Chat API

Documentation Index

Fetch the complete documentation index at: https://docs.poly.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

• 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

​

Example: Create chat

curl -X POST \
  "https://api.us-1.platform.polyai.app/v1/ACCOUNT-xxx/PROJECT-xxx/chat/create" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variant_id": "VARIANT-xxxxxxxx",
    "integration_attributes": {
      "user_id": "12345",
      "customer_tier": "premium"
    }
  }'

{
  "conversation_id": "CONV-1234567890",
  "response": "Hi, how can I help you today?"
}

​

Example: Send message

curl -X POST \
  "https://api.us-1.platform.polyai.app/v1/ACCOUNT-xxx/PROJECT-xxx/chat/respond" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "CONV-1234567890",
    "message": "What'\''s your return policy?"
  }'

{
  "conversation_id": "CONV-1234567890",
  "response": "Our return policy is 30 days with proof of purchase.",
  "end_conversation": false
}

{
  "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

curl -X PUT \
  "https://api.us-1.platform.polyai.app/v1/ACCOUNT-xxx/PROJECT-xxx/chat/close" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": "CONV-1234567890"}'

{
  "success": true
}

​

Passing custom data with 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?"

​

Targeting a variant with variant_id

{
  "variant_id": "VARIANT-xxxxxxxx"
}

​

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.