Skip to content
TriedDocs
Deploy

Chat widget and public keys

Add a chat agent to any website with one script tag, and control browser access with public keys, allowed domains, reCAPTCHA v3, rate limits and blocked countries.

The chat widget is a chat bubble that runs a chat agent on your website. It loads from one script tag served by the Tried API (/widget.js). A public key decides which chat agent answers, which domains may use it, and what abuse protection applies. The same key can also let your page start browser voice calls.

Set up the widget#

Create a chat agent#

Go to Chat Agents and create one, or convert an existing voice agent.

Add a public key#

Open the Website widget tab and click Add public key. Give it a Name, choose the agent under Chat agents, and list Allowed domains. Click Create key.

Copy the snippet#

Click Snippet on the key. Paste the code before the closing </body> tag on any page of an allowed domain.

Try it#

Click Demo to open a demo page that loads the widget with this key.

The Website widget tab listing public keys with Edit, Snippet and Demo buttons

The snippet looks like this:

<script src="https://api.tried.com.au/widget.js" data-public-key="public_key_c6190cdfff21015a05ac4e386d1158ce" async></script>

Widget options#

Set these as attributes on the script tag.

Attribute Default Description
data-public-key required The public key. Without it the widget logs an error and does not render.
data-title Chat with us Header text and button label.
data-color #18181b Button, header and user bubble colour.
data-api the API's public URL API base, for self-hosted or staging APIs.
data-recaptcha-site-key RECAPTCHA_SITE_KEY on the API reCAPTCHA v3 site key. When set, the widget loads reCAPTCHA and sends a token when a chat starts.
data-recaptcha-mock-score none Test only: in mock mode, sends mock:<score> instead of a real token.

The widget renders a round button at the bottom right of the page. Clicking it opens a 340 by 460 pixel panel and starts the chat. When the visitor leaves the page, the widget ends the chat with a beacon request, which triggers post-chat analysis and the chat_ended webhook.

Public keys#

A public key (public_key_...) is safe to put in a web page. It is not an API key: it only works from an allowed origin and only on these routes:

  • POST /public/chat/start, /public/chat/:id/message and /public/chat/:id/end (the widget)
  • POST /v3/create-web-call, /create-chat, /create-chat-completion and /end-chat/:id with Authorization: Bearer public_key_...

Every other route returns 403 for a public key.

The Add public key dialog with an A/B split across two chat agents, allowed domains and abuse protection
Dashboard field API field Description
Name name Label. Default Website widget, up to 80 characters.
Chat agents chat_agent_id or chat_agents One chat agent, or up to 10 weighted chat agents for an A/B split.
Voice agent for web calls agent_id Optional. Lets the page start browser voice calls with this key.
Allowed domains allowed_domains 1 to 20 entries: example.com, *.example.com, localhost, optionally with a port.
reCAPTCHA v3 recaptcha_enabled Require a reCAPTCHA v3 token. Default off.
Minimum score recaptcha_threshold 0 to 1. Requests scoring below this are refused. Default 0.5.
Requests per minute rate_limit_per_minute Limit for the whole key, 1 to 10000. Empty means no key-wide limit.
Blocked countries blocked_countries Two-letter country codes refused for this key.

A key needs at least one of chat_agent_id, chat_agents or agent_id.

API: GET /public-keys, POST /public-keys, PATCH /public-keys/:id, DELETE /public-keys/:id.

How a request is checked#

  1. Origin. The Origin header must match an allowed domain. *.example.com matches subdomains and example.com itself. An entry with a port only matches that port.
  2. Blocked countries. The visitor's country comes from the cf-ipcountry, x-vercel-ip-country or x-country-code header set by your CDN or load balancer. Without one of those headers, this check is skipped.
  3. Per-IP limit. Each IP may make 30 requests per minute per key (PUBLIC_KEY_IP_RATE_PER_MINUTE). Over the limit returns 429.
  4. Key limit. When Requests per minute is set, the whole key is limited. Over the limit returns 429.
  5. reCAPTCHA. When on, the token from the request body (recaptcha_token) or the x-recaptcha-token header is verified with Google. A failed check or a low score returns 403.
  6. Credit. If the workspace is out of credit or over its monthly budget, the request returns 402.
Needs keys

Real reCAPTCHA verification needs RECAPTCHA_SECRET on the API (and a site key in the widget). Without the secret, verification is mocked: a missing token scores 0, mock:<score> scores that value, and any other token scores 0.9.

A/B test chat agents#

Add a second agent under Chat agents (Add an A/B variant) and give each a weight. New chats pick an agent at random by weight; the dashboard shows each weight as a percentage. The pick is stored on the chat in metadata.ab_test, so you can compare results in Chat History. The split is across chat agents, not versions of one chat agent. See A/B testing.

Start chats and calls from your own front end#

If you build your own chat UI, call the chat API from the browser with the public key:

const res = await fetch("https://api.tried.com.au/create-chat", {
  method: "POST",
  headers: { Authorization: `Bearer ${PUBLIC_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ recaptcha_token: token }),
});

With a public key, create-chat uses the key's chat agents (a chat_agent_id that is not on the key returns 403), and create-web-call always uses the key's voice agent. Tried adds public_key_id and origin to the metadata.

Limits and gotchas#

  • Requests without an Origin header are refused, so the key does not work from server code or cURL.
  • localhost is accepted as a domain for testing. Remove it before going live.
  • Chats are billed per message.
  • Blocked countries only work behind a CDN or proxy that sets a country header.