Chat API

Use the Chat API to integrate PolyAI agents into non-voice channels. It provides a simple set of REST endpoints for starting conversations, sending and receiving messages, and handling handoffs–ideal for webchat widgets, web SDKs, and SMS platforms. The Chat API powers webchat integrations including in-browser widgets, web SDK implementations, and SMS.

If you need real-time streaming responses, typing indicators, or in-session live-agent handoff events over a persistent connection, use the Messaging API instead. See Messaging API vs Chat API for guidance on choosing.

Chatting with the API

Start a conversation Call POST /{version}/{account_id}/{project_id}/chat/create. The response includes a conversation_id and the agent’s initial response. You can optionally pass integration_attributes to provide custom context to the agent, and variant_id to target a specific variant.
Send and receive messages Call POST /{version}/{account_id}/{project_id}/chat/respond with the conversation_id. message is optional. The response includes the agent’s response, an end_conversation flag, and may include a handoff object.
Close a conversation Call PUT /{version}/{account_id}/{project_id}/chat/close with the conversation_id in the body. The response returns { "success": true } on success.

Endpoints

Base URLs

Region	Base URL
US	https://api.us-1.platform.polyai.app
UK	https://api.uk-1.platform.polyai.app
EUW	https://api.euw-1.platform.polyai.app

Endpoint format: /{version}/{account_id}/{project_id}/chat/{operation}

version: API version (for example v1)
account_id: Your PolyAI account ID (for example poly-scs-uk or ws-xxxxxxxx)
project_id: Your PolyAI project ID (for example PROJECT-191bfa2a)
operation: create, respond, or close

Finding your `account_id` and `project_id`

Your account_id and project_id are the first two path segments of your Agent Studio URL, immediately after the host:

https://studio.<region>.poly.ai/<account_id>/<project_id>/...

Agent Studio is region-specific. Each Studio host serves one region and pairs with the matching API host. Replace <region> with the subdomain for your tenant:

Studio URL	API host
`https://studio.us.poly.ai`	`https://api.us-1.platform.polyai.app`
`https://studio.uk.poly.ai`	`https://api.uk-1.platform.polyai.app`
`https://studio.eu.poly.ai`	`https://api.euw-1.platform.polyai.app`
`https://studio.poly.ai`	`https://api.studio.poly.ai` (self-serve)

A workspace lives in exactly one region — log in to the Studio host for that region and call the matching API host.

For example, if your Studio URL is https://studio.uk.poly.ai/acme-uk/acme-team-4/agent, then:

<region> = uk (so calls go to api.uk-1.platform.polyai.app)
account_id = acme-uk
project_id = acme-team-4

Account and project identifiers are also shown in prefixed form in Agent Studio — both the slug form (visible in the URL) and the prefixed form are accepted in API paths:

Path parameter	Slug form (from URL)	Prefixed form (shown in Agent Studio as Workspace ID / Agent ID)
`account_id`	`acme-uk`	`ws-xxxxxxxx` (for example `ws-fd112d8f`)
`project_id`	`acme-team-4`	`PROJECT-xxxxxxxx`

The account_id path parameter is shown as Workspace ID in Agent Studio and uses a ws- prefix — not ACCOUNT-. Older docs may still call it ACCOUNT-xxxxxxx; the value you see in Agent Studio (prefixed with ws-) is the correct one to use. If you only have the prefixed form, your PolyAI representative can confirm the matching slug.

The same IDs are exposed inside Agent Studio functions as conv.account_id and conv.project_id — see the Conversation object reference.

Authentication

All requests must include the following headers (case-sensitive):

Header	Description
`X-API-KEY`	Your API key for PolyAI
`X-TOKEN`	Agent authentication token (connector)
`Content-Type`	Must be `application/json`

Getting your credentials

Both X-API-KEY and X-TOKEN are provisioned by PolyAI — there is no self-serve endpoint to create a Chat API connector or generate a connector token. To request access, contact your PolyAI representative with:

Your account_id
Your project_id
The client environment you need (live, pre-release, or sandbox)
Your variant_id (optional, only if targeting a specific variant)

PolyAI will provision a Chat API connector for your project and return:

An API key to use in the X-API-KEY header
A connector token to use in the X-TOKEN header

The Chat API connector is distinct from the voice/telephony connectors managed under the Agents API. You do not need SIP details, phone numbers, or language codes to provision a Chat API connector.

Example: Create chat

POST /v1/{account_id}/{project_id}/chat/create

curl -X POST \
  "https://api.<region>.platform.polyai.app/v1/ws-xxxxxxxx/PROJECT-xxx/chat/create" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variant_id": "VARIANT-xxxxxxxx",
    "integration_attributes": {
      "user_id": "12345",
      "customer_tier": "premium"
    }
  }'

import requests

base_url = "https://api.<region>.platform.polyai.app"
headers = {
    "X-API-KEY": "YOUR_API_KEY",
    "X-TOKEN": "YOUR_TOKEN",
    "Content-Type": "application/json",
}

response = requests.post(
    f"{base_url}/v1/ws-xxxxxxxx/PROJECT-xxx/chat/create",
    headers=headers,
    json={
        "variant_id": "VARIANT-xxxxxxxx",
        "integration_attributes": {
            "user_id": "12345",
            "customer_tier": "premium",
        },
    },
)
data = response.json()
conversation_id = data["conversation_id"]
print(data["response"])

const baseUrl = "https://api.<region>.platform.polyai.app";
const headers = {
  "X-API-KEY": "YOUR_API_KEY",
  "X-TOKEN": "YOUR_TOKEN",
  "Content-Type": "application/json",
};

