Skip to main content
The Chat Widget is how your users interact with the AI agent on your website. This guide covers generating the embed code, securing it with domain whitelisting, and customizing its behavior.
New to Deflect? Start with Launch an agent on your website for a full checklist from first login to a verified live widget.

​
Generating the embed snippet

1

Navigate to Settings

Go to Settings → Widget tab in your dashboard.
2

Create an API Key

If you haven’t already, click Create API Key, give it a name (e.g., “Production Website”), and click Create.
Copy your API key immediately — it won’t be shown again in full after creation.
3

Select Your Chatbot

Choose which chatbot the widget should be connected to from the dropdown.
4

Copy the Snippet

The embed snippet will be generated automatically. Click Copy to copy it to your clipboard.
5

Paste into Your Website

Add the snippet just before the closing </body> tag in your website’s HTML:
<script
  src="https://widget.deflect.in/widget.js"
  data-api-key="YOUR_API_KEY"
  data-chatbot-id="YOUR_CHATBOT_ID"
></script>

​
Domain Whitelisting

For security, you should restrict which domains can use your API key.
  1. Go to Settings → Domains tab.
  2. Click Add Domain.
  3. Enter your website domain (e.g., example.com).
  4. Click Add.
Only requests from whitelisted domains are accepted. The browser sends an Origin header; it must match a domain you added under Settings → Domains, or the widget cannot connect (including WebSocket chat).
You must add at least one domain before the embedded widget will work on your site. With no domains whitelisted, widget traffic is rejected.

​
Widget Customization

​
Welcome Message

Configure the initial greeting users see when they open the chat:
  • Static: A fixed message you define (e.g., “Hi! How can I help you today?”).
  • Dynamic: An AI-generated greeting based on context.
Set this in the Agent Editor under the agent’s settings.

​
Auto-Open

Enable auto-open to have the widget automatically open when a user visits your site:
  • Go to Settings → Widget tab.
  • Toggle Auto Open on.

​
AI Popup Greeting

Show a small popup message next to the chat icon to encourage interaction:
  • Go to Settings → Widget tab.
  • Toggle AI Greeting Popup on.
The popup will display a contextual message to draw users into the chat.
Chat widget on a website showing the popup greeting and chat window

​
Visitor image uploads (web widget)

For agents that run on your website, you may enable image uploads so visitors can send screenshots or photos (for example, an error dialog). When enabled, images are validated and the assistant can use a text description of the image in context. Leave the feature off if you want strictly text-only conversations. Configure per agent in the Agent editor (look for an images / uploads toggle for the web channel). Availability can depend on your plan.

​
Testing

Before going live, use the Preview Widget to test the full user experience:
  1. Go to the Agent Editor for your chatbot.
  2. Use the built-in chat window on the right to test responses.
  3. Or go to Settings → Widget and click Preview to see the widget exactly as users will.
Always test after making changes to system prompts, knowledge base, or widget settings.