Skip to main content
Visit the web chat homepage if you are looking for more information on chat integrations.
Use the Chat API to integrate PolyAI agents into existing systems, and use its endpoints to get programmatic access to automated chat interactions. This API structures non-voice web conversations, messages, and chat sessions using a simple set of REST endpoints. The Chat API can power multiple Webchat integrations, including WhatsApp, email, and in-app widgets.

​
Chatting with the API

  1. Start a conversation Call POST /{version}/{account_id}/{project_id}/chat/create. The response includes a conversation_id and the assistant’s initial response.
    Per current schema, this endpoint has no request body.
  2. Send and receive messages Call POST /{version}/{account_id}/{project_id}/chat/respond with the conversation_id. message is optional. The response includes the assistant’s response, an end_conversation flag, and may include a handoff object.
  3. 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

RegionBase URL
UShttps://api.us-1.platform.polyai.app
UKhttps://api.uk-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 ACCOUNT-xxxxxxx)
  • project_id: Your PolyAI project ID (for example PROJECT-191bfa2a)
  • operation: create, respond, or close

​
Authentication

All requests must include the following headers (case-sensitive):
HeaderDescription
X-API-KEYYour API key for PolyAI
X-TOKENAgent authentication token (connector)
Content-TypeMust be application/json

​
Example: Create chat

POST /v1/poly-scs-uk/PROJECT-191bfa2a/chat/create Response 
{
  "conversation_id": "CONV-1234567890",
  "response": "Hi, how can I help you today?"
}

​
Example: Send message

POST /v1/poly-scs-uk/PROJECT-191bfa2a/chat/respond Body 
{
  "conversation_id": "CONV-1234567890",
  "message": "What's your return policy?"
}
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/poly-scs-uk/PROJECT-191bfa2a/chat/close Body 
{
  "conversation_id": "CONV-1234567890"
}
Response 
{
  "success": true
}

​
Notes

  • create has no request body in the current schema.
  • 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.