Client events | PolyAI Platform

Your client can send the following five event types. Any other type is rejected with an EVENT_TYPE_SYSTEM_MESSAGE error.

`EVENT_TYPE_REQUEST_POLY_AGENT_JOIN`

Requests the PolyAI agent to join the session. You must send this to start the conversation.

{
  "type": "EVENT_TYPE_REQUEST_POLY_AGENT_JOIN",
  "payload": {}
}

After sending this, you receive (in order):

An echo of your event
EVENT_TYPE_POLY_AGENT_JOINED — the agent has joined
EVENT_TYPE_POLY_AGENT_THINKING — the agent is preparing its greeting
EVENT_TYPE_POLY_AGENT_MESSAGE (or chunks, if streaming) — the greeting message

Send a text message from the user.

{
  "type": "EVENT_TYPE_USER_MESSAGE",
  "payload": {
    "text": "I'd like to book a table for tomorrow at 7pm."
  }
}

Field	Type	Required	Description
`text`	string	Yes	The message text

The server echoes this back with a server-assigned message_id added to the payload.

Notify the server that the user is typing (or has stopped). Use this to show typing indicators on the live agent side.

{
  "type": "EVENT_TYPE_USER_TYPING",
  "payload": {
    "state": "TYPING_STATE_STARTED"
  }
}

Field	Type	Values
`state`	string	`TYPING_STATE_STARTED` or `TYPING_STATE_STOPPED`

Send when the user deliberately ends the conversation (e.g. clicks a “Leave” button).

{
  "type": "EVENT_TYPE_USER_END_SESSION",
  "payload": {}
}

This triggers a clean shutdown: the server echoes the event, then sends EVENT_TYPE_SESSION_END with reason REASON_USER_END.

Keeps the WebSocket alive. Send at regular intervals (typically every 30 seconds). The server echoes it back.

{
  "type": "EVENT_TYPE_HEARTBEAT",
  "payload": {}
}