Update widget settings

Update an agent's widget settings. Top-level keys you send replace the stored ones; orb, button and sandbox (including sandbox.style) are merged one level deep, so you can change a single colour. Changes apply to the live widget on every site where it's embedded.

PATCH https://api.centerfy.ai/webhooks/inbound/agents/:id/widget

Headers

Header	Required	Value	Description
`x-api-key`	Yes	your sub-account API key (cfy_…)	Authenticates the request; or use Authorization: Bearer `<key>`.

Path parameters

Name	Type	Required	Description
`id`	`string (uuid)`	Yes	The agent id.

Body parameters

Name	Type	Required	Default	Description
`type`	`string`	No	—	One of orb, button.
`position`	`string`	No	—	Widget position on the page.
`orb`	`object`	No	—	Orb settings: icon (string), color (string), size (number, 20–400), show_border (boolean), show_text_below (boolean), cta_text (string, max 200), text_color (string), background_style (dark, light or transparent), cta_background (string), cta_background_opacity (number, 0–1), position (string).
`button`	`object`	No	—	Button settings: text (string, max 200), color (string), text_color (string), border_radius (number, min 0), font_size (number, min 1), show_icon (boolean), icon (string), position (string).
`sandbox`	`object`	No	—	enabled (boolean) and style { headline, subheadline, button_label, brand_color, text_color, background_color } (all strings).
`live-avatar`	`any`	No	—	Live avatar widget settings, stored as given.
`demo`	`any`	No	—	Phone demo widget settings, stored as given.

Request body

{
  "orb": {
    "color": "#7c3aed",
    "cta_text": "Talk to us"
  }
}

Example

curl -X PATCH "https://api.centerfy.ai/webhooks/inbound/agents/{id}/widget" \
  -H "x-api-key: $CENTERFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orb": {
    "color": "#7c3aed",
    "cta_text": "Talk to us"
  }
}'

import { CenterfyClient } from "@centerfy/sdk";

const centerfy = new CenterfyClient({ apiKey: process.env.CENTERFY_API_KEY! });

const result = await centerfy.agentWidget.update("<agentId>", {
  "orb": {
    "color": "#7c3aed",
    "cta_text": "Talk to us"
  }
});
console.log(result);

centerfy agentWidget update <agentId> '{"orb":{"color":"#7c3aed","cta_text":"Talk to us"}}'

MCP tool: centerfy_agent_widget_update (see MCP server)

Response

{
  "status": "success",
  "agent_id": "0f1e2d3c-4b5a-4968-8776-655443322110",
  "name": "Front desk",
  "widget_config": {
    "type": "orb",
    "orb": {
      "icon": "mic",
      "color": "#7c3aed",
      "size": 60,
      "show_border": true,
      "show_text_below": false,
      "cta_text": "Talk to us",
      "text_color": "#ffffff",
      "background_style": "dark"
    }
  },
  "updated_at": "2026-10-05T11:00:00.000Z"
}

Errors

400 — if the body is empty, a value is out of range, or type is button and no button object is stored or sent.
404 — if the agent is not in this sub-account.

Notes

Send at least one field; unknown fields are ignored.