Skip to main content
POST
/
{version}
/
{account_id}
/
{project_id}
/
chat
/
create
Create a new chat conversation
curl --request POST \
  --url https://api.us-1.platform.polyai.app/{version}/{account_id}/{project_id}/chat/create \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-TOKEN: <x-token>' \
  --data '
{
  "integration_attributes": {
    "customer_id": "12345",
    "source": "mobile_app"
  },
  "variant_id": "VARIANT-xxxxxxxx",
  "channel": "webchat",
  "asr_lang_code": "en-US",
  "tts_lang_code": "en-US",
  "initial_message": "Hello, I need help"
}
'
{
  "conversation_id": "CONV-1234567890",
  "response": "Hi, how can I help?"
}

​
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 via conv.integration_attributes.Example:
{
  "integration_attributes": {
    "customer_id": "12345",
    "source": "mobile_app"
  }
}
​
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", "whatsapp").
​
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:
{
  "customer_id": "12345",
  "source": "mobile_app"
}
​
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"

​
initial_message
string

Optional initial message from the user to start the conversation.

Example:

"Hello, I need help"

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