New real-time messages via API

Real-time is a way to learn about new messages and changes in chats immediately, without constant polling. Chatterfy sends an event to your program as soon as something happens. Article for programmer

Updated November 2, 20264 min

Real-time is a way to learn about new messages and changes in chats immediately, without constant polling. Chatterfy sends an event to your program as soon as something happens.

Article for programmers: the subscription requires a program that keeps a connection open. If you are not writing code, use regular requests — for example, look for chats where new messages have appeared every few minutes, as described in the article How to export all chats via API.

How real-time events work

Send a standard API request. You will receive an address and a token for a persistent connection in the response.

Connect

The program connects via WebSocket to the ws_url address with the connection_token and subscribes to the channel.

Receive events

Chatterfy sends an event for every change: a new message, or a change in status, tag, or assignee.

Renew the subscription

Repeat the request from the first step before the expires_in_seconds time runs out. Otherwise, events will stop arriving.

The event server operates on the Centrifugo protocol, so any Centrifugo client library will work: for JavaScript, Python, Go, Swift, Java, and Dart. See the list at centrifugal.dev.

Subscribe to bot chats

Subscription to all bot chats is opened by POST /chats/v1/realtime with bot_id in the body. The response contains the ws_url address, the connection_token, and the channel for connection:

POST

https://api.chatterfy.ai/public-api/chats/v1/realtime

Events for bot chats

curl -X POST 'https://api.chatterfy.ai/public-api/chats/v1/realtime' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"bot_id": "ID_БОТА"}'

You can pass the same filter to filter as in the search (Chat filters in the API). In that case, events will only come for matching chats. Pass the filter exactly as in the search: a differently written filter is a different channel.

{
  "channel": "messenger:list_019e1768-a39d-77d7-b444-4222455c14d8_bdb00b7759d6e539#01a035ee-9281-7043-acff-7ae77ba35ae0",
  "connection_token": "eyJhbGciOiJIUzI1NiIs...",
  "ws_url": "wss://rt.chatterfy.ai/connection/websocket",
  "expires_in_seconds": 43200
}

Field	What is this
`ws_url`	Address for WebSocket connection
`connection_token`	Connection token
`channel`	The channel to subscribe to
`expires_in_seconds`	How many seconds until the subscription expires if not renewed. 43,200 seconds — 12 hours

Which events are received for bot chats

Every bot chat subscription event has a kind field: bump, upsert, remove, or stale:

`kind`	What happened	What to do on your end
`bump`	New message received	Move the chat to the top of the list
`upsert`	Something else changed: status, assignee, tags, read status	Update the chat
`remove`	Chat deleted or no longer matches the filter	Remove the chat from the list
`stale`	The server could not determine what changed	Refetch this chat via `GET /chats/v1/{chat_id}`

{
  "kind": "bump",
  "bot_id": "019e1768-a39d-77d7-b444-4222455c14d8",
  "chat_id": "019e0112-dab8-7600-b1b8-8fd8c213e6aa",
  "cursor": "2026-08-31T17:37:19.841476Z",
  "chat": { "id": "019e0112-dab8-7600-b1b8-8fd8c213e6aa", "status": "manual" }
}

In bump and upsert events, the chat arrives in its entirety, in the chat field — usually, an additional request is not required.

Subscribe to a single chat

Subscription to single chat events is opened by POST /chats/v1/{chat_id}/realtime.

POST

https://api.chatterfy.ai/public-api/chats/v1/{chat_id}/realtime

Events within a single chat

A subscription to a single chat sends all events within the chat, including those not visible in the list. Besides connection_token, the response will include subscription_token — pass this when subscribing to the channel.

Events arrive with kind: "event", and the occurrence is described in payload_type:

`payload_type`	What happened
`messages/create`	New message. The message itself is in the `message` field
`messages/sent`	Message sent
`messages/event`	System event in chat
`messages/attach-file`	File attached to the message
`chats/edit`	Chat changed
`chats/delete`	Chat deleted
`chats/read-state`	Message read state changed

New values for payload_type may appear over time. Ignore those that your program does not recognize.

Example of subscribing in JavaScript (Node.js)

The program subscribes to all bot chats and prints each event. You need Node.js 22 or newer and the Centrifugo library: install it using the command npm install centrifuge.

import { Centrifuge } from "centrifuge";

const API = "https://api.chatterfy.ai/public-api";
const BOT_ID = "ID_БОТА";

async function subscribe() {
  const response = await fetch(`${API}/chats/v1/realtime`, {
    method: "POST",
    headers: { "ApiKey": process.env.CHATTERFY_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ bot_id: BOT_ID }),
  });
  if (!response.ok) throw new Error(await response.text());
  return response.json();
}

const first = await subscribe();

const centrifuge = new Centrifuge(first.ws_url, {
  token: first.connection_token,
  getToken: async () => (await subscribe()).connection_token,
});

const subscription = centrifuge.newSubscription(first.channel);

subscription.on("publication", ({ data }) => {
  console.log(data.kind, data.chat_id, data.chat?.last_message?.content ?? "");
});

subscription.subscribe();
centrifuge.connect();

setInterval(subscribe, first.expires_in_seconds * 500);

Запустите программу с ключом в переменной окружения: CHATTERFY_API_KEY='ВАШ_КЛЮЧ' node realtime.mjs. Подписка продлевается сама — каждые полсрока, а пропуск обновляется через getToken.