const res = await fetch(
  `${baseUrl}/v1/ws-xxxxxxxx/PROJECT-xxx/chat/create`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      variant_id: "VARIANT-xxxxxxxx",
      integration_attributes: {
        user_id: "12345",
        customer_tier: "premium",
      },
    }),
  }
);
const data = await res.json();
const conversationId = data.conversation_id;
console.log(data.response);

Response

{
  "conversation_id": "CONV-1234567890",
  "response": "Hi, how can I help you today?"
}

Example: Send message

POST /v1/{account_id}/{project_id}/chat/respond

curl -X POST \
  "https://api.<region>.platform.polyai.app/v1/ws-xxxxxxxx/PROJECT-xxx/chat/respond" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "CONV-1234567890",
    "message": "What'\''s your return policy?"
  }'

response = requests.post(
    f"{base_url}/v1/ws-xxxxxxxx/PROJECT-xxx/chat/respond",
    headers=headers,
    json={
        "conversation_id": "CONV-1234567890",
        "message": "What's your return policy?",
    },
)
data = response.json()
print(data["response"])

if data.get("end_conversation"):
    print("Conversation ended")
if data.get("handoff"):
    print(f"Handoff to: {data['handoff']['destination']}")

const respondRes = await fetch(
  `${baseUrl}/v1/ws-xxxxxxxx/PROJECT-xxx/chat/respond`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      conversation_id: "CONV-1234567890",
      message: "What's your return policy?",
    }),
  }
);
const respondData = await respondRes.json();
console.log(respondData.response);

if (respondData.end_conversation) {
  console.log("Conversation ended");
}
if (respondData.handoff) {
  console.log(`Handoff to: ${respondData.handoff.destination}`);
}

Response

{
  "conversation_id": "CONV-1234567890",
  "response": "Our return policy is 30 days with proof of purchase.",
  "end_conversation": false
}

Response with handoff

{
  "conversation_id": "CONV-1234567890",
  "response": "Transferring you to a live agent.",
  "end_conversation": true,
  "handoff": {
    "destination": "live_agent_queue",
    "reason": "billing_question"
  }
}

Example: Close chat

PUT /v1/{account_id}/{project_id}/chat/close

curl -X PUT \
  "https://api.<region>.platform.polyai.app/v1/ws-xxxxxxxx/PROJECT-xxx/chat/close" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": "CONV-1234567890"}'

response = requests.put(
    f"{base_url}/v1/ws-xxxxxxxx/PROJECT-xxx/chat/close",
    headers=headers,
    json={"conversation_id": "CONV-1234567890"},
)
print(response.json())

const closeRes = await fetch(
  `${baseUrl}/v1/ws-xxxxxxxx/PROJECT-xxx/chat/close`,
  {
    method: "PUT",
    headers,
    body: JSON.stringify({
      conversation_id: "CONV-1234567890",
    }),
  }
);
const closeData = await closeRes.json();
console.log(closeData);

Response

{
  "success": true
}

Passing custom data with `integration_attributes`

The integration_attributes field lets you pass custom data when creating a chat. These attributes are accessible in your project functions at conv.integration_attributes.

When to use

Pass user context (user ID, session ID, authentication status)
Include customer information (tier, preferences, history)
Send external system references (CRM ID, ticket number)
Provide A/B test parameters or feature flags

Accessing in project functions

def start(conv):
    # Get integration attributes (always check for None)
    attrs = conv.integration_attributes or {}
    
    user_id = attrs.get("user_id")
    customer_tier = attrs.get("customer_tier", "standard")
    
    # Store in state for use throughout the conversation
    if user_id:
        conv.state.user_id = user_id
    
    # Customize greeting based on tier
    if customer_tier == "premium":
        return "Welcome back! As a premium member, how can I assist you today?"
    return "Hello! How can I help you?"

Pass integration_attributes when creating the chat. They’re set on the first turn and available throughout the conversation. Store values in conv.state to access them in later turns.

Targeting a variant with `variant_id`

Pass variant_id in the create request body to route the conversation to a specific variant. This is useful for multi-site deployments where different variants serve different brands, languages, or regions.

{
  "variant_id": "VARIANT-xxxxxxxx"
}

variant_id is only accepted on POST /chat/create. It cannot be changed after the conversation starts.

Notes

create accepts an optional request body with variant_id and integration_attributes.
respond requires conversation_id; message is optional.
handoff may appear in the respond response with destination and reason.
close requires a JSON body containing conversation_id.
Header names are case-sensitive: X-API-KEY, X-TOKEN.
Use the regional base URL closest to your deployment.

API reference

Build & deploy

Runtime & data

Monitoring

Legacy

Chatting with the API

Endpoints

Base URLs

Finding your `account_id` and `project_id`

Authentication

Getting your credentials

Example: Create chat

Example: Send message

Example: Close chat

Passing custom data with `integration_attributes`

When to use

Accessing in project functions

Targeting a variant with `variant_id`

Notes

​Chatting with the API

​Endpoints

​Base URLs

​Finding your account_id and project_id

​Authentication

​Getting your credentials

​Example: Create chat

​Example: Send message

​Example: Close chat

​Passing custom data with integration_attributes

​When to use

​Accessing in project functions

​Targeting a variant with variant_id

​Notes

Chatting with the API

Endpoints

Base URLs

Finding your `account_id` and `project_id`

Authentication

Getting your credentials

Example: Create chat

Example: Send message

Example: Close chat

Passing custom data with `integration_attributes`

When to use

Accessing in project functions

Targeting a variant with `variant_id`

Notes