Chirio
Get Started
Introduction
Quickstart
How Chirio works
Authentication
MCP server
Platforms
Overview
Instagram
Threads
X
LinkedIn
Supa Hub
Guides
Connect accounts
Publish a post
Media requirements
Carousels
First comments
Idempotency and retries
Account lifecycle
Revocation and deletion
The dashboard
Products
Screenshots
Feedback boards
What's new
Inbox
Messages
Site analytics
Page comments
Billing
Plans
Metering
Quotas
Api Reference
Overview
Accounts
Posts
Errors
Changelog
Roadmap
TrademarkTrademark
Ctrl k
Search…
Sign up
Chirio
Get Started
Introduction
Quickstart
How Chirio works
Authentication
MCP server
Platforms
Overview
Instagram
Threads
X
LinkedIn
Supa Hub
Guides
Connect accounts
Publish a post
Media requirements
Carousels
First comments
Idempotency and retries
Account lifecycle
Revocation and deletion
The dashboard
Products
Screenshots
Feedback boards
What's new
Inbox
Messages
Site analytics
Page comments
Billing
Plans
Metering
Quotas
Api Reference
Overview
Accounts
Posts
Errors
Changelog
Roadmap
TrademarkTrademark© Dopler. All rights reserved.
Built with Aveiro

Messages

Private conversations between your team and your product's users: a chat widget, a team inbox, a server API and a signed webhook.
Updated 4 days ago
Inbox
Site analytics
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 });
Then add the widget:
<script src="https://chirio.dev/messages-widget.js"
        data-token-url="/api/chirio/messages-token" data-lang="en" async></script>
What a person sees depends on their 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/conversationsList or start conversations
    GET, PATCH/api/v1/conversations/:idRead or change one
    GET, POST/api/v1/conversations/:id/messagesRead or send messages
    POST/api/v1/conversations/:id/readMark read
    POST/api/v1/conversations/identifyMint 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.
    curl https://chirio.dev/api/v1/message-settings \
      -H "Authorization: Bearer chirio_sk_..." \
      -H "Content-Type: application/json" \
      -d '{ "webhookUrl": "https://example.com/api/chirio/messages" }'