Visit the web chat homepage if you are looking for more information on chat integrations.
Chatting with the API
-
Start a conversation
Call
POST /{version}/{account_id}/{project_id}/chat/create. The response includes aconversation_idand the assistant’s initialresponse.Per current schema, this endpoint has no request body.
-
Send and receive messages
Call
POST /{version}/{account_id}/{project_id}/chat/respondwith theconversation_id.messageis optional. The response includes the assistant’sresponse, anend_conversationflag, and may include ahandoffobject. -
Close a conversation
Call
PUT /{version}/{account_id}/{project_id}/chat/closewith theconversation_idin 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 |
/{version}/{account_id}/{project_id}/chat/{operation}
version: API version (for examplev1)account_id: Your PolyAI account ID (for examplepoly-scs-ukorACCOUNT-xxxxxxx)project_id: Your PolyAI project ID (for examplePROJECT-191bfa2a)operation:create,respond, orclose
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 |
Example: Create chat
POST/v1/poly-scs-uk/PROJECT-191bfa2a/chat/create
Response
Example: Send message
POST/v1/poly-scs-uk/PROJECT-191bfa2a/chat/respond
Body
Example: Close chat
PUT/v1/poly-scs-uk/PROJECT-191bfa2a/chat/close
Body
Notes
createhas no request body in the current schema.respondrequiresconversation_id;messageis optional.handoffmay appear in therespondresponse withdestinationandreason.closerequires a JSON body containingconversation_id.- Header names are case-sensitive:
X-API-KEY,X-TOKEN. - Use the regional base URL closest to your deployment.

