Skip to main content
POST
Create a new chat conversation

Custom parameters

The Chat API supports additional parameters for advanced use cases:
integration_attributes
object
Custom metadata passed from external integrations. This data is accessible in functions through conv.integration_attributes.Example:
variant_id
string
Specify which variant to use for this conversation. Useful for multi-site deployments.
channel
string
Channel identifier for the conversation (e.g., "webchat", "sms").
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
integration_attributes
object

Custom metadata passed from external integrations. Accessible in functions via conv.integration_attributes.

Example:
variant_id
string

Specify which variant to use for this conversation. Useful for multi-site deployments.

Example:

"VARIANT-xxxxxxxx"

channel
enum<string>

Channel identifier for the conversation.

Available options:
webchat,
whatsapp,
sms,
api
Example:

"webchat"

asr_lang_code
string

Language code for speech recognition (ISO 639-1 with region).

Example:

"en-US"

tts_lang_code
string

Language code for text-to-speech (ISO 639-1 with region).

Example:

"en-US"

Response

OK

conversation_id
string
required

Unique ID for the created conversation

Example:

"CONV-1234567890"

response
string
required

Initial response message from the agent

Example:

"Hi, how can I help?"

Last modified on April 20, 2026