Documentation

Domain Restrictions

Control which websites can embed your agent widget.

Domain restrictions limit where your agent widget can be embedded. When configured, the widget only loads on approved domains - preventing unauthorized use on other websites.

Setting Up Domain Restrictions

  1. Go to your agent's Settings tab
  2. Click Security
  3. Find Allowed Domains
  4. Toggle the restriction on
  5. Add your domain(s)
  6. Save changes

Adding Domains

Enter full origins including the protocol. The domain validation performs exact origin matching (protocol + hostname + port):

  • https://example.com - Matches only https://example.com (NOT https://www.example.com)
  • https://www.example.com - Matches only https://www.example.com
  • https://*.example.com - Matches any subdomain (e.g., https://app.example.com, https://www.example.com) but NOT the root domain

Examples

EntryMatchesDoesn't Match
https://mysite.comhttps://mysite.comhttps://www.mysite.com, https://app.mysite.com
https://www.mysite.comhttps://www.mysite.comhttps://mysite.com, https://app.mysite.com
https://*.mysite.comhttps://app.mysite.com, https://www.mysite.comhttps://mysite.com (root domain)

Important: To cover both root and www, add both entries:

https://mysite.com
https://www.mysite.com

What Happens on Unauthorized Domains

When someone tries to load your widget from an unapproved origin, the chat API returns a 403 Domain not allowed response and the widget will not be able to start a conversation.

Your agent and messages remain secure.

Development and Testing

For local development, add the full origin including the port:

  • http://localhost:3000
  • http://127.0.0.1:3000

Remember to remove these before production, or use separate agents for dev and production.

Multiple Domains

Add all origins where your agent should appear:

https://mysite.com
https://www.mysite.com
https://app.mysite.com
https://help.mysite.com

There's no limit to the number of allowed domains.

Disabling Restrictions

To allow embedding on any domain:

  1. Go to Settings > Security
  2. Toggle off Allowed Domains
  3. Save changes

When the toggle is off, the widget can be embedded anywhere.

Common Use Cases

Single Marketing Site

https://mycompany.com
https://www.mycompany.com

Multiple Properties

https://mainsite.com
https://blog.mainsite.com
https://shop.mainsite.com
https://support.mainsite.com

Development + Production

Create separate agents:

  • Production agent: Only production domains
  • Dev agent: localhost, staging domains

Troubleshooting

Widget Not Loading on My Site

  • Verify the origin is in the allowed list
  • Check for typos (https://mysite.com vs https://www.mysite.com)
  • Make sure each entry includes the protocol (https:// or http://) and matches the port used in the browser
  • Clear browser cache and try again

Widget Loading on Unauthorized Sites

  • Verify domain restrictions are saved
  • Check if wildcard is too broad
  • Test in a private/incognito browser

Next Steps