Put Chinwagly on your site, and teach it who's who.
One script tag adds the messenger. A small JavaScript API names signed-in users and opens the messenger for a team, and signed webhooks let your own bot answer visitors.
Install the messenger
The snippet
Sign in and open Settings › Install on your site. It shows your workspace's snippet with
its public key filled in, and a button to copy it. Paste it before </body> on
every page that should show the messenger:
<script src="https://app.chinwagly.com/widget/chinwagly.js"
data-chinwagly-key="pk_your_key" async></script>
The key starts pk_ and is public: it only lets visitors talk to your workspace, so it
is safe in your page source. A visitor gets a contact the first time they write. Their messenger
keeps a token in localStorage and listens for replies on a WebSocket, so a
conversation carries on across page loads.
Script options
| Attribute | What it does |
|---|---|
data-chinwagly-key |
Your workspace's public key. Required. |
data-title-alert="false" |
Stops the messenger alternating your page's title with "New message from …" when a reply arrives while the page is in the background. On by default. |
The messenger draws inside a shadow root on a #chinwagly-messenger element, so your
site's styles don't reach it and its styles don't reach your site.
JavaScript API
Once it starts, the messenger puts window.Chinwagly on the page with three functions:
identify, logout and open.
Calling before it loads
The script loads async, so define a small queue first. Calls made before the messenger
starts wait in q, and it runs them in order when it loads:
<script>
window.Chinwagly = window.Chinwagly || {
q: [],
identify(user) { this.q.push(['identify', user]); },
logout() { this.q.push(['logout']); },
open(options) { this.q.push(['open', options]); }
};
</script>Chinwagly.identify(user)
When your site knows who the visitor is, tell the messenger:
Chinwagly.identify({
id: 'u_42',
name: 'Maya Okafor',
email: '[email protected]',
user_hash: '…', // from your server
plan: 'Pro' // an attribute
});id(required) is your own user id, a string or number.-
nameandemailreplace the generated name ("Calm Otter"). With an email, replies can reach the visitor after they leave (Replies by email). - Every other field becomes a custom attribute in the inbox's contact panel: up to 50, with names of 1 to 50 characters and values that are text (up to 500 characters), numbers, true/false or null. Lists and objects are refused.
An anonymous visitor who is then identified is merged into the contact already known by that id, conversations and all, so history follows the user across browsers and devices.
Identity verification
Without verification, any page with your key could claim to be any user and read their
conversations. Prove each identify call came from you with user_hash: the hex
HMAC-SHA256 of the user id, keyed with the Identity secret under Settings › Visitors.
Compute it on your server, never in the browser, and render it into the page:
import { createHmac } from 'node:crypto';
const userHash = createHmac('sha256', process.env.CHINWAGLY_IDENTITY_SECRET)
.update(String(user.id))
.digest('hex');$userHash = hash_hmac('sha256', (string) $user->id, $identitySecret);import hashlib, hmac
user_hash = hmac.new(identity_secret.encode(), str(user.id).encode(), hashlib.sha256).hexdigest()- A hash that doesn't match the id is always refused.
- With Require identity verification on (Settings › Visitors), identify calls without a hash are refused too.
- Once a user has been verified, nobody can claim them without a hash, even with it off.
Chinwagly.logout()
Call it when the user signs out of your site. The messenger forgets them and starts a fresh, anonymous visitor, so the next person on that browser can't see their conversations.
Chinwagly.open(options) and teams
Chinwagly.open() opens the messenger on the visitor's ordinary conversation. To send
them to a team, pass the team's address from Settings › Teams:
<button onclick="Chinwagly.open({ team: 'billing' })">Ask billing</button>Each team keeps its own conversation with the visitor, which starts in that team's inbox. The messenger's header shows the team's name and its own hours ("Away right now · usually here Mon–Fri 10:00–14:00"). An address Chinwagly doesn't know opens the ordinary conversation instead, with a warning in the browser console.
The ready event
When the messenger has started and run any queued calls, it fires chinwagly:ready on
window:
window.addEventListener('chinwagly:ready', () => {
document.querySelector('#help-button').hidden = false;
});Bots
An external bot is your own service answering visitors in Chinwagly. Chinwagly posts signed webhooks to it about the conversations it holds, and it answers through the bot API with a bearer token: it can reply, read the conversation, show that it's typing, and hand over to the team.
Setting one up
In the inbox, open Settings › Bots › New external bot, name it and give the address Chinwagly should post to. Chinwagly then shows two credentials, once:
-
Signing secret (
whsec_…) verifies that a webhook really came from Chinwagly. -
Bearer token (
rbt_…) authenticates your bot's calls to the bot API. Chinwagly keeps only its hash, so store it somewhere safe.
A conversation reaches the bot when an agent picks it under Assign… › Hand to a bot, or
when an automation's Hand to a bot action fires. It sits in the inbox's With bot
view until the bot hands over or an agent takes it (pressing A, or replying). From
then on the bot API refuses that bot's calls on the conversation.
Webhooks
Chinwagly sends a POST with a JSON body for each event in a conversation the bot holds:
type | When |
|---|---|
conversation.assigned |
The conversation was just handed to the bot. message is
null; fetch the history.
|
conversation.visitor_message |
The visitor wrote while the bot holds the conversation. |
{
"id": "evt_Q2l1cmVudGx5IGEgcmFuZG9t",
"type": "conversation.visitor_message",
"created_at": "2026-11-15T11:13:04.120Z",
"bot": { "id": 2, "name": "Echo bot" },
"conversation": {
"id": 19,
"status": "open",
"title": "Where is my parcel?",
"page_url": "https://shop.example/orders",
"contact": { "id": 19, "name": "Daring Heron" },
"created_at": "2026-11-15T11:12:58.004Z"
},
"message": {
"id": 233,
"author": "contact",
"agent_name": null,
"body": "Can I talk to a human please?",
"created_at": "2026-11-15T11:13:04.120Z"
}
}
Answer with any 2xx quickly and do the work afterwards. Chinwagly waits up to 10
seconds per attempt. A timeout, connection error or non-2xx answer is retried twice,
after 1 s and then 2 s, with the same body and signature each time. If every attempt fails, the
conversation stays with the bot, so a person can take over from the With bot view. Internal notes
never trigger a webhook.
Checking the signature
Every webhook carries a header:
Chinwagly-Signature: t=1794741184,v1=5f2c…e9a1
v1 is the hex HMAC-SHA256, keyed with your signing secret, of the timestamp, a full
stop and the raw request body: "<t>.<body>". Signing the time too stops an
old delivery being replayed. To verify:
- Split the header on
,and readtandv1. -
Compute
HMAC_SHA256(secret, t + "." + raw_body)over the bytes exactly as received, before parsing the JSON. -
Compare with
v1in constant time, and reject atmore than five minutes from your clock.
import { createHmac, timingSafeEqual } from 'node:crypto';
function fromChinwagly(header, rawBody, secret) {
const { t, v1 } = Object.fromEntries(header.split(',').map((part) => part.split('=')));
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
const given = Buffer.from(v1 ?? '', 'hex');
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
return fresh && given.length === expected.length && timingSafeEqual(given, expected);
}The bot API
The base address is https://app.chinwagly.com/api/bot/v1. Every call sends
Authorization: Bearer <token>. A bot sees only conversations in its own
workspace, and acts only on those it holds:
| Status | Meaning |
|---|---|
401 | The token is missing or unknown. |
404 | No such conversation in the bot's workspace. |
403 |
The conversation is in the workspace but not with this bot, perhaps because an agent took it over. Stop. |
422 | The body is invalid; errors says which field. |
GET /conversations/{id}
The conversation and every message the visitor can see (theirs, the team's, bots' and automated replies), oldest first. Internal notes and timeline lines are left out.
{
"conversation": {
"id": 19, "status": "open", "title": "Where is my parcel?", "page_url": "…",
"contact": { "id": 19, "name": "Daring Heron" }, "created_at": "…"
},
"messages": [
{ "id": 230, "author": "contact", "agent_name": null, "body": "Where is my parcel?", "created_at": "…" },
{ "id": 231, "author": "automated", "agent_name": null, "body": "Thanks for writing!", "created_at": "…" }
]
}POST /conversations/{id}/messages
Body {"text": "…"}. Sends a reply the visitor sees under the bot's name. Answers
201 with the message.
POST /conversations/{id}/hand_over
Body {"summary": "…"}, up to 2,000 characters. The conversation moves to
Unassigned, the summary becomes an internal note only the team sees, and agents get a
notification. After this the bot's calls on the conversation answer 403.
POST /conversations/{id}/typing
Body {} or {"active": false}. Shows the visitor "<bot name> is
typing…" while your bot works. It fades after about six seconds, so call it again every few
seconds for longer work. Your reply clears it, as does {"active": false}. Answers
204.
Trying it with curl
TOKEN=rbt_… # from Settings › Bots
CHINWAGLY=https://app.chinwagly.com
ID=19 # a conversation handed to the bot
curl -s "$CHINWAGLY/api/bot/v1/conversations/$ID" -H "Authorization: Bearer $TOKEN"
curl -s -X POST "$CHINWAGLY/api/bot/v1/conversations/$ID/messages" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"text": "Your parcel left our warehouse this morning."}'
curl -s -X POST "$CHINWAGLY/api/bot/v1/conversations/$ID/hand_over" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"summary": "Asked where order 4411 is; told them it shipped today. Wants a delivery date."}'The built-in AI bot
No bot of your own? Settings › Bots › New AI bot makes one with a name, instructions and
a knowledge text, and no code. It answers with Claude (claude-sonnet-5-5, or
claude-haiku-5-5 for speed), from your instructions, your knowledge and the published
help articles that match the visitor's latest messages. Replies are capped at 1,024 tokens.
- It hands over to the team when it's unsure, at once when the visitor asks for a person, and when the model fails or declines to answer.
- While it thinks, the visitor sees "<bot name> is typing…". If they write again before it answers, it answers both messages once rather than twice.
- If Settings says the AI bot is unavailable, conversations handed to it go straight back to Unassigned with a note saying why.
Replies by email
Visitors often close the tab before the team answers. When an agent replies (not a bot, an automation or a note) to a visitor who has left, and the contact has an email address, Chinwagly sends the reply by email about a minute later. If the visitor comes back and reads it in the messenger first, the email is skipped.
- The email comes from your team ("Sam at Northwind support") with the subject "Re: <the conversation's first line>", and the timeline notes that it was emailed.
- The visitor's emailed answer threads back into the same conversation through a signed reply address, with the quoted text and signatures stripped, and reopens it if it was closed.
-
The email address comes from the messenger ("Get replies by email"), from an agent in the
contact panel, or from your site through
identify.