Create a chat
Creates a new chat conversation and returns the conversation ID along with the agent’s initial response.
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"
}
'import requests
url = "https://api.us-1.platform.polyai.app/{version}/{account_id}/{project_id}/chat/create"
payload = {
"integration_attributes": {
"customer_id": "12345",
"source": "mobile_app"
},
"variant_id": "VARIANT-xxxxxxxx",
"channel": "webchat",
"asr_lang_code": "en-US",
"tts_lang_code": "en-US"
}
headers = {
"X-API-KEY": "<api-key>",
"X-TOKEN": "<x-token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-API-KEY': '<api-key>',
'X-TOKEN': '<x-token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
integration_attributes: {customer_id: '12345', source: 'mobile_app'},
variant_id: 'VARIANT-xxxxxxxx',
channel: 'webchat',
asr_lang_code: 'en-US',
tts_lang_code: 'en-US'
})
};
fetch('https://api.us-1.platform.polyai.app/{version}/{account_id}/{project_id}/chat/create', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.us-1.platform.polyai.app/{version}/{account_id}/{project_id}/chat/create",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'integration_attributes' => [
'customer_id' => '12345',
'source' => 'mobile_app'
],
'variant_id' => 'VARIANT-xxxxxxxx',
'channel' => 'webchat',
'asr_lang_code' => 'en-US',
'tts_lang_code' => 'en-US'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: <api-key>",
"X-TOKEN: <x-token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.us-1.platform.polyai.app/{version}/{account_id}/{project_id}/chat/create"
payload := strings.NewReader("{\n \"integration_attributes\": {\n \"customer_id\": \"12345\",\n \"source\": \"mobile_app\"\n },\n \"variant_id\": \"VARIANT-xxxxxxxx\",\n \"channel\": \"webchat\",\n \"asr_lang_code\": \"en-US\",\n \"tts_lang_code\": \"en-US\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("X-TOKEN", "<x-token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.us-1.platform.polyai.app/{version}/{account_id}/{project_id}/chat/create")
.header("X-API-KEY", "<api-key>")
.header("X-TOKEN", "<x-token>")
.header("Content-Type", "application/json")
.body("{\n \"integration_attributes\": {\n \"customer_id\": \"12345\",\n \"source\": \"mobile_app\"\n },\n \"variant_id\": \"VARIANT-xxxxxxxx\",\n \"channel\": \"webchat\",\n \"asr_lang_code\": \"en-US\",\n \"tts_lang_code\": \"en-US\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.us-1.platform.polyai.app/{version}/{account_id}/{project_id}/chat/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["X-TOKEN"] = '<x-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"integration_attributes\": {\n \"customer_id\": \"12345\",\n \"source\": \"mobile_app\"\n },\n \"variant_id\": \"VARIANT-xxxxxxxx\",\n \"channel\": \"webchat\",\n \"asr_lang_code\": \"en-US\",\n \"tts_lang_code\": \"en-US\"\n}"
response = http.request(request)
puts response.read_body{
"conversation_id": "CONV-1234567890",
"response": "Hi, how can I help?"
}{
"success": false,
"error": "The draft you are attempting to chat with does not exist.",
"error_id": "550e8400-e29b-41d4-a716-446655440000",
"error_code": "CHAT_DRAFT_NOT_EXIST",
"error_message": "The draft you are attempting to chat with does not exist.",
"data": null
}{
"success": false,
"error": "<string>",
"error_id": "<string>",
"error_code": "<string>",
"error_message": "<string>",
"data": "<unknown>"
}{
"success": false,
"error": "<string>",
"error_id": "<string>",
"error_code": "<string>",
"error_message": "<string>",
"data": "<unknown>"
}{
"success": false,
"error": "<string>",
"error_id": "<string>",
"error_code": "<string>",
"error_message": "<string>",
"data": "<unknown>"
}{
"success": false,
"error": "<string>",
"error_id": "<string>",
"error_code": "<string>",
"error_message": "<string>",
"data": "<unknown>"
}Custom parameters
The Chat API supports additional parameters for advanced use cases:object
Custom metadata passed from external integrations. This data is accessible in functions through
conv.integration_attributes.Example:{
"integration_attributes": {
"customer_id": "12345",
"source": "mobile_app"
}
}
string
Specify which variant to use for this conversation. Useful for multi-site deployments.
string
Channel identifier for the conversation (e.g.,
"webchat", "sms").string
Language code for speech recognition (e.g.,
"en-US", "es-ES").string
Language code for text-to-speech (e.g.,
"en-US", "es-ES").Authorizations
ApiKeyAuthTokenAuth
You must request an API Key to use PolyAI APIs.
Headers
Your PolyAI API key.
Agent authentication token (connector).
Path Parameters
API version
Account ID
Project ID
Body
application/json
Custom metadata passed from external integrations. Accessible in functions via conv.integration_attributes.
Example:
{ "customer_id": "12345", "source": "mobile_app" }
Specify which variant to use for this conversation. Useful for multi-site deployments.
Example:
"VARIANT-xxxxxxxx"
Channel identifier for the conversation.
Available options:
webchat, whatsapp, sms, api Example:
"webchat"
Language code for speech recognition (ISO 639-1 with region).
Example:
"en-US"
Language code for text-to-speech (ISO 639-1 with region).
Example:
"en-US"
Last modified on April 20, 2026
Was this page helpful?
⌘I
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"
}
'import requests
url = "https://api.us-1.platform.polyai.app/{version}/{account_id}/{project_id}/chat/create"
payload = {
"integration_attributes": {
"customer_id": "12345",
"source": "mobile_app"
},
"variant_id": "VARIANT-xxxxxxxx",
"channel": "webchat",
"asr_lang_code": "en-US",
"tts_lang_code": "en-US"
}
headers = {
"X-API-KEY": "<api-key>",
"X-TOKEN": "<x-token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-API-KEY': '<api-key>',
'X-TOKEN': '<x-token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
integration_attributes: {customer_id: '12345', source: 'mobile_app'},
variant_id: 'VARIANT-xxxxxxxx',
channel: 'webchat',
asr_lang_code: 'en-US',
tts_lang_code: 'en-US'
})
};
fetch('https://api.us-1.platform.polyai.app/{version}/{account_id}/{project_id}/chat/create', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.us-1.platform.polyai.app/{version}/{account_id}/{project_id}/chat/create",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'integration_attributes' => [
'customer_id' => '12345',
'source' => 'mobile_app'
],
'variant_id' => 'VARIANT-xxxxxxxx',
'channel' => 'webchat',
'asr_lang_code' => 'en-US',
'tts_lang_code' => 'en-US'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: <api-key>",
"X-TOKEN: <x-token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.us-1.platform.polyai.app/{version}/{account_id}/{project_id}/chat/create"
payload := strings.NewReader("{\n \"integration_attributes\": {\n \"customer_id\": \"12345\",\n \"source\": \"mobile_app\"\n },\n \"variant_id\": \"VARIANT-xxxxxxxx\",\n \"channel\": \"webchat\",\n \"asr_lang_code\": \"en-US\",\n \"tts_lang_code\": \"en-US\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("X-TOKEN", "<x-token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.us-1.platform.polyai.app/{version}/{account_id}/{project_id}/chat/create")
.header("X-API-KEY", "<api-key>")
.header("X-TOKEN", "<x-token>")
.header("Content-Type", "application/json")
.body("{\n \"integration_attributes\": {\n \"customer_id\": \"12345\",\n \"source\": \"mobile_app\"\n },\n \"variant_id\": \"VARIANT-xxxxxxxx\",\n \"channel\": \"webchat\",\n \"asr_lang_code\": \"en-US\",\n \"tts_lang_code\": \"en-US\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.us-1.platform.polyai.app/{version}/{account_id}/{project_id}/chat/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["X-TOKEN"] = '<x-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"integration_attributes\": {\n \"customer_id\": \"12345\",\n \"source\": \"mobile_app\"\n },\n \"variant_id\": \"VARIANT-xxxxxxxx\",\n \"channel\": \"webchat\",\n \"asr_lang_code\": \"en-US\",\n \"tts_lang_code\": \"en-US\"\n}"
response = http.request(request)
puts response.read_body{
"conversation_id": "CONV-1234567890",
"response": "Hi, how can I help?"
}{
"success": false,
"error": "The draft you are attempting to chat with does not exist.",
"error_id": "550e8400-e29b-41d4-a716-446655440000",
"error_code": "CHAT_DRAFT_NOT_EXIST",
"error_message": "The draft you are attempting to chat with does not exist.",
"data": null
}{
"success": false,
"error": "<string>",
"error_id": "<string>",
"error_code": "<string>",
"error_message": "<string>",
"data": "<unknown>"
}{
"success": false,
"error": "<string>",
"error_id": "<string>",
"error_code": "<string>",
"error_message": "<string>",
"data": "<unknown>"
}{
"success": false,
"error": "<string>",
"error_id": "<string>",
"error_code": "<string>",
"error_message": "<string>",
"data": "<unknown>"
}{
"success": false,
"error": "<string>",
"error_id": "<string>",
"error_code": "<string>",
"error_message": "<string>",
"data": "<unknown>"
}
