Chat API

Use the PolyAI Chat API to power Webchat.

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 Webchat 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 powers webchat integrations including in-browser widgets, web SDK implementations, and SMS.

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 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.

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 agent’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

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 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):

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

Body (optional)

{
  "variant_id": "VARIANT-xxxxxxxx",
  "integration_attributes": {
    "user_id": "12345",
    "session_id": "abc-123-def",
    "customer_tier": "premium"
  }
}

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
}

Passing custom data with integration_attributes

The integration_attributes field allows you to pass custom data when creating a chat. These attributes are accessible in your project functions via 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.