Messaging API

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

https://messaging.poly.ai

For cluster-specific deployments, the pattern is https://messaging.<cluster>.poly.ai:

Cluster	Base URL	Description
`us-1`	`https://messaging.us-1.poly.ai`	US Mainland
`uk-1`	`https://messaging.uk-1.poly.ai`	UK
`euw-1`	`https://messaging.euw-1.poly.ai`	EU West

Your PolyAI contact will confirm which base URL to use.

Prerequisites

Before integrating, you need two values:

Value	What it is	Where to find it
Connector token	A secret token that identifies your integration	Provisioned by PolyAI — contact your PolyAI representative to request one
Host identifier	The domain (e.g. `https://www.yourcompany.com`) or app namespace (e.g. `com.yourcompany.app`) registered against the connector token	Set when the token is provisioned. The server rejects requests where `X-Host` doesn’t match.

The self-serve Messaging → API Configuration page in Agent Studio is not fully built out yet. For now, your PolyAI representative will provision a connector token and register the host identifier on your behalf.

If you already have a PolyAI webchat widget configured, you can reuse its credentials:

Connector token: the value between the last / and .js in the widget embed script URL.
Host identifier: the same domain you set in the widget configuration.

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:

Obtain an access token

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

Create a session

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

Open a WebSocket connection

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

Request the agent to join

Send EVENT_TYPE_REQUEST_POLY_AGENT_JOIN to start the conversation.

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 API	Chat API
Protocol	WebSocket (real-time, event-driven)	REST (turn-based request/response)
Streaming responses	Yes (incremental chunks)	No
Typing indicators	Yes	No
Live-agent handoff	Yes (full event flow over the WebSocket)	Yes (via `handoff` in the respond response)
Reconnection / history replay	Built-in (`cursor` query param)	Client manages turns
Auth	Connector token + host domain → short-lived JWT	API key + connector token
Best for	Web apps, iOS/Android apps, custom SDKs	SMS, 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

API reference

Build & deploy

Runtime & data

Monitoring

Legacy

Base URL

Prerequisites

Getting started

Minimal JavaScript example

Messaging API vs Chat API

Reference

Sessions and authentication

WebSocket connection

Event format

Client events

Server events

Streaming

Handoff to live agent

Session lifecycle

Errors

Best practices

​Base URL

​Prerequisites

​Getting started

​Minimal JavaScript example

​Messaging API vs Chat API

​Reference

Sessions and authentication

WebSocket connection

Event format

Client events

Server events

Streaming

Handoff to live agent

Session lifecycle

Errors

Best practices

Base URL

Prerequisites

Getting started

Minimal JavaScript example

Messaging API vs Chat API

Reference