Skip to navigation
Runtime & dataMessaging API

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:

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 base URL to use.

Prerequisites

Before integrating, you need two values:

ValueWhat it isWhere to find it
Connector tokenA secret token that identifies your integrationProvisioned by PolyAI — contact your PolyAI representative to request one
Host identifierThe domain (e.g. https://www.yourcompany.com) or app namespace (e.g. com.yourcompany.app) registered against the connector tokenSet 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:

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