Update the web widget settings
Saves the widget's switch, websites and look. Send the whole object: enabled,
allowed_origins, title, greeting, away_message, accent, side and
theme are written as sent. reply_time and identity_required are left
unchanged when omitted.
Refused with 422 when the widget is switched on with no allowed_origins, when
accent is not a six-digit hex colour, or when identity_required is true before
verified visitors are set up. Each save is recorded in the workspace activity log
and sends the widget.settings_changed webhook event.
Same key and SautiDesk requirements as getWebWidgetSettings. The Call button is
set with updateWebWidgetVoice.
Authorization
bearerAuth Long-lived ES256 JWT minted from the dashboard (https://app.sautikit.com/developers/api-keys). Signed by the
platform keyring. Carries workspace_id and scopes claims;
revoked via the platform deny-list.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/v1/desk/widget/settings" \ -H "Content-Type: application/json" \ -d '{ "enabled": true, "allowed_origins": [ "https://www.example.co.ke" ], "title": "Talk to us", "greeting": "Hi, how can we help today?", "away_message": "We are away right now and will reply when we are back.", "reply_time": "We usually reply in a few minutes", "accent": "#0F766E", "side": "right", "theme": "system" }'{ "public_key": "wk_3f9c2a7b1e", "enabled": true, "allowed_origins": [ "https://www.example.co.ke" ], "title": "Talk to us", "greeting": "Hi, how can we help today?", "away_message": "We are away right now and will reply when we are back.", "reply_time": "We usually reply in a few minutes", "accent": "#0F766E", "side": "right", "theme": "system", "identity_required": false, "snippet": "<script async src=\"https://api.sautidesk.com/widget.js\" data-desk-key=\"wk_3f9c2a7b1e\"></script>", "faces": [ "AW", "BK" ], "names": [ "Amina", "Brian" ], "lead": "Amina", "voice": { "enabled": true, "queue_id": "c70c2d37-4d65-4ba4-9843-5e8aaf2dae40", "queue_name": "Support", "queue_ready": true, "destination": "", "note": "Talk to sales", "available": true, "status": "ready", "needs_number": false }}{ "error": "string", "code": "string"}{ "error": "string", "code": "string"}{ "error": "string", "code": "string"}{ "error": "add the website the widget will live on before turning it on"}Get the web widget settings GET
Returns the chat widget for this workspace: whether it is on, the websites it may load on, its title, greeting, colour and corner, the `snippet` to paste into your site, and the state of its Call button. The first call creates the widget with a fresh `public_key`, switched off. `public_key` names the workspace and grants nothing on its own; the widget only loads on the `allowed_origins` you list. `identity_secret` is a real secret (it signs the token your server issues to vouch for a signed-in visitor): keep it on your server. Authenticate with a personal SautiDesk API key that carries the `desk.admin` scope, held by a workspace owner or admin. Workspace API keys are refused. The workspace must have SautiDesk turned on (`403 desk.not_desk_opted_in` otherwise).
Set the widget Call button PUT
Turns the widget's Call button on or off and says where a call rings: a SautiDesk queue (`queue_id`) or an extension (`destination`). Kept apart from the look settings because switching it on accepts phone calls. A visitor sees Call only while it is enabled, the workspace has an active voice number, and an agent is online with their phone open. `voice.status` in the response says which of these is missing (`off`, `needs_number`, `needs_agent` or `ready`). Visitor calls from the widget are not billed. Refused with 422 when enabled with neither a queue nor a destination, when `destination` looks like a phone number but is not valid E.164 (`code: invalid_destination`, with `suggested_e164` when one can be inferred), or when the queue has not been saved to the phone system yet. Same key and SautiDesk requirements as `getWebWidgetSettings`.