ClientSphereDocs
API reference/Widgets

Create widget

Creates a new chat widget with a default support channel.

POST
/widgets

Authorization

AuthorizationRequiredBearer <token>

API key as Bearer token: Authorization: Bearer sk_live_.... Use sk_live_ prefixed keys for production data and sk_test_ prefixed keys for sandbox/test data.

In: header

X-API-Key<token>

API key via header: X-API-Key: sk_live_.... Use sk_live_ prefixed keys for production data and sk_test_ prefixed keys for sandbox/test data.

In: header

Request Body

application/jsonRequired
nameRequiredstring
primaryColorstring

Overridden by the workspace-level appearance setting when one is present.

accentColorstring

Overridden by the workspace-level appearance setting when one is present.

welcomeMessagestring
placeholderTextstring
positionstring
Default: "bottom-right"Value in: "bottom-right" | "bottom-left"
showAgentPhotosboolean
Default: true
showTypingIndicatorboolean
Default: true
requireEmailboolean
Default: false
collectVisitorInfoboolean
Default: true
businessHoursobject
offlineMessagestring
accountIdstring

Link widget to a CRM account

Format: "uuid"
aiAutoRespondboolean

Enable AI auto-responses. Defaults to company AI config.

curl -X POST "https://clientsphere.io/api/v1/widgets" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Chat",
    "primaryColor": "#3B82F6",
    "accentColor": "#1E40AF",
    "welcomeMessage": "Hi! How can we help you today?",
    "placeholderText": "Type your message...",
    "position": "bottom-right",
    "showAgentPhotos": true,
    "showTypingIndicator": true,
    "requireEmail": false,
    "collectVisitorInfo": true,
    "businessHours": {},
    "offlineMessage": "string",
    "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
    "aiAutoRespond": true
  }'

Created widget

{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda",
    "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
    "name": "string",
    "isActive": true,
    "primaryColor": "#3B82F6",
    "accentColor": "#1E40AF",
    "welcomeMessage": "string",
    "placeholderText": "string",
    "position": "bottom-right",
    "showAgentPhotos": true,
    "showTypingIndicator": true,
    "requireEmail": true,
    "collectVisitorInfo": true,
    "businessHours": {},
    "offlineMessage": "string",
    "aiAutoRespond": true,
    "aiAssistantName": "string",
    "aiWelcomeMessage": "string",
    "totalConversations": 0,
    "totalMessages": 0,
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}

Previous

Get widget GET

Next

Update widget PUT