Public keys

A public key lets code running in a visitor's browser start a chat with a chat agent, or a web call with a voice agent, without exposing a secret API key. Public keys start with public_key_ and are safe to put in page source because the API only accepts them:

• from an Origin on the key's Allowed domains,
• on four routes: POST /v3/create-web-call, POST /create-chat, POST /create-chat-completion and POST /end-chat/:id (plus the hosted widget routes under /public/chat),
• for the agents attached to the key,
• after the key's abuse checks pass.

Any other route returns 403 with A public key can only start web calls and chats.

Create a public key#

Public keys are managed on Settings, API Keys under the Public Keys tab, and from Chat Agents. A workspace needs at least one chat agent before you can create a key.

At least one of a chat agent, chat agents or a voice agent is required.

Domain matching#

The browser's Origin header is compared with each entry:

• example.com matches https://example.com on any port.
• *.example.com matches any subdomain and example.com itself.
• An entry with a port, such as localhost:3000, must match host and port exactly.

Requests with no Origin (for example from a server) are refused. Use a secret API key on servers.

Abuse protection#

Each request authenticated with a public key goes through these checks, in order:

1. Blocked countries. The client country is read from cf-ipcountry, x-vercel-ip-country or x-country-code, set by your CDN or load balancer. A blocked country gets 403.
2. Per-IP rate. 30 requests per minute from one IP on one key by default (PUBLIC_KEY_IP_RATE_PER_MINUTE). Over it: 429.
3. Per-key rate. When Requests per minute is set, the whole key is limited to that rate. Over it: 429.
4. reCAPTCHA v3. When on, the request must carry a token in the body as recaptcha_token or in the x-recaptcha-token header. A score below the threshold returns 403 with reCAPTCHA check failed.

The account's spend checks also apply: when credit is exhausted or the monthly budget is reached, starting a chat returns 402. See Billing.

Embed the chat widget#

Click Snippet on a key. Embed the chat widget shows a script tag to paste before the closing body tag on any page of an allowed domain:

<script src="https://api.tried.com.au/widget.js" data-public-key="public_key_9c1e..." data-title="Chat with us" async></script>

Optional attributes on the script tag: data-title, data-color, data-api, data-recaptcha-site-key. The widget starts a chat at POST /public/chat/start, then sends messages with a per-chat token, and ends the chat when the page closes.

Start a web call from the browser#

With a voice agent on the key, a page can create a web call directly:

const res = await fetch("https://api.tried.com.au/v3/create-web-call", {
  method: "POST",
  headers: {
    Authorization: "Bearer public_key_9c1e...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ recaptcha_token: token }),
});
const { call_id, access_token } = await res.json();

The key's voice agent is always used. Passing a different agent_id returns 403. The call's metadata records public_key_id and the page origin.

API#

Creating and deleting public keys is recorded in the audit log. For more abuse controls across the platform, see Prevent abuse.