Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.poly.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Messaging API lets you embed real-time text conversations into your application. End users chat with a PolyAI agent, and the conversation can be handed off to a live human agent inside the same session when needed. Communication happens over a WebSocket connection after a short HTTP handshake. All messages are JSON-encoded events.
The Messaging API is a real-time, event-driven protocol. If you only need simple turn-based request/response (for example for SMS), use the Chat API instead. See Messaging API vs Chat API below.

​
Base URL

Each region has its own cluster-specific host:
ClusterBase URLDescription
us-1https://messaging.us-1.poly.aiUS Mainland
uk-1https://messaging.uk-1.poly.aiUK
euw-1https://messaging.euw-1.poly.aiEU West
Your PolyAI contact will confirm which cluster your project is deployed in. There is no region-agnostic alias — you must use the cluster URL that matches your project.

​
Prerequisites

Before integrating, you need two values, both generated when you create a webchat widget in Agent Studio under Channels → Chat → Widget:
ValueWhat it isWhere to find it
Connector tokenA secret token that identifies your integrationGenerated automatically when you create a widget in Agent Studio
Host identifierThe domain (e.g. https://www.yourcompany.com) or app namespace (e.g. com.yourcompany.app) you registered when generating the tokenSet as the host domain when creating the widget. The server rejects requests where X-Host doesn’t match.
Subdomains are matched against the registered host — for example, a connector registered to yourcompany.com accepts requests from app.yourcompany.com.

​
Getting started

Every conversation follows this sequence:
1

Obtain an access token

POST /api/v1/access-token with your connector token. Returns a short-lived JWT.
2

Create a session

POST /api/v1/sessions with the access token. Returns a session_id.
3

Open a WebSocket connection

wss://<base-url>/ws?access_token=...&session_id=...
4

Request the agent to join

Send EVENT_TYPE_REQUEST_POLY_AGENT_JOIN to start the conversation.
5

Exchange messages

Send and receive events over the WebSocket.
The PolyAI agent does not join the session automatically. On a new session, after opening the WebSocket and receiving the session history, your client must explicitly send EVENT_TYPE_REQUEST_POLY_AGENT_JOIN to start the conversation. On a reconnect to an existing session, the agent has already joined — check the replayed history for EVENT_TYPE_POLY_AGENT_JOINED and skip the join request if present.

​
Minimal JavaScript example

// 1. Get an access token
const tokenRes = await fetch("https://messaging.us-1.poly.ai/api/v1/access-token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Token": "<your-connector-token>",
    "X-Host": "https://www.yourcompany.com",
  },
  body: "{}",
});
const { access_token } = await tokenRes.json();

// 2. Create a session
const sessionRes = await fetch("https://messaging.us-1.poly.ai/api/v1/sessions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${access_token}`,
  },
  body: JSON.stringify({ streaming_enabled: false }),
});
const { session_id } = await sessionRes.json();

// 3. Open the WebSocket
const ws = new WebSocket(
  `wss://messaging.us-1.poly.ai/ws?session_id=${session_id}&access_token=${access_token}`
);

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg.type, msg.payload);
};

ws.onopen = () => {
  // Wait for EVENT_TYPE_EVENT_BATCH (history replay), then:

  // 4. Request the agent to join
  ws.send(JSON.stringify({
    type: "EVENT_TYPE_REQUEST_POLY_AGENT_JOIN",
    payload: {},
  }));
};

​
Messaging API vs Chat API

PolyAI offers two APIs for non-voice channels. Pick the one that matches your integration model.
Messaging APIChat API
ProtocolWebSocket (real-time, event-driven)REST (turn-based request/response)
Streaming responsesYes (incremental chunks)No
Typing indicatorsYesNo
Live-agent handoffYes (full event flow over the WebSocket)Yes (via handoff in the respond response)
Reconnection / history replayBuilt-in (cursor query param)Client manages turns
AuthConnector token + host domain → short-lived JWTAPI key + connector token
Best forWeb apps, iOS/Android apps, custom SDKsSMS, server-to-server, simple webchat

​
Reference

Sessions and authentication

Obtain an access token and create a session

WebSocket connection

Connect, reconnect, and keep the connection alive

Event format

Common envelope, echo behavior, delivery receipts

Client events

Events your client can send

Server events

Events your client receives

Streaming

Receive agent responses as incremental chunks

Handoff to live agent

Server-managed and client-managed handoff flows

Session lifecycle

Every event in order, from connect to session end

Errors

HTTP codes and system-message error catalog

Best practices

Connection management, dedup, ordering, UX, security
Last modified on May 19, 2026