Перейти к содержимому
ChatterfyСправочный центр
ГлавнаяGeneralCRMAI ManagerTrackerПлатформыAPIFAQUpdate log
Начало работы
Инструкции
Чаты и сообщения
Отправка сообщений
Изменение чата
Фильтры чатов
Выгрузка чатов
Реальное время
Аналитика и Tracker
Справочник
API и AI
  1. API
  2. Инструкции
  3. Новые сообщения в реальном времени через API

Новые сообщения в реальном времени через API

Реальное время — это способ узнавать о новых сообщениях и изменениях в чатах сразу, без постоянных повторных запросов. Chatterfy сам присылает событие вашей программе, как только что-то произошло. Ста

Обновлено 2 ноября 2026 г.4 мин
Реальное время — это способ узнавать о новых сообщениях и изменениях в чатах сразу, без постоянных повторных запросов. Chatterfy сам присылает событие вашей программе, как только что-то произошло.
Статья для программистов: подписке нужна программа, которая держит открытое соединение. Если вы не пишете код, используйте регулярные запросы — например, раз в несколько минут ищите чаты, в которых появились сообщения, как описано в статье Как выгрузить все чаты через API.



Как работают события в реальном времени

  1. 1

    Подпишитесь

    Отправьте обычный запрос к API. В ответ придут адрес и пропуск для постоянного соединения.
  2. 2

    Подключитесь

    Программа подключается по WebSocket к адресу ws_url с пропуском connection_token и подписывается на канал channel.
  3. 3

    Получайте события

    Chatterfy присылает событие на каждое изменение: новое сообщение, смену статуса, тега, ответственного.
  4. 4

    Продлевайте подписку

    Повторяйте запрос из первого шага, пока не истекло время 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.



Что важно учесть в подписке на события

  • Одно и то же событие может прийти дважды, например после переподключения. Обрабатывайте события так, чтобы повтор ничего не ломал.
  • Если соединение обрывалось надолго, перечитайте список чатов через поиск — часть событий могла потеряться.
  • Права ключа запоминаются в момент подписки. После смены роли подпишитесь заново.
  • Канал списка чатов привязан к вашему ключу: чужой пропуск к нему не подключится.



Частые вопросы

Нет, для подписки на события в реальном времени нужна программа. Без кода проверяйте изменения регулярными запросами или поручите это AI-ассистенту — Как подключить Chatterfy API к своему AI.

Нет, Chatterfy не отправляет события на ваш адрес, как вебхук. Соединение открывает ваша программа, а Chatterfy присылает события в него.

Ошибка realtime_unavailable значит, что сервер событий временно недоступен. Повторите запрос на подписку через несколько секунд.

Подписка на события живёт столько, сколько указано в expires_in_seconds, — сейчас 12 часов. Повторный запрос с тем же телом продлевает ту же подписку и возвращает тот же канал.

Нет, события подписки не тратят лимит запросов. Лимит в 120 запросов в минуту считает только запросы к API, в том числе запросы на подписку и продление.



Связанное

Как получить чаты и сообщения через API
Чаты и сообщения через API читаются двумя запросами: сначала список чатов бота, потом сообщения нужного чата. Это то же самое, что открыть бота в приложении и нажать на диалог. В статье — как получить
Фильтры чатов в API
Фильтр чатов — это условия, по которым API отбирает чаты: например, «непрочитанные», «с тегом Оплатил» или «пришли из Google». Один и тот же фильтр работает в поиске, подсчёте, выгрузке и подписке на
Как выгрузить все чаты через API
Выгрузка чатов — это способ забрать все чаты бота разом: в таблицу, в свою CRM или базу данных. Она читает снимок чатов на момент начала, поэтому ничего не пропускает и не повторяет, сколько бы чатов
Ошибки и лимиты API
Ошибка API — это ответ, в котором Chatterfy объясняет, почему не выполнил запрос. У всех ошибок одинаковый вид, поэтому разобраться можно по двум полям: коду ответа и code . В статье — как читать ошиб

Эта статья была полезна?

НазадКак выгрузить все чаты через APIДалееАналитика и Tracker через API

На этой странице

  • Как работают события в реальном времени
  • Подпишитесь на чаты бота
  • Какие события приходят по чатам бота
  • Подпишитесь на один чат
  • Пример подписки на JavaScript (Node.js)
  • Что важно учесть в подписке на события
  • Частые вопросы
  • Связанное