> ## Documentation Index > Fetch the complete documentation index at: https://docs.vocily.ai/llms.txt > Use this file to discover all available pages before exploring further. # Configure the widget > Appearance, placement, and which modes it offers. ```json theme={"dark"} { "allowed_origins": ["https://acme.example"], "enabled_modes": { "chat": true, "talk": true }, "theme": { "title": "Acme Support", "accent_color": "#7C83FF", "position": "bottom-right" } } ``` `enabled_modes` decides whether visitors can type, talk, or both. `default_variables` supplies values for the agent's `{{variables}}` on every conversation the widget starts — a plan name, a page, a customer id your site already knows. ## OpenAPI ````yaml developers/openapi.json PATCH /v1/agents/{agent_id}/widget openapi: 3.1.0 info: title: Vocily API description: >- Public REST API for Vocily. Build and configure an agent, publish a version and put it live, place outbound calls, and read back calls, chats and what the agent remembered. Authenticate with a workspace API key as a Bearer token. Some things stay in the dashboard, by design: creating an API key, buying or connecting a phone number, setting an agent's webhook URL, connecting WhatsApp and its templates, building HTTP tools, and running batch campaigns. version: v1 servers: - url: https://api.vocily.ai description: Production security: [] paths: /v1/agents/{agent_id}/widget: patch: tags: - widgets summary: Update Agent Widget description: Change the widget. Send only the fields you are changing. operationId: update_agent_widget_v1_agents__agent_id__widget_patch parameters: - name: agent_id in: path required: true schema: type: string title: Agent Id description: The agent's id, as `GET /v1/agents` returns it. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicWidgetUpdate' example: allowed_origins: - https://acme.example responses: '200': description: The updated widget. content: application/json: schema: type: object properties: id: type: string agent_id: type: string name: type: string allowed_origins: items: type: string type: array enabled_modes: type: object properties: chat: type: boolean talk: type: boolean theme: type: object default_variables: type: object public_key_prefix: type: string status: type: string created_at: type: string format: date-time updated_at: type: string format: date-time example: name: Website widget allowed_origins: - https://acme.example enabled_modes: chat: true talk: true theme: title: Acme Support subtitle: Ask anything or start a web call welcome_message: Hi! How can I help you today? logo_url: null accent_color: '#7C83FF' launcher_text_color: '#FFFFFF' user_message_color: '#7C83FF' user_message_text_color: '#FFFFFF' assistant_message_color: '#17171D' assistant_message_text_color: '#E5E7EB' position: bottom-right launcher_label: Chat button_shape: rounded panel_radius: 24 message_radius: 16 launcher_radius: 999 icon_radius: 999 dock_icon_size: 26 launcher_padding_x: 18 launcher_padding_y: 13 widget_width: 380 widget_height: 620 show_inbound_number: true default_variables: {} id: 00000011-0000-4000-8000-000000000011 agent_id: 00000005-0000-4000-8000-000000000005 public_key_prefix: pk_widget_live_EXA status: active created_at: '2026-09-16T19:38:04.301686Z' updated_at: '2026-09-16T19:38:04.312452Z' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: detail: Invalid API key code: UNAUTHORIZED '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded — honor `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: code: rate_limited security: - bearerAuth: [] components: schemas: PublicWidgetUpdate: properties: name: anyOf: - maxLength: 255 minLength: 1 type: string - type: 'null' title: Name description: What to call this widget. allowed_origins: anyOf: - items: type: string type: array - type: 'null' title: Allowed Origins description: >- **The security boundary**: which origins may use this widget's public key. Sending the list replaces the whole set. enabled_modes: anyOf: - $ref: '#/components/schemas/WidgetModes' - type: 'null' description: Whether visitors can type, talk, or both. theme: anyOf: - $ref: '#/components/schemas/WidgetTheme' - type: 'null' description: Appearance and placement. default_variables: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Default Variables description: >- Values supplied for the agent's `{{variables}}` on every conversation this widget starts. status: anyOf: - type: string - type: 'null' title: Status description: Whether the widget is live or paused. additionalProperties: false type: object title: PublicWidgetUpdate ApiError: type: object description: >- Error envelope. `code` is derived from the HTTP status, so branch on it for the CLASS of failure; the specific reason is `detail.code`. Every public refusal carries both. properties: detail: type: object description: >- The reason. `code` is the domain reason (e.g. `call_not_found`) and `message` is a sentence safe to log. On a `422` it also carries `errors[]`, one entry per rejected field — see `HTTPValidationError`. properties: code: type: string example: call_not_found message: type: string example: Call not found required: - code - message code: type: string description: Derived from the HTTP status, not the domain reason. example: NOT_FOUND HTTPValidationError: type: object title: HTTPValidationError description: >- A request the API could not read: a field of the wrong type, out of range, missing, or one we do not accept. Same envelope as every other error. properties: detail: type: object description: >- What was wrong, as `code`, a one-line `message`, and every offending field in `errors`. required: - code - message - errors properties: code: type: string enum: - validation_error message: type: string description: >- The first problem in one line, with a count of the rest — e.g. `model.temperature: Input should be less than or equal to 2 (and 1 more)`. errors: type: array items: $ref: '#/components/schemas/ValidationError' description: >- One entry per offending field. **Every problem is reported at once**, not just the first, so a malformed body needs one round trip to fix rather than one per field. code: type: string enum: - VALIDATION_ERROR description: Derived from the HTTP status, as on every error. WidgetModes: properties: chat: type: boolean title: Chat description: Whether visitors can type to the agent. default: true talk: type: boolean title: Talk description: >- Whether visitors can speak to it. A talk session is a real voice call and bills like one. default: false type: object title: WidgetModes WidgetTheme: properties: title: type: string title: Title description: Heading shown at the top of the widget panel. default: Vocily Assistant subtitle: type: string title: Subtitle description: Line under the heading. default: Ask anything or start a web call welcome_message: type: string title: Welcome Message description: First thing shown in the panel, before the conversation starts. default: Hi! How can I help you today? logo_url: anyOf: - type: string - type: 'null' title: Logo Url description: Your logo, shown in the panel header. accent_color: type: string title: Accent Color description: Main brand colour, as a hex string like `#7C83FF`. default: '#7C83FF' launcher_text_color: type: string title: Launcher Text Color description: Text colour on the launcher button, hex. default: '#FFFFFF' user_message_color: type: string title: User Message Color description: Bubble colour for the visitor's messages, hex. default: '#7C83FF' user_message_text_color: type: string title: User Message Text Color description: Text colour inside the visitor's bubbles, hex. default: '#FFFFFF' assistant_message_color: type: string title: Assistant Message Color description: Bubble colour for the agent's messages, hex. default: '#17171D' assistant_message_text_color: type: string title: Assistant Message Text Color description: Text colour inside the agent's bubbles, hex. default: '#E5E7EB' position: type: string title: Position description: >- Which corner the widget sits in — `bottom-right`, `bottom-left`, `top-right` or `top-left`. Anything else is refused. default: bottom-right launcher_label: type: string title: Launcher Label description: Text on the launcher button. default: Chat button_shape: type: string title: Button Shape description: >- Shape of the launcher button. `rounded` and `square` are what the dashboard offers. **Open set** — an unrecognised value is stored and the launcher falls back to its default shape. default: rounded panel_radius: type: integer maximum: 48 minimum: 0 title: Panel Radius description: Corner radius of the panel, in pixels. default: 24 message_radius: type: integer maximum: 32 minimum: 0 title: Message Radius description: Corner radius of message bubbles, in pixels. default: 16 launcher_radius: type: integer maximum: 999 minimum: 0 title: Launcher Radius description: Corner radius of the launcher button, in pixels. default: 999 icon_radius: type: integer maximum: 999 minimum: 0 title: Icon Radius description: Corner radius of the icon, in pixels. default: 999 dock_icon_size: type: integer maximum: 96 minimum: 16 title: Dock Icon Size description: Size of the docked icon, in pixels. default: 26 launcher_padding_x: type: integer maximum: 96 minimum: 0 title: Launcher Padding X description: Horizontal padding inside the launcher button, in pixels. default: 18 launcher_padding_y: type: integer maximum: 80 minimum: 0 title: Launcher Padding Y description: Vertical padding inside the launcher button, in pixels. default: 13 widget_width: type: integer maximum: 520 minimum: 300 title: Widget Width description: Panel width, in pixels. default: 380 widget_height: type: integer maximum: 820 minimum: 420 title: Widget Height description: Panel height, in pixels. default: 620 show_inbound_number: type: boolean title: Show Inbound Number description: >- Whether to show the agent's inbound number in the panel, so a visitor can call instead. default: true type: object title: WidgetTheme ValidationError: type: object title: ValidationError required: - field - message - type properties: field: type: string description: >- The offending field as a path from the root of your request — `voice.speed`, `variables[0].key`, or `query.limit` for a query parameter. **This is the field to read.** message: type: string description: What is wrong with it, in plain language. type: type: string description: >- A stable machine code for the kind of failure, e.g. `extra_forbidden` for a field we do not accept, `missing` for a required one, or `less_than_equal` for a number out of range. Switch on this rather than on `message`, which may be reworded. securitySchemes: bearerAuth: type: http scheme: bearer description: 'Your API key as a Bearer token, e.g. `Authorization: Bearer vk_…`.' ````