Server events

The server sends these events to your client. Group them into four categories: PolyAI agent, live agent, handoff, and system.

PolyAI agent events

EVENT_TYPE_POLY_AGENT_JOINED

The PolyAI agent has joined the session. Sent in response to your REQUEST_POLY_AGENT_JOIN.

{
  "payload": {
    "agent_name": "Ada",
    "agent_avatar_url": "https://example.com/avatars/ada.png"
  }
}

EVENT_TYPE_POLY_AGENT_THINKING

The agent is composing a response. Show a typing indicator in your UI.

{ "payload": {} }

EVENT_TYPE_POLY_AGENT_MESSAGE

A complete message from the agent. Sent when streaming_enabled is false.

{
  "payload": {
    "message_id": "msg_abc123",
    "text": "I'd be happy to help you book a table! What restaurant are you interested in?",
    "attachments": [
      {
        "title": "Our locations",
        "preview_image_url": "https://example.com/thumb.png",
        "content_url": "https://example.com/locations",
        "content_type": "ATTACHMENT_CONTENT_TYPE_URL",
        "call_to_action_text": "View locations"
      }
    ],
    "response_suggestions": [
      { "message_text": "The Italian place on Main Street" },
      { "message_text": "Show me all available restaurants" }
    ]
  }
}

EVENT_TYPE_POLY_AGENT_LEFT

The agent has left the session (typically before a handoff to a live agent).

{ "payload": {} }

EVENT_TYPE_POLY_AGENT_TRIGGERED_HANDOFF

The agent has determined a human should take over. Handoff events follow — see Handoff.

{ "payload": {} }

Live agent events

When a conversation is handed off to a human, you receive these events:

EVENT_TYPE_LIVE_AGENT_JOINED

A human agent has connected to the conversation.

{
  "payload": {
    "agent": {
      "id": "agent_42",
      "name": "Sarah",
      "avatar_url": "https://example.com/avatars/sarah.png"
    }
  }
}

EVENT_TYPE_LIVE_AGENT_TYPING

The human agent is typing.

{
  "payload": {
    "state": "TYPING_STATE_STARTED",
    "agent_id": "agent_42"
  }
}

EVENT_TYPE_LIVE_AGENT_MESSAGE

A message from the human agent. Same structure as agent messages, plus an agent_id.

{
  "payload": {
    "message_id": "msg_live_789",
    "agent_id": "agent_42",
    "text": "Hi! I can see your booking request. Let me check availability.",
    "attachments": [],
    "response_suggestions": []
  }
}

EVENT_TYPE_LIVE_AGENT_LEFT

The human agent has left the session.

{ "payload": {} }

Handoff events

These events track the transition from the PolyAI agent to a human agent. See Handoff for the full flow.

EVENT_TYPE_HANDOFF_ACCEPTED

The live agent system accepted the handoff. The user may be placed in a queue.

{ "payload": {} }

EVENT_TYPE_HANDOFF_QUEUE_STATUS

Periodic updates while the user is waiting. Show in your UI (e.g. “You are #3 in the queue”).

{
  "payload": {
    "queue_name": "General Support",
    "position_in_queue": 3,
    "estimated_wait_seconds": 180
  }
}

All fields are optional — not all live agent systems provide queue position data.

EVENT_TYPE_CLIENT_HANDOFF_REQUIRED

The server cannot handle the handoff automatically and needs your client to take action (e.g. redirect to a different channel or open a third-party widget).

{
  "payload": {
    "reason": "COMPLEX_QUERY",
    "queue_name": "Support Queue"
  }
}

EVENT_TYPE_HANDOFF_FAILED

The handoff could not be completed (e.g. the live agent system is unavailable).

{ "payload": {} }

EVENT_TYPE_HANDOFF_TIMEOUT

The user waited too long in the queue without being connected.

{ "payload": {} }

System events

EVENT_TYPE_SESSION_START

Sent as part of the history replay when the WebSocket connects. Describes session capabilities.

{
  "payload": {
    "capabilities": {
      "streaming": true,
      "max_message_size_bytes": 131072,
      "max_reconnect_attempts": 5,
      "heartbeat_interval_seconds": 30
    }
  }
}

EVENT_TYPE_SESSION_END

The session has ended. After this, no further events will be sent. Close the WebSocket.

{
  "payload": {
    "reason": "REASON_USER_END"
  }
}

EVENT_TYPE_SYSTEM_MESSAGE

A system-level notification — usually an error in response to an invalid event you sent. See Errors for the full catalog.

{
  "payload": {
    "level": "SYSTEM_MESSAGE_LEVEL_ERROR",
    "message": "Event type not allowed: EVENT_TYPE_POLY_AGENT_MESSAGE"
  }
}

EVENT_TYPE_LANGUAGE_CHANGED

The PolyAI agent has detected the conversation has switched language. Use this to update your UI locale (for example, swap response suggestion translations, adjust input direction, or relabel controls).

{
  "payload": {
    "language_code": "fr-FR"
  }
}

The event is journaled and replayed on reconnect, so your client may receive it more than once. It is idempotent — it carries the absolute language code, not a delta — so just apply the latest value you see.

EVENT_TYPE_EVENT_BATCH

A batch of historical events, sent during connection replay. Contains an array of events in chronological order.

{
  "payload": {
    "events": [
      { "id": "...", "sequence": 1, "type": "EVENT_TYPE_SESSION_START", "payload": {} },
      { "id": "...", "sequence": 2, "type": "EVENT_TYPE_POLY_AGENT_MESSAGE", "payload": {} }
    ]
  }
}

Flatten the events array into your local event list, using sequence for ordering and id for deduplication.

Attachments

Attachments are rich content items in agent or live agent messages — typically links or images.

{
  "title": "Our Locations",
  "preview_image_url": "https://example.com/thumb.png",
  "content_url": "https://example.com/locations",
  "content_type": "ATTACHMENT_CONTENT_TYPE_URL",
  "call_to_action_text": "View locations"
}