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_id
and 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/respond
with theconversation_id
.message
is optional. The response includes the assistant’sresponse
, anend_conversation
flag, and may include ahandoff
object. -
Close a conversation
Call
PUT /{version}/{account_id}/{project_id}/chat/close
with theconversation_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 |
/{version}/{account_id}/{project_id}/chat/{operation}
version
: API version (for examplev1
)account_id
: Your PolyAI account ID (for examplepoly-scs-uk
orACCOUNT-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
create
has no request body in the current schema.respond
requiresconversation_id
;message
is optional.handoff
may appear in therespond
response withdestination
andreason
.close
requires a JSON body containingconversation_id
.- Header names are case-sensitive:
X-API-KEY
,X-TOKEN
. - Use the regional base URL closest to your deployment.