Skip to main content
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
}
'
{
  "message": "Webchat configuration created",
  "data": {
    "_id": "67d3a0b0c0d0e0f0a0b0c0d0",
    "name": "Marketing site widget",
    "isEnabled": true
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
name
string
required

Display name for the webchat configuration in the admin UI.

​
backgroundColor
string
required

Hex color for the widget chat panel background.

​
primaryColor
string
required

Hex color for the widget primary accent (header/buttons).

​
secondaryColor
string
required

Hex color for the widget secondary accent (outbound bubbles).

​
promptId
string
required

AI prompt _id driving the agent for this widget.

​
allowedDomains
string[]
required

Hostnames permitted to embed this widget. Empty array disables host check.

​
initialStage
string
required

Pipeline stage new webchat contacts enter.

​
description
string

Free-form notes describing this widget configuration.

​
starterMessage
string

Greeting bubble shown to the visitor before they send a message.

​
icon
string

Storage key or signed URL for the widget icon.

​
headerTextColor
string

Hex color for text inside the widget header.

​
statusText
string

Status line shown under the title (e.g. We typically reply in minutes).

​
statusTextColor
string

Hex color for the status text.

​
timestampColor
string

Hex color for message timestamps.

​
csatBackgroundColor
string

Hex color for the CSAT survey panel background.

​
csatTextColor
string

Hex color for CSAT survey text.

​
csatThankYouMessage
string

Message shown after the visitor submits a CSAT response.

​
pipelineId
string

Pipeline _id new webchat contacts are placed into.

​
pipelineStage
string

Pipeline stage new webchat contacts are placed into.

​
isAutopilot
boolean

When true, the AI replies autonomously without rep approval.

​
isEnabled
boolean

When true, the widget is active and accepts new sessions.

Response

Webchat configuration created

Response from POST /api/webchats and PUT /api/webchats/{id}.

​
data
object
required

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).

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"
}
​
message
string