Новые сообщения в реальном времени через API
Реальное время — это способ узнавать о новых сообщениях и изменениях в чатах сразу, без постоянных повторных запросов. Chatterfy сам присылает событие вашей программе, как только что-то произошло. Ста
Реальное время — это способ узнавать о новых сообщениях и изменениях в чатах сразу, без постоянных повторных запросов. Chatterfy сам присылает событие вашей программе, как только что-то произошло.
Статья для программистов: подписке нужна программа, которая держит открытое соединение. Если вы не пишете код, используйте регулярные запросы — например, раз в несколько минут ищите чаты, в которых появились сообщения, как описано в статье Как выгрузить все чаты через API.
Как работают события в реальном времени
Подпишитесь
Отправьте обычный запрос к API. В ответ придут адрес и пропуск для постоянного соединения.Подключитесь
Программа подключается по WebSocket к адресуws_urlс пропускомconnection_tokenи подписывается на каналchannel.Получайте события
Chatterfy присылает событие на каждое изменение: новое сообщение, смену статуса, тега, ответственного.Продлевайте подписку
Повторяйте запрос из первого шага, пока не истекло времяexpires_in_seconds. Иначе события перестанут приходить.
Сервер событий работает по протоколу Centrifugo, поэтому подойдёт любая клиентская библиотека Centrifugo: для JavaScript, Python, Go, Swift, Java и Dart. Список — на сайте centrifugal.dev.
Подпишитесь на чаты бота
Подписку на все чаты бота открывает
POST /chats/v1/realtime с bot_id в теле. В ответе — адрес ws_url, пропуск connection_token и канал channel для подключения:POST
https://api.chatterfy.ai/public-api/chats/v1/realtime
События по чатам бота
Запросbash
curl -X POST 'https://api.chatterfy.ai/public-api/chats/v1/realtime' \
-H 'ApiKey: ВАШ_КЛЮЧ' \
-H 'Content-Type: application/json' \
-d '{"bot_id": "ID_БОТА"}'В
filter можно передать тот же фильтр, что и в поиске (Фильтры чатов в API). Тогда события придут только по подходящим чатам. Передавайте фильтр в точности как в поиске: по-другому записанный фильтр — это другой канал.Ответjson
{
"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
}Поле | Что это |
|---|---|
ws_url | Адрес для подключения по WebSocket |
connection_token | Пропуск для подключения |
channel | Канал, на который нужно подписаться |
expires_in_seconds | Через сколько секунд подписка закончится, если её не продлить. 43 200 секунд — 12 часов |
Какие события приходят по чатам бота
У каждого события подписки на чаты бота есть поле
kind: bump, upsert, remove или stale:`kind` | Что случилось | Что сделать у себя |
|---|---|---|
bump | Пришло новое сообщение | Поднять чат наверх списка |
upsert | Изменилось другое: статус, ответственный, теги, прочтение | Обновить чат |
remove | Чат удалён или больше не подходит под фильтр | Убрать чат из списка |
stale | Сервер не смог определить, что изменилось | Перечитать этот чат через GET /chats/v1/{chat_id} |
Событиеjson
{
"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" }
}В событиях
bump и upsert чат приходит целиком, в поле chat, — обычно дополнительный запрос не нужен.Подпишитесь на один чат
Подписку на события одного чата открывает
POST /chats/v1/{chat_id}/realtime.POST
https://api.chatterfy.ai/public-api/chats/v1/{chat_id}/realtime
События внутри одного чата
Подписка на один чат присылает все события внутри чата, в том числе те, что не видны в списке. Кроме
connection_token, в ответе будет subscription_token — передайте его при подписке на канал.События приходят с
kind: "event", а что случилось, написано в payload_type:`payload_type` | Что случилось |
|---|---|
messages/create | Новое сообщение. Само сообщение — в поле message |
messages/sent | Сообщение отправлено |
messages/event | Системное событие в чате |
messages/attach-file | К сообщению прикрепился файл |
chats/edit | Изменился чат |
chats/delete | Чат удалён |
chats/read-state | Изменилось прочтение сообщений |
Со временем могут появиться новые значения
payload_type. Пропускайте те, которые ваша программа не знает.Пример подписки на JavaScript (Node.js)
Программа подписывается на все чаты бота и печатает каждое событие. Нужен Node.js 22 или новее и библиотека Centrifugo: установите её командой
npm install centrifuge.realtime.mjsjavascript
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.Что важно учесть в подписке на события
- Одно и то же событие может прийти дважды, например после переподключения. Обрабатывайте события так, чтобы повтор ничего не ломал.
- Если соединение обрывалось надолго, перечитайте список чатов через поиск — часть событий могла потеряться.
- Права ключа запоминаются в момент подписки. После смены роли подпишитесь заново.
- Канал списка чатов привязан к вашему ключу: чужой пропуск к нему не подключится.
Частые вопросы
Связанное
Эта статья была полезна?

