What format does an allowed origin take?

An origin is a scheme, a host and a port if it isn’t the default one, with no path. The API saves each entry in that form, so https://Example.com:443/ becomes https://example.com. It rejects paths, other schemes and plain http on public hosts with “Use an HTTPS origin without a path, such as https://yourproduct.com.”, and a value without a scheme, such as example.com, as an invalid URL.

  • https://www.example.com is valid, with or without a trailing slash.
  • https://www.example.com/pricing is rejected because it has a path. Query strings, fragments and user names are rejected too.
  • http:// works only for localhost and 127.0.0.1, such as http://localhost:3000. Every other site needs HTTPS.
  • www.example.com and example.com are different origins, so list both if your site answers on both.
  • A port makes a different origin: https://staging.example.com:8443 doesn’t match https://staging.example.com.
  • There are no wildcards. Each entry matches one origin exactly, so every preview or branch deployment address needs its own entry.
  • Each agent takes up to 10. Sending more returns “Add up to 10 allowed origins.”
A valid list
{
  "allowedOrigins": [
    "https://www.example.com",
    "https://example.com",
    "http://localhost:3000"
  ]
}

How is the origin checked?

When a visitor starts a call, the widget requests a one-use call ticket from your page, so the browser attaches your page’s Origin header. The server compares that header exactly with the agent’s list, then checks whether customer calls are on and whether the workspace is within its call limits. This is what a visitor sees when a check fails:

  • An origin that isn’t listed: the server refuses the browser’s CORS preflight with 403, so the browser blocks the ticket request. After allowing the microphone, the visitor sees “Could not connect. Please try again.”, and the browser console shows a CORS error for /api/widget/ticket. If that happens on your own site, check that its exact origin is in the list.
  • Customer calls switched off for that agent: “This line is not accepting calls yet.”
  • Already 3 calls starting or in progress, or 12 started in the last minute: “This line is busy. Please try again shortly.”

What doesn’t the origin check protect against?

Browsers always send the real origin, so the list stops other websites from using your agent in their pages. It isn’t bot protection, though: a program outside a browser can send any Origin header, and there’s no CAPTCHA. The call limits and the free allowance cap what such traffic can use, and switching customer calls off stops it at once.

How do you update the list without losing origins?

The list is saved as a whole. The allowedOrigins you send replaces the agent’s saved list, so read the current list, change it and send all of it back. An empty list removes every origin and stops customer calls from every site.

Use PATCH /api/manage/settings for the support agent and PATCH /api/manage/sales-settings for the sales agent. Over MCP, read the list with get_installation and send it back through update_agent.

Every change to a list emails the workspace owner’s sign-in address with the new origins and the first characters of the token that made the change, so an email you didn’t expect is worth checking.

Read the list, then send it back with a new origin
# 1. Read the saved lists: settings.allowedOrigins is support,
#    salesSettings.allowedOrigins is sales.
curl 'https://app.kawlnow.com/api/manage/workspace' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN'

# 2. Send the whole support list back with the new origin added.
curl -X PATCH 'https://app.kawlnow.com/api/manage/settings' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"allowedOrigins": ["https://www.example.com", "https://example.com", "https://staging.example.com"]}'

Which origins do you need while you test?

None for your first tests, because dashboard test calls work before you add an origin. Add http://localhost with your port, such as http://localhost:3000, to try the embed on your own machine, and your staging origin to check it with your real headers.

Remove the origins you no longer need before launch. Once customer calls are on, any listed origin can start calls, and each one counts towards the workspace’s 50 free conversations.