Create webchat configuration
curl --request POST \
--url https://your-instance.example.com/api/webchats \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Marketing site widget",
"description": "Bottom-right widget on the marketing site",
"starterMessage": "Hi! Looking for pricing?",
"backgroundColor": "#FFFFFF",
"primaryColor": "#1F2937",
"secondaryColor": "#3B82F6",
"headerTextColor": "#FFFFFF",
"statusText": "We typically reply within minutes",
"statusTextColor": "#6B7280",
"timestampColor": "#9CA3AF",
"csatBackgroundColor": "#F3F4F6",
"csatTextColor": "#111827",
"csatThankYouMessage": "Thanks for your feedback!",
"promptId": "65b2a1c3d4e5f6a7b8c9d0e1",
"allowedDomains": [
"https://example.com"
],
"pipelineId": "66f0a0b0c0d0e0f0a0b0c0d0",
"pipelineStage": "67f0a0b0c0d0e0f0a0b0c0d0",
"initialStage": "new",
"isAutopilot": true,
"isEnabled": true
}
'import requests
url = "https://your-instance.example.com/api/webchats"
payload = {
"name": "Marketing site widget",
"description": "Bottom-right widget on the marketing site",
"starterMessage": "Hi! Looking for pricing?",
"backgroundColor": "#FFFFFF",
"primaryColor": "#1F2937",
"secondaryColor": "#3B82F6",
"headerTextColor": "#FFFFFF",
"statusText": "We typically reply within minutes",
"statusTextColor": "#6B7280",
"timestampColor": "#9CA3AF",
"csatBackgroundColor": "#F3F4F6",
"csatTextColor": "#111827",
"csatThankYouMessage": "Thanks for your feedback!",
"promptId": "65b2a1c3d4e5f6a7b8c9d0e1",
"allowedDomains": ["https://example.com"],
"pipelineId": "66f0a0b0c0d0e0f0a0b0c0d0",
"pipelineStage": "67f0a0b0c0d0e0f0a0b0c0d0",
"initialStage": "new",
"isAutopilot": True,
"isEnabled": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Marketing site widget',
description: 'Bottom-right widget on the marketing site',
starterMessage: 'Hi! Looking for pricing?',
backgroundColor: '#FFFFFF',
primaryColor: '#1F2937',
secondaryColor: '#3B82F6',
headerTextColor: '#FFFFFF',
statusText: 'We typically reply within minutes',
statusTextColor: '#6B7280',
timestampColor: '#9CA3AF',
csatBackgroundColor: '#F3F4F6',
csatTextColor: '#111827',
csatThankYouMessage: 'Thanks for your feedback!',
promptId: '65b2a1c3d4e5f6a7b8c9d0e1',
allowedDomains: ['https://example.com'],
pipelineId: '66f0a0b0c0d0e0f0a0b0c0d0',
pipelineStage: '67f0a0b0c0d0e0f0a0b0c0d0',
initialStage: 'new',
isAutopilot: true,
isEnabled: true
})
};
fetch('https://your-instance.example.com/api/webchats', 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://your-instance.example.com/api/webchats",
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([
'name' => 'Marketing site widget',
'description' => 'Bottom-right widget on the marketing site',
'starterMessage' => 'Hi! Looking for pricing?',
'backgroundColor' => '#FFFFFF',
'primaryColor' => '#1F2937',
'secondaryColor' => '#3B82F6',
'headerTextColor' => '#FFFFFF',
'statusText' => 'We typically reply within minutes',
'statusTextColor' => '#6B7280',
'timestampColor' => '#9CA3AF',
'csatBackgroundColor' => '#F3F4F6',
'csatTextColor' => '#111827',
'csatThankYouMessage' => 'Thanks for your feedback!',
'promptId' => '65b2a1c3d4e5f6a7b8c9d0e1',
'allowedDomains' => [
'https://example.com'
],
'pipelineId' => '66f0a0b0c0d0e0f0a0b0c0d0',
'pipelineStage' => '67f0a0b0c0d0e0f0a0b0c0d0',
'initialStage' => 'new',
'isAutopilot' => true,
'isEnabled' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://your-instance.example.com/api/webchats"
payload := strings.NewReader("{\n \"name\": \"Marketing site widget\",\n \"description\": \"Bottom-right widget on the marketing site\",\n \"starterMessage\": \"Hi! Looking for pricing?\",\n \"backgroundColor\": \"#FFFFFF\",\n \"primaryColor\": \"#1F2937\",\n \"secondaryColor\": \"#3B82F6\",\n \"headerTextColor\": \"#FFFFFF\",\n \"statusText\": \"We typically reply within minutes\",\n \"statusTextColor\": \"#6B7280\",\n \"timestampColor\": \"#9CA3AF\",\n \"csatBackgroundColor\": \"#F3F4F6\",\n \"csatTextColor\": \"#111827\",\n \"csatThankYouMessage\": \"Thanks for your feedback!\",\n \"promptId\": \"65b2a1c3d4e5f6a7b8c9d0e1\",\n \"allowedDomains\": [\n \"https://example.com\"\n ],\n \"pipelineId\": \"66f0a0b0c0d0e0f0a0b0c0d0\",\n \"pipelineStage\": \"67f0a0b0c0d0e0f0a0b0c0d0\",\n \"initialStage\": \"new\",\n \"isAutopilot\": true,\n \"isEnabled\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <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://your-instance.example.com/api/webchats")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Marketing site widget\",\n \"description\": \"Bottom-right widget on the marketing site\",\n \"starterMessage\": \"Hi! Looking for pricing?\",\n \"backgroundColor\": \"#FFFFFF\",\n \"primaryColor\": \"#1F2937\",\n \"secondaryColor\": \"#3B82F6\",\n \"headerTextColor\": \"#FFFFFF\",\n \"statusText\": \"We typically reply within minutes\",\n \"statusTextColor\": \"#6B7280\",\n \"timestampColor\": \"#9CA3AF\",\n \"csatBackgroundColor\": \"#F3F4F6\",\n \"csatTextColor\": \"#111827\",\n \"csatThankYouMessage\": \"Thanks for your feedback!\",\n \"promptId\": \"65b2a1c3d4e5f6a7b8c9d0e1\",\n \"allowedDomains\": [\n \"https://example.com\"\n ],\n \"pipelineId\": \"66f0a0b0c0d0e0f0a0b0c0d0\",\n \"pipelineStage\": \"67f0a0b0c0d0e0f0a0b0c0d0\",\n \"initialStage\": \"new\",\n \"isAutopilot\": true,\n \"isEnabled\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://your-instance.example.com/api/webchats")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Marketing site widget\",\n \"description\": \"Bottom-right widget on the marketing site\",\n \"starterMessage\": \"Hi! Looking for pricing?\",\n \"backgroundColor\": \"#FFFFFF\",\n \"primaryColor\": \"#1F2937\",\n \"secondaryColor\": \"#3B82F6\",\n \"headerTextColor\": \"#FFFFFF\",\n \"statusText\": \"We typically reply within minutes\",\n \"statusTextColor\": \"#6B7280\",\n \"timestampColor\": \"#9CA3AF\",\n \"csatBackgroundColor\": \"#F3F4F6\",\n \"csatTextColor\": \"#111827\",\n \"csatThankYouMessage\": \"Thanks for your feedback!\",\n \"promptId\": \"65b2a1c3d4e5f6a7b8c9d0e1\",\n \"allowedDomains\": [\n \"https://example.com\"\n ],\n \"pipelineId\": \"66f0a0b0c0d0e0f0a0b0c0d0\",\n \"pipelineStage\": \"67f0a0b0c0d0e0f0a0b0c0d0\",\n \"initialStage\": \"new\",\n \"isAutopilot\": true,\n \"isEnabled\": true\n}"
response = http.request(request)
puts response.read_body{
"message": "Webchat configuration created",
"data": {
"_id": "67d3a0b0c0d0e0f0a0b0c0d0",
"name": "Marketing site widget",
"isEnabled": true
}
}{
"error": "Webchat configuration not found",
"details": "NOT_FOUND"
}{
"error": "Webchat configuration not found",
"details": "NOT_FOUND"
}Webchats
Create webchat configuration
Create a new webchat widget configuration. allowedDomains restricts the embed origins; promptId selects which Prompt the agent uses for AI responses on inbound visitor messages.
POST
/
api
/
webchats
Create webchat configuration
curl --request POST \
--url https://your-instance.example.com/api/webchats \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Marketing site widget",
"description": "Bottom-right widget on the marketing site",
"starterMessage": "Hi! Looking for pricing?",
"backgroundColor": "#FFFFFF",
"primaryColor": "#1F2937",
"secondaryColor": "#3B82F6",
"headerTextColor": "#FFFFFF",
"statusText": "We typically reply within minutes",
"statusTextColor": "#6B7280",
"timestampColor": "#9CA3AF",
"csatBackgroundColor": "#F3F4F6",
"csatTextColor": "#111827",
"csatThankYouMessage": "Thanks for your feedback!",
"promptId": "65b2a1c3d4e5f6a7b8c9d0e1",
"allowedDomains": [
"https://example.com"
],
"pipelineId": "66f0a0b0c0d0e0f0a0b0c0d0",
"pipelineStage": "67f0a0b0c0d0e0f0a0b0c0d0",
"initialStage": "new",
"isAutopilot": true,
"isEnabled": true
}
'import requests
url = "https://your-instance.example.com/api/webchats"
payload = {
"name": "Marketing site widget",
"description": "Bottom-right widget on the marketing site",
"starterMessage": "Hi! Looking for pricing?",
"backgroundColor": "#FFFFFF",
"primaryColor": "#1F2937",
"secondaryColor": "#3B82F6",
"headerTextColor": "#FFFFFF",
"statusText": "We typically reply within minutes",
"statusTextColor": "#6B7280",
"timestampColor": "#9CA3AF",
"csatBackgroundColor": "#F3F4F6",
"csatTextColor": "#111827",
"csatThankYouMessage": "Thanks for your feedback!",
"promptId": "65b2a1c3d4e5f6a7b8c9d0e1",
"allowedDomains": ["https://example.com"],
"pipelineId": "66f0a0b0c0d0e0f0a0b0c0d0",
"pipelineStage": "67f0a0b0c0d0e0f0a0b0c0d0",
"initialStage": "new",
"isAutopilot": True,
"isEnabled": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Marketing site widget',
description: 'Bottom-right widget on the marketing site',
starterMessage: 'Hi! Looking for pricing?',
backgroundColor: '#FFFFFF',
primaryColor: '#1F2937',
secondaryColor: '#3B82F6',
headerTextColor: '#FFFFFF',
statusText: 'We typically reply within minutes',
statusTextColor: '#6B7280',
timestampColor: '#9CA3AF',
csatBackgroundColor: '#F3F4F6',
csatTextColor: '#111827',
csatThankYouMessage: 'Thanks for your feedback!',
promptId: '65b2a1c3d4e5f6a7b8c9d0e1',
allowedDomains: ['https://example.com'],
pipelineId: '66f0a0b0c0d0e0f0a0b0c0d0',
pipelineStage: '67f0a0b0c0d0e0f0a0b0c0d0',
initialStage: 'new',
isAutopilot: true,
isEnabled: true
})
};
fetch('https://your-instance.example.com/api/webchats', 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://your-instance.example.com/api/webchats",
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([
'name' => 'Marketing site widget',
'description' => 'Bottom-right widget on the marketing site',
'starterMessage' => 'Hi! Looking for pricing?',
'backgroundColor' => '#FFFFFF',
'primaryColor' => '#1F2937',
'secondaryColor' => '#3B82F6',
'headerTextColor' => '#FFFFFF',
'statusText' => 'We typically reply within minutes',
'statusTextColor' => '#6B7280',
'timestampColor' => '#9CA3AF',
'csatBackgroundColor' => '#F3F4F6',
'csatTextColor' => '#111827',
'csatThankYouMessage' => 'Thanks for your feedback!',
'promptId' => '65b2a1c3d4e5f6a7b8c9d0e1',
'allowedDomains' => [
'https://example.com'
],
'pipelineId' => '66f0a0b0c0d0e0f0a0b0c0d0',
'pipelineStage' => '67f0a0b0c0d0e0f0a0b0c0d0',
'initialStage' => 'new',
'isAutopilot' => true,
'isEnabled' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://your-instance.example.com/api/webchats"
payload := strings.NewReader("{\n \"name\": \"Marketing site widget\",\n \"description\": \"Bottom-right widget on the marketing site\",\n \"starterMessage\": \"Hi! Looking for pricing?\",\n \"backgroundColor\": \"#FFFFFF\",\n \"primaryColor\": \"#1F2937\",\n \"secondaryColor\": \"#3B82F6\",\n \"headerTextColor\": \"#FFFFFF\",\n \"statusText\": \"We typically reply within minutes\",\n \"statusTextColor\": \"#6B7280\",\n \"timestampColor\": \"#9CA3AF\",\n \"csatBackgroundColor\": \"#F3F4F6\",\n \"csatTextColor\": \"#111827\",\n \"csatThankYouMessage\": \"Thanks for your feedback!\",\n \"promptId\": \"65b2a1c3d4e5f6a7b8c9d0e1\",\n \"allowedDomains\": [\n \"https://example.com\"\n ],\n \"pipelineId\": \"66f0a0b0c0d0e0f0a0b0c0d0\",\n \"pipelineStage\": \"67f0a0b0c0d0e0f0a0b0c0d0\",\n \"initialStage\": \"new\",\n \"isAutopilot\": true,\n \"isEnabled\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <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://your-instance.example.com/api/webchats")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Marketing site widget\",\n \"description\": \"Bottom-right widget on the marketing site\",\n \"starterMessage\": \"Hi! Looking for pricing?\",\n \"backgroundColor\": \"#FFFFFF\",\n \"primaryColor\": \"#1F2937\",\n \"secondaryColor\": \"#3B82F6\",\n \"headerTextColor\": \"#FFFFFF\",\n \"statusText\": \"We typically reply within minutes\",\n \"statusTextColor\": \"#6B7280\",\n \"timestampColor\": \"#9CA3AF\",\n \"csatBackgroundColor\": \"#F3F4F6\",\n \"csatTextColor\": \"#111827\",\n \"csatThankYouMessage\": \"Thanks for your feedback!\",\n \"promptId\": \"65b2a1c3d4e5f6a7b8c9d0e1\",\n \"allowedDomains\": [\n \"https://example.com\"\n ],\n \"pipelineId\": \"66f0a0b0c0d0e0f0a0b0c0d0\",\n \"pipelineStage\": \"67f0a0b0c0d0e0f0a0b0c0d0\",\n \"initialStage\": \"new\",\n \"isAutopilot\": true,\n \"isEnabled\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://your-instance.example.com/api/webchats")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Marketing site widget\",\n \"description\": \"Bottom-right widget on the marketing site\",\n \"starterMessage\": \"Hi! Looking for pricing?\",\n \"backgroundColor\": \"#FFFFFF\",\n \"primaryColor\": \"#1F2937\",\n \"secondaryColor\": \"#3B82F6\",\n \"headerTextColor\": \"#FFFFFF\",\n \"statusText\": \"We typically reply within minutes\",\n \"statusTextColor\": \"#6B7280\",\n \"timestampColor\": \"#9CA3AF\",\n \"csatBackgroundColor\": \"#F3F4F6\",\n \"csatTextColor\": \"#111827\",\n \"csatThankYouMessage\": \"Thanks for your feedback!\",\n \"promptId\": \"65b2a1c3d4e5f6a7b8c9d0e1\",\n \"allowedDomains\": [\n \"https://example.com\"\n ],\n \"pipelineId\": \"66f0a0b0c0d0e0f0a0b0c0d0\",\n \"pipelineStage\": \"67f0a0b0c0d0e0f0a0b0c0d0\",\n \"initialStage\": \"new\",\n \"isAutopilot\": true,\n \"isEnabled\": true\n}"
response = http.request(request)
puts response.read_body{
"message": "Webchat configuration created",
"data": {
"_id": "67d3a0b0c0d0e0f0a0b0c0d0",
"name": "Marketing site widget",
"isEnabled": true
}
}{
"error": "Webchat configuration not found",
"details": "NOT_FOUND"
}{
"error": "Webchat configuration not found",
"details": "NOT_FOUND"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Display name for the webchat configuration in the admin UI.
Hex color for the widget chat panel background.
Hex color for the widget primary accent (header/buttons).
Hex color for the widget secondary accent (outbound bubbles).
AI prompt _id driving the agent for this widget.
Hostnames permitted to embed this widget. Empty array disables host check.
Pipeline stage new webchat contacts enter.
Free-form notes describing this widget configuration.
Greeting bubble shown to the visitor before they send a message.
Storage key or signed URL for the widget icon.
Hex color for text inside the widget header.
Status line shown under the title (e.g. We typically reply in minutes).
Hex color for the status text.
Hex color for message timestamps.
Hex color for the CSAT survey panel background.
Hex color for CSAT survey text.
Message shown after the visitor submits a CSAT response.
Pipeline _id new webchat contacts are placed into.
Pipeline stage new webchat contacts are placed into.
When true, the AI replies autonomously without rep approval.
When true, the widget is active and accepts new sessions.
Response
Webchat configuration created
Response from POST /api/webchats and PUT /api/webchats/{id}.
Stored webchat configuration document. The icon field, when present, is a freshly-signed URL pointing at the R2-hosted asset (the database stores the storage key).
Show child attributes
Show child attributes
Example:
{
"_id": "67d3a0b0c0d0e0f0a0b0c0d0",
"organizationId": "65a0e0e0e0e0e0e0e0e0e0e0",
"userId": "65b1f0a2c3d4e5f6a7b8c9d0",
"createdBy": "65b1f0a2c3d4e5f6a7b8c9d0",
"name": "Marketing site widget",
"description": "Bottom-right widget on the marketing site",
"starterMessage": "Hi! Looking for pricing?",
"backgroundColor": "#FFFFFF",
"primaryColor": "#1F2937",
"secondaryColor": "#3B82F6",
"icon": "https://r2.example.com/orgs/65a0.../webchat/icon.png?token=...",
"promptId": "65b2a1c3d4e5f6a7b8c9d0e1",
"allowedDomains": ["https://example.com"],
"pipelineId": "66f0a0b0c0d0e0f0a0b0c0d0",
"initialStage": "new",
"isAutopilot": true,
"isEnabled": true,
"position": "bottom-right",
"offsetX": 24,
"offsetY": 24,
"zIndex": 9999,
"createdAt": "2026-03-12T10:00:00.000Z",
"updatedAt": "2026-05-18T14:00:00.000Z"
}
⌘I