For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Send heartbeats regularly. Use the interval from capabilities.heartbeat_interval_seconds in the SESSION_START event (fall back to 30 seconds). Without heartbeats, the session times out after 10 minutes.
Implement reconnection with backoff. Connections can drop due to network issues or server-side timeouts. Reconnect with exponential backoff (start at 1 second, cap at 30 seconds) using the same session_id and a cursor set to your last seen sequence.
Don’t create a new session on reconnect. Reuse the existing session_id to preserve the conversation. Only create a new session for a genuinely new conversation.
Message handling
Deduplicate by id. The same event may arrive more than once — during replay after a reconnect, or if replay and live delivery overlap. Use the event id to detect duplicates.
Order by sequence. Events may arrive out of order during reconnection. Sort by sequence for display.
Flatten EVENT_TYPE_EVENT_BATCH. On connect, the server sends history as batch events. Extract the events array into your local event list.
Process streaming chunks in order. Accumulate chunks by message_id in chunk_index order. The message is complete when is_complete is true.
User experience
Show typing indicators. Display when you receive POLY_AGENT_THINKING or LIVE_AGENT_TYPING. Clear when the message arrives.
Show response suggestions as buttons. When a message includes response_suggestions, display them as tappable buttons. When tapped, send the suggestion’s message_text as a USER_MESSAGE.
Handle handoff gracefully. Inform the user they’re being connected to a human agent. Show queue status updates if available.
Handle session end. When you receive SESSION_END, disable the message input and show an appropriate message based on the reason.
Security
Treat the access token as sensitive. Do not log it, store it in localStorage, or expose it to third-party scripts. It is passed as a WebSocket query parameter — ensure connections use wss:// (TLS).
Tokens are short-lived. Obtain a fresh token for each new session. Do not cache tokens across sessions.
Never embed your connector token in client-side code. The connector token must be kept on a trusted backend that mints access tokens for your clients. Exposing it lets anyone create sessions against your project.
