---
title: "Create Widget"
method: POST
path: "/api/v1/widgets"
tags: ["Widgets"]
---

# Create Widget

`POST /api/v1/widgets`

## Request

- Base URL: `https://api.dialogbrain.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.dialogbrain.com/api/v1/widgets`
- Auth: none declared

Create a widget and return it, embed key included.

Requires Idempotency-Key: a retried request with the same key returns the widget created the first time instead of a second one. A widget is its own channel, so it has its own conversations and, with allow_voice, its own voice pickup.

## Headers

- `Idempotency-Key` string, nullable

## Request body

- SrcApiV1ToolSchemaWidgetCreateRequest
  - `name` string, required: Name for the widget (e.g., 'Website Chat', 'Support Widget')
  - `auto_reply_mode` 'auto' | 'draft', nullable: Auto-reply mode: 'draft' (review before sending) or 'auto' (send immediately)
  - `primary_color` string, nullable: Primary color for widget theme (hex, e.g., '#2563eb')
  - `position` 'bottom-right' | 'bottom-left', nullable: Widget position on screen
  - `header_title` string, nullable: Title shown in chat header
  - `display_mode` 'chat' | 'voice_only' | 'headless', nullable: How the widget renders: 'chat' (default) for the full panel with a microphone, 'voice_only' for a mic-only bubble that starts a call, 'headless' for no interface at all, driven through window.DialogBrain.
  - `allow_voice` boolean, nullable: Master switch for voice — set true to show the mic so visitors can talk to the agent. Everything else voice-related is inert until this is on. The mic also needs a voice-capable agent in the workspace: one with an enabled incoming_call trigger. OMIT to leave voice off (the default).
  - `voice_button_label` string, nullable: Localized aria-label and hover tooltip for the voice-only mic bubble (only used when display_mode='voice_only'). ≤ 100 chars. Defaults to 'Talk to agent' if omitted.

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway.md) · [All operations](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway/revisions/77bef09a9209?raw)