Messages are private conversations between your team and your own users: a venue and its guests, a site and its visitors, an agency and its clients. Chirio stores them and gives you a chat widget, a team inbox you can embed in your admin, a server API and a webhook. People are identified by your own user ids; Chirio never signs them in.Two fields organise conversations. profileId says whose customers they are, such as venue:42 or an organisation. topicRef says what a conversation is about, such as booking:981.
On your site
Your server mints a participant token for the signed-in person:
// Your route, e.g. GET /api/chirio/messages-token, behind your own session
const res = await fetch("https://chirio.dev/api/v1/conversations/identify", {
method: "POST",
headers: { authorization: `Bearer ${process.env.CHIRIO_API_KEY}`, "content-type": "application/json" },
body: JSON.stringify({ id: user.id, name: user.name, role: "customer", profileId: "venue:42" }),
});
return Response.json({ token: (await res.json()).token });
A customer with a profileId gets a chat button, sees their own conversations there and can start one. data-subject names it, such as the venue's name.
A customer without a profileId gets their inbox across every profile, where they answer but do not start.
A team member (role: "team") sees the profile's inbox, waiting for a reply, open and closed, answers and closes.
For the team inbox inside your admin, set data-launcher="false" and call window.ChirioMessages.embed(element). ChirioMessages.unread() and the chirio:messages-unread event give you a badge count. Other options: data-lang (en, hu), data-topic, data-position, data-offset and data-signin-url, which gives people without a token a sign-in button.
From your server
With your API key:
Method
Path
Purpose
GET, POST
/api/v1/conversations
List or start conversations
GET, PATCH
/api/v1/conversations/:id
Read or change one
GET, POST
/api/v1/conversations/:id/messages
Read or send messages
POST
/api/v1/conversations/:id/read
Mark read
POST
/api/v1/conversations/identify
Mint a participant token
The list filters by profileId, topicRef, participant, status and needsReply, and since returns only conversations with a message after a time, which makes polling cheap. Starting a conversation reuses the customer's open one on the same profile and topic unless you send reuseOpen: false.
A message holds up to 8,000 characters and up to 3 attachments of 3.2 MB each.
Webhook
Set one webhook per project:
Every new message is posted there with chirio-event: message.created and a chirio-signature header: t=<unix>,v1=<hex>, an HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with your webhookSecret from GET /api/v1/message-settings. Verify it before you trust the body. Delivery is one attempt with a 5-second timeout, so treat the webhook as a nudge and the API as the record. Send webhookUrl: null to remove it.
Retention
The same settings take retentionMonths, 0 to 120 (default 24), for the project or per profileId. Quiet conversations past it are deleted with their files every night.
Limits
Messages cost no units. Each plan caps the messages stored per calendar month, from every side of every conversation: 1,000 on Free, 20,000 on Indie, 100,000 on Studio and 500,000 on Scale. Past it, new messages are refused with 429 message_limit until the month turns. Nothing is billed.
From an agent
The MCP server has list_conversations, get_conversation, reply_to_conversation (as the assistant by default) and update_conversation, so an agent can answer people and close conversations it resolved.