Visit the integrations homepage if you are looking for more information on Webchat 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 Send a POST /chat/create request with:
    • a unique user_id (UUID recommended)
    • an optional message (can be an empty string)
    • an empty or populated metadata object
    The response includes a conversation_id and the assistant’s initial message.
  2. Send and receive messages Use POST /chat/respond with the conversation_id and a message. The response includes the assistant’s reply and an optional end_conversation flag.

​
Endpoints

​
Base URLs

The Chat API is available in the following regions:
RegionBase URL
UShttps://api.us-1.platform.polyai.app
UKhttps://api.uk-1.platform.polyai.app
EU-Whttps://api.euw-1.platform.polyai.app
Endpoint format: /v1/{account_id}/{project_id}/chat/{operation}
  • account_id: Your PolyAI account ID (e.g. poly-scs-uk)
  • project_id: Your PolyAI project ID (e.g. PROJECT-191bfa2a)
  • operation: Either create or respond

​
Authentication

All requests must include the following headers:
HeaderDescription
X-Api-KeyYour API key for PolyAI
X-TokenA token identifying the agent (connector token)
Content-TypeMust be application/json

​
Example: Create Chat

POST /v1/poly-scs-uk/PROJECT-191bfa2a/chat/create Body: 
   {
     "user_id": "71c21b7c-5fa3-4c0d-bd4f-5ef0a7641b84",
     "message": "",
     "metadata": {}
   }
Response: 

    {
      "conversation_id": "WEBCHAT_abc123def456",
      "response": "Hi, how can I help you today?"
    }

​
Example: Send Message

POST /v1/poly-scs-uk/PROJECT-191bfa2a/chat/respond Body: 

    {
      "conversation_id": "WEBCHAT_abc123def456",
      "message": "What's your return policy?"
    }
Response: 
    {
      "response": "Our return policy is 30 days with proof of purchase.",
      "end_conversation": false
    }

​
Notes

  • user_id must be unique per session. Use uuid.uuid4() to generate it safely.
  • conversation_id must match the ID returned by the /chat/create endpoint.
  • end_conversation indicates the assistant has concluded the session.
  • All fields in the request bodies are required (even if some are empty).