Web Widget Setup

The web widget is the fastest path to customer-facing chat. Dawn owns the transcript directly, so conversation context is simpler and more predictable than external chat platforms.

Before you start

• A Dawn workspace and at least one agent profile.
• The website origin or origins that should be allowed to load and use the widget.
• A public Dawn API base URL reachable by browsers.
• A decision about whether website visitors should be allowed to upload images.

1) Create the Web binding

1. Open Channels → Add channel → Web Widget.
2. Optionally set a Display name and your own Public key. If you leave the key empty, Dawn generates one.
3. Turn the binding on with Enable this channel.
4. Set Allowed origins, one per line. This is required while the binding is enabled.
5. Enable image uploads only if your site should accept visitor image attachments.
6. Create the binding and assign it to an agent.

Use explicit origins such as https://app.example.com in production. Use * only when you intentionally want to allow every origin.

2) Copy the embed code

1. Open the created Web binding in Dawn.
2. Open Embed code.
3. Choose the widget title you want the snippet to use.
4. Copy the generated snippet and paste it into your website HTML before </body>.

<script>
window.DawnWidgetConfig = {
  apiBaseUrl: "https://api.dawnhq.ai",
  publicKey: "web_public_key",
  title: "Support",
  imageUploadEnabled: true
};
</script>
<script async src="https://api.dawnhq.ai/api/v1/channels/web/widget.min.js"></script>

3) How the conversation works

• The hosted widget handles the conversation ID for you.
• Dawn stores the transcript directly, so future messages in the same widget conversation can use that stored history as context.
• Dawn does not depend on any provider-side history fetch for the widget.

Direct API option

If you are building your own client instead of using Dawn’s hosted widget script, use these endpoints:

• POST /api/v1/channels/web/messages to send messages
• POST /api/v1/channels/web/attachments to upload files
• GET /api/v1/channels/web/messages?publicKey=...&conversationExternalId=... to read conversation history

{
  "publicKey": "web_public_key",
  "text": "Hello Dawn"
}

On the first message, omit conversationExternalId. Dawn returns the conversation ID to reuse on later messages and history calls. Do not invent your own conversation ID for a new web binding.

Validation checklist

• The widget loads on an allowed origin and fails on a disallowed one.
• A first test message gets a reply and creates a conversation in Dawn.
• A second message in the same browser session continues the same conversation instead of starting a new one.
• If image uploads are enabled, one image upload succeeds end to end.

Troubleshooting

• Widget loads but messages fail: check that the binding is enabled, the origin is allowed, and the binding is assigned to an active agent.
• Origin errors or CORS failures: make sure the site origin exactly matches one of the allowed origins, or use * only when appropriate.
• Image uploads fail: confirm image uploads are enabled for the binding and upload the file first so you can reference the returned attachmentId.
• History does not restore: your client is likely not reusing the conversationExternalId returned by Dawn.
• Public key not found: the embed snippet or direct API caller is using the wrong binding key.

Validate Web channel origin settings and warn on risky wildcard usage.

Check recent web widget conversation errors and summarize root causes.