Chat API reference: conversations, messages, read receipts and events

How to call the Hibira Chat API: signed requests, conversations and members, messages, catching up, read receipts and unread counts, user tokens for browsers, attachments, push, moderation, events and limits.

Before you start

The Chat API stores conversations and their messages and delivers them over the realtime connection your app already has. Your server decides who is in each conversation and calls the API; clients connect, sign in and listen.

• It is in beta. An account can use it once it is in the beta or holds a Chat add-on. Until then every call answers 403 the Chat API is not enabled for this app. Join the waitlist to get in.
• Base URL: https://ws.hibira.io/apps/APP_ID/chat (use your app's host from its page in the portal).
• Bodies are JSON. Errors are {"error": "..."} with a 4xx or 5xx status.
• Your users' IDs are your own: use the same IDs your clients pass to pusher.signin().

How it works

1. Your server creates a conversation and its members (PUT /conversations/{id}).
2. Each client connects with pusher-js and calls pusher.signin() as its user. That subscribes it to #server-to-user-<user_id>, so a member needs no channel authorization per conversation.
3. Your server sends a message on a user's behalf (POST /conversations/{id}/messages). Hibira stores it with the conversation's next sequence number (seq), then sends chat.message to every member and calls your chat_message webhook.
4. A client that was offline reads what it missed with GET /conversations/{id}/messages?after=<last seq it has>.

Every change is stored before any event is sent. If the app is over its daily message quota the change is still stored but no events go out, so clients catch up by reading.

Signing requests

Requests from your server are signed exactly like the rest of the Pusher HTTP API, with the app key and secret: the query string carries auth_key, auth_timestamp, auth_version=1.0, body_md5 (when there is a body) and auth_signature, the HMAC-SHA256 of METHOD\nPATH\nQUERY with the query parameters sorted by name. Any Pusher server library's signing code works; this is the whole thing in Node.js:

import crypto from 'node:crypto';

const { PUSHER_APP_ID: id, PUSHER_APP_KEY: key, PUSHER_APP_SECRET: secret } = process.env;

export async function chat(method, path, body) {
  const fullPath = `/apps/${id}/chat${path}`;
  const json = body === undefined ? '' : JSON.stringify(body);
  const params = { auth_key: key, auth_timestamp: Math.floor(Date.now() / 1000), auth_version: '1.0' };
  if (json) params.body_md5 = crypto.createHash('md5').update(json).digest('hex');
  const query = Object.keys(params).sort().map((k) => `${k}=${params[k]}`).join('&');
  const signature = crypto.createHmac('sha256', secret).update(`${method}\n${fullPath}\n${query}`).digest('hex');
  const res = await fetch(`https://ws.hibira.io${fullPath}?${query}&auth_signature=${signature}`, {
    method, body: json || undefined, headers: { 'Content-Type': 'application/json' },
  });
  if (!res.ok) throw new Error(`${res.status} ${(await res.json()).error}`);
  return res.json();
}

await chat('PUT', '/conversations/order-1042', { name: 'Order #1042', members: ['ann', 'support-bob'] });
await chat('POST', '/conversations/order-1042/messages', { user_id: 'ann', name: 'Ann', text: 'Where is my parcel?' });

Query parameters of a GET (such as after or limit) are part of the signed query too.

Conversations and members

A conversation:

{"id": "order-1042", "name": "Order #1042", "metadata": {"kind": "support"},
 "members": [{"user_id": "ann", "read_seq": 3}, {"user_id": "support-bob", "read_seq": 1, "role": "agent"}],
 "last_seq": 3, "created_at": "...", "updated_at": "..."}

Roles and internal notes. A message with visible_to (up to 5 roles) reaches only members with one of those roles: everyone else never receives it, reads it or counts it as unread. Watchers are private or presence channels that receive every event of the conversation, so a team inbox follows all of its conversations with one subscription. Authorize only your staff on them.

Messages

A message:

{"id": "...", "seq": 3, "sender": "ann", "name": "Ann", "kind": "text",
 "text": "hi", "metadata": {"reply_to": 2}, "reactions": {"👍": ["support-bob"]}, "created_at": "..."}

An edited message keeps its seq and gets edited_at. A deleted one keeps its place with deleted_at and no text, and can no longer be edited or reacted to (409). Reading after a number only returns newer messages, so a client that comes back re-reads the messages it shows (last=n) to pick up edits, deletes and reactions. Search matches any part of a word, ignoring case and full-width forms, so it works for Chinese, Japanese and Korean. System messages say what happened (joined, transferred, closed): only your server posts them, and they are never pushed or counted as unread.

Read receipts and unread counts

How far a member has read only moves forward and is capped at last_seq; the sender of a message has read it. unread in a user's conversation list counts the messages after their read_seq that are not system messages. Every member gets chat.read when someone's read_seq moves.

Browsers and apps: user tokens

Clients can call the Chat API themselves under /apps/APP_ID/chat/me, with Authorization: Bearer <user token> and no proxy on your server. The token is a JWT signed with the app secret (HS256, {sub, exp}, at most 30 days); your server makes one with any JWT library or with POST /tokens:

With a token, a client lists its conversations (GET /me/conversations), reads, searches, sends, edits and deletes its own messages, reacts, marks read and sends typing. The user is always the token's sub. A client cannot create conversations, change members, set push options, mute or ban: those stay on your server. Each user may write at most 2 times a second, in bursts of up to 10. A token with conversation_id and join suits anonymous visitors of a support chat: your server creates the conversation, checks the visitor, then issues a short-lived token for an ID it makes up.

Attachments

1. Your server asks for an upload: POST /conversations/{id}/attachments with user_id, name, content_type and size (up to 25 MB). The answer has attachment and upload (url, method, headers).
2. The client uploads the file straight to upload.url within 15 minutes, with exactly those headers.
3. Your server sends the message with attachments: the id, name and content_type from step 1 (up to 10 per message; text may then be empty).

Each attachment read from the API or an event carries a url that downloads it for an hour. Uploads not sent within a day are removed, and deleting a message or a conversation deletes its files.

Push to offline members

A new message is pushed through the app's Hibira Push to members who are not connected (push: "offline", the default), to every member but the sender ("always"), or to nobody ("never"). The title is the sender's and the conversation's name (or push_title), the body the first 180 characters of the text, and push_url opens when it is tapped. Devices register with the Beams-compatible push SDKs under the same user IDs. The answer's push says how many members were pushed, or why none were.

Moderation

The word filter checks every new or edited message, inside words and ignoring case and full-width forms, so it also catches Chinese and Japanese. mask replaces each match with ＊; reject answers 422 and stores nothing. A banned user gets 403 on send, edit, reactions and typing in every conversation of the app; a muted member gets 403 on send and typing in that conversation and can still read it.

Events and webhook

Events go to #server-to-user-<user_id> of each member concerned, and to the conversation's watchers. Each one counts as one message toward the daily quota.

const pusher = new Pusher('APP_KEY', { cluster: 'hkg', wsHost: 'ws.hibira.io', userAuthentication: { endpoint: '/pusher/user-auth' } });
pusher.signin();
pusher.user.bind('chat.message', ({ conversation_id, message }) => showMessage(conversation_id, message));

Your server also gets the chat_message webhook for every new message: channel is the conversation ID, user_id the sender, and data the JSON {"conversation_id", "message"}. Add chat_message to the events of one of the app's webhooks to receive it.

Limits

Writes share the app's HTTP API rate limit (429 beyond it).

Monthly active users and retention

A user is active in a month (UTC) when they send a message or mark a conversation read, counted once across all of the account's apps. Every account includes 500 a month; the Chat add-ons raise it to 1,000, 5,000, 20,000 or 60,000 (plans). Once the month is full, a user not yet counted gets 429 on send and read until the next month; users already counted carry on. GET /usage answers {month, active_users, limit}.

Messages stay fully editable for 30 days. After that, accounts with a paid plan or a Chat add-on keep them in an archive that the API keeps returning (read-only); on the Free plan without an add-on they are deleted.

Using it from an AI agent

The Hibira MCP server has Chat API tools, so an AI coding agent can set up and test chat for you: create_conversation, send_message, list_conversations and list_messages. They act on your own apps with the same checks as a signed request, and need the account to have the Chat API. The agent plugin for Claude Code, Codex, Cursor and others adds a skill that wires the Chat API into a project with these steps. For a ready conversation view in React or plain JavaScript, see @hibira-io/chat-ui.