---
title: "Update widget configuration for an agent"
method: PATCH
path: "/agent/{id}/widget-config"
tags: ["Agents"]
---

# Update widget configuration for an agent

`PATCH /agent/{id}/widget-config`

Merge updates into the agent's embeddable widget config. Only the fields in the
request body are overwritten; everything else is preserved. Returns the full
widget config after merge.

## Path parameters

- `id` string, required

## Request body

- object
  - `widgetConfig` WidgetConfig, required — Configuration for the embeddable web widget. Used by `GET /agent/{id}/widget-config` (returned with `assistantId` injected) and `PATCH /agent/{id}/widget-config` (merge-patched). Every field is optional — only the fields present in a PATCH request body are written, so partial updates are safe.
    - `position` 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
    - `size` 'tiny' | 'compact' | 'full'
    - `borderRadius` number
    - `mode` 'chat' | 'voice'
    - `theme` 'light' | 'dark'
    - `baseColor` string
    - `accentColor` string
    - `agentBubbleColor` string
    - `textOnAccentColor` string
    - `secondaryTextColor` string
    - `primaryTextColor` string
    - `title` string
    - `startButtonText` string
    - `endButtonText` string
    - `ctaTitle` string, nullable
    - `ctaSubtitle` string, nullable
    - `ctaName` string, nullable
    - `widgetName` string, nullable
    - `avatarUrl` string, nullable — Must start with the CDN distribution domain prefix configured for the organization. Submit a non-CDN URL and the server returns 400.
    - `voiceEmptyMessage` string, nullable
    - `voiceActiveEmptyMessage` string, nullable
    - `chatEmptyMessage` string, nullable
    - `chatFirstMessage` string, nullable
    - `chatPlaceholder` string
    - `voiceShowTranscript` boolean
    - `consentRequired` boolean
    - `consentTitle` string
    - `consentContent` string
    - `consentStorageKey` string, nullable
    - `publicKey` string
    - `assistantId` string — Injected by `GET /agent/{id}/widget-config` (equals the agent ID).
    - `allowlist` string[] — List of origins (domains) authorized to embed this widget.

## Response `200`

Merged widget configuration.

- object
  - `status` boolean
  - `data` WidgetConfig — Configuration for the embeddable web widget. Used by `GET /agent/{id}/widget-config` (returned with `assistantId` injected) and `PATCH /agent/{id}/widget-config` (merge-patched). Every field is optional — only the fields present in a PATCH request body are written, so partial updates are safe.
    - `position` 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
    - `size` 'tiny' | 'compact' | 'full'
    - `borderRadius` number
    - `mode` 'chat' | 'voice'
    - `theme` 'light' | 'dark'
    - `baseColor` string
    - `accentColor` string
    - `agentBubbleColor` string
    - `textOnAccentColor` string
    - `secondaryTextColor` string
    - `primaryTextColor` string
    - `title` string
    - `startButtonText` string
    - `endButtonText` string
    - `ctaTitle` string, nullable
    - `ctaSubtitle` string, nullable
    - `ctaName` string, nullable
    - `widgetName` string, nullable
    - `avatarUrl` string, nullable — Must start with the CDN distribution domain prefix configured for the organization. Submit a non-CDN URL and the server returns 400.
    - `voiceEmptyMessage` string, nullable
    - `voiceActiveEmptyMessage` string, nullable
    - `chatEmptyMessage` string, nullable
    - `chatFirstMessage` string, nullable
    - `chatPlaceholder` string
    - `voiceShowTranscript` boolean
    - `consentRequired` boolean
    - `consentTitle` string
    - `consentContent` string
    - `consentStorageKey` string, nullable
    - `publicKey` string
    - `assistantId` string — Injected by `GET /agent/{id}/widget-config` (equals the agent ID).
    - `allowlist` string[] — List of origins (domains) authorized to embed this widget.

## Other responses

- `400` — Bad request — validation failed or required field missing.
- `401` — Unauthorized access
- `404` — Resource not found — the referenced ID does not exist or does not belong to the caller's organization.
- `500` — Internal server error

## Changes

- **2026-06-21** `ea4ea58d7c4e` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/smallest-inc/apis/agent-management-api/changes/agent/:id/widget-config/patch.md)

---

[API](https://skmtc.dev/smallest-inc/apis/agent-management-api.md) · [All operations](https://skmtc.dev/smallest-inc/apis/agent-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/smallest-inc/agent-management-api/revisions/ea4ea58d7c4e/schema)