Respond to a chat

Sends a user message to an existing conversation and returns the agent’s response.

POST /{version}/{account_id}/{project_id}/chat/respond

Send a message to an existing chat conversation

cURL

curl --request POST \
  --url https://api.us-1.platform.polyai.app/{version}/{account_id}/{project_id}/chat/respond \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-TOKEN: <x-token>' \
  --data '
{
  "conversation_id": "CONV-1234567890",
  "message": "Hello again"
}
'

200

{
  "conversation_id": "CONV-1234567890",
  "response": "Transferring you to an agent.",
  "end_conversation": true,
  "handoff": {
    "destination": "live_agent_queue",
    "reason": "billing_question"
  }
}

Custom parameters

The respond endpoint supports additional parameters for advanced use cases:

integration_attributes · object

Custom metadata to pass to the conversation. This data is accessible in functions through conv.integration_attributes.

Example:

{
  "integration_attributes": {
    "page_url": "https://example.com/checkout",
    "cart_value": "99.99"
  }
}

asr_lang_code · string

Language code for speech recognition (e.g., "en-US", "es-ES").

tts_lang_code · string

Language code for text-to-speech (e.g., "en-US", "es-ES").

Custom parameters

metadata · object

Custom metadata for this specific message. Accessible in functions during this turn.

Example:

{
  "metadata": {
    "user_action": "clicked_button",
    "button_id": "confirm_booking"
  }
}

asr_lang_code · string

Language code for speech recognition (e.g., "en-US", "es-ES").

tts_lang_code · string

Language code for text-to-speech (e.g., "en-US", "es-ES").

Authorizations

ApiKeyAuthTokenAuth

X-API-KEY · string · header · required

You must request an API Key to use PolyAI APIs.

Headers

X-API-KEY · string · required

Your PolyAI API key.

X-TOKEN · string · required

Agent authentication token (connector).

Path Parameters

version · string · required

API version

account_id · string · required

Account ID

project_id · string · required

Project ID

Body

application/json

conversation_id · string · required

ID of the conversation to respond to

Example:

"CONV-1234567890"

message · string

Message to send to the agent

Example:

"Hello again"

Response

200

application/json

OK

conversation_id · string · required

ID of the conversation

Example:

"CONV-1234567890"

response · string · required

Response message from the agent

Example:

"Transferring you to an agent."

end_conversation · boolean · required

Whether the conversation should be ended

Example:

true

handoff · object

Information about handoff if applicable

Show child attributes