Skip to main content
POST
/
{version}
/
{account_id}
/
{project_id}
/
chat
/
respond
Send a message to an existing chat conversation
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"
}
'
{
  "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 via 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

​
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
required

Message to send to the agent

Example:

"Hello again"

Response

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