Sessions

Persistent WebSocket endpoint for low-latency text conversations with streamed agent responses.

The Sessions API provides endpoints for managing text-based agent sessions. The persistent WebSocket endpoint replaces per-turn HTTP round-trips with a single connection, reducing turn latency to a few seconds after the initial handshake.

WebSocket Connect

Endpoint: wss://api.platform.amigo.ai/v1/{workspace_id}/sessions/connect

Opens a persistent WebSocket connection for a text conversation.

Query Parameters

Parameter	Type	Required	Description
service_id	string (UUID)	Yes	The service to converse with
entity_id	string (UUID)	Yes	The entity (patient/contact) for this session
tool_events	boolean	No	Include tool execution events in the response stream. Default: false

Authentication

Authenticate using the Sec-WebSocket-Protocol header with two comma-separated values:

Sec-WebSocket-Protocol: auth, <api_key_or_jwt>

The first value is the literal string auth. The second value is your API key or JWT access token. The server accepts the connection with auth as the negotiated subprotocol.

Connection Lifecycle

1. Connect - Client opens the WebSocket with query parameters and auth header.

2. Session created - Server sends a session.created event with the resolved conversation_id, entity_id, and service_id.

3. Greeting - Server sends the agent's auto-greeting as a stream of turn events.

4. Message loop - Client sends user_text messages; server responds with turn event streams.

5. Close - Either side closes the connection. The server closes on idle timeout.

Client Messages

Clients send JSON text frames with the following format:

{
  "type": "user_text",
  "text": "I need to reschedule my appointment"
}

Field	Type	Required	Description
type	string	Yes	Must be user_text
text	string	Yes	The user's message. Must be between 1 and 10,000 characters.

Server Events

The server sends JSON text frames. Each frame has an event field and a data object.

session.created

Sent immediately after connection is accepted.

{
  "event": "session.created",
  "data": {
    "conversation_id": "conv-uuid",
    "entity_id": "entity-uuid",
    "service_id": "service-uuid"
  }
}

Turn stream events

After the greeting and after each user_text message, the server sends a stream of turn events. These are the same event types used in the streaming text session HTTP endpoint - including transcript chunks, tool calls (when tool_events=true), and turn completion markers.

error

Sent when an error occurs during a turn. The connection remains open unless the error is fatal.

{
  "event": "error",
  "data": {
    "message": "Description of the error",
    "code": "error_code",
    "retryable": true
  }
}

Error Code	Description	Retryable
client_error	Invalid message format, unknown type, missing text, or text too long	No
upstream_error	Agent engine returned an error	Depends on status
stream_interrupted	Connection to agent engine was interrupted	Yes
turn_timeout	Agent did not complete the turn within the allowed time	Yes
idle_timeout	No messages received within the idle window	Yes

Close Codes

The server uses custom close codes to indicate why the connection was closed before or shortly after acceptance:

Code	Reason
4000	Invalid request parameters (workspace ID, service ID, entity ID format, or missing required parameters)
4001	Authentication failed (missing, invalid, or expired credentials)
4004	Resource not found (workspace inactive, service not found, entity not found)
4503	Service temporarily unavailable (agent engine down, session creation timed out)

Thread Resolution

The platform automatically resolves or creates a conversation thread for each unique combination of entity and service. If a prior WebSocket session used the same entity and service, the new session continues the existing conversation. This means clients can disconnect and reconnect without losing conversation history.

Example

const ws = new WebSocket(
  'wss://api.platform.amigo.ai/v1/{workspace_id}/sessions/connect?service_id={service_id}&entity_id={entity_id}&tool_events=true',
  ['auth', 'your-api-key']
);

ws.onmessage = (event) => {
  const frame = JSON.parse(event.data);
  switch (frame.event) {
    case 'session.created':
      console.log('Session started:', frame.data.conversation_id);
      break;
    case 'error':
      console.error(frame.data.message, frame.data.code);
      break;
    default:
      // Handle turn stream events (transcript chunks, tool calls, etc.)
      console.log(frame.event, frame.data);
  }
};

// Send a message
ws.send(JSON.stringify({ type: 'user_text', text: 'Hello' }));