Widgets

Create Widget

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.

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

Headers

Idempotency-Keystring nullable

Request body

namestring 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_colorstring nullable

Primary color for widget theme (hex, e.g., '#2563eb')

position'bottom-right' | 'bottom-left' nullable

Widget position on screen

header_titlestring 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_voiceboolean 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_labelstring 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

Successful Response

unknown required

Changes

No recorded changes to this operation across all 5 revisions of this API.