ВойтиНачать бесплатный пробный период
easyCoexistence Официальные API

Как узнать, что подключение клиента к WhatsApp или соцсети отключилось

easyCoexistence отправляет вашей платформе подписанные события статуса, когда подключение клиента подключается, отключается, удаляется или приостанавливается. Для номера WhatsApp это connection.connected, connection.disconnected с причиной от Meta, connection.removed, connection.suspended или connection.token_missing. Для аккаунта в соцсети приходят аналогичные события channel.*, но без token_missing. Каждое событие отправляется как JSON POST-запрос, подписывается заголовком X-EC-Signature и повторяется с нарастающими паузами около 33 часов, пока ваш эндпоинт не ответит 2xx.

~14 days

PRIMARY_INACTIVITY: причина от Meta, когда основное устройство было неактивно примерно 14 дней, из-за чего номер Coexistence отключается.

~30 days

COMPANION_INACTIVITY: причина от Meta, когда сопутствующее устройство было неактивно примерно 30 дней.

account_update

Вебхук, который сообщает об отключении. Meta всегда отправляет его на основной callback URL приложения, никогда на переопределённый.

7 attempts

Как часто повторно пробуется событие статуса после любого ответа, отличного от 2xx: с интервалами от 1 минуты до 24 часов, около 33 часов в сумме.

5 minutes

Самая старая метка времени t подписи, которую эндпоинт должен принимать для события статуса, при сравнении HMAC за постоянное время.

Какие бывают события статуса?

Девять, в двух семействах, которые используют один эндпоинт и один секрет подписи. Для номеров используется connection.*, для аккаунтов в соцсетях channel.*, поэтому получатель, написанный для номеров, может пропускать события channel по имени. Эндпоинт задаётся в панели управления в разделе «Profile», затем «Developers», или через инструмент MCP set_partner_events_url. Секрет подписи показывается один раз, при сохранении URL.

connection.connectedA number connected, came back after a drop, or got its customer token on a second run.
connection.disconnectedMeta dropped the link; reason carries Meta's code when known.
connection.removedRemoved with DELETE /connections/{id} or from the dashboard.
connection.suspendedYour subscription lapsed; reason names its state.
connection.token_missingConnected without a customer token: it receives, but cannot send yet.
channel.connectedA social account connected, one event per Page when a sign-in brings several.
channel.disconnectedThe network refused the token, or the owner withdrew access.
channel.removedRemoved with DELETE /channels/{id} or from the dashboard, or the owner removed the app on Meta.
channel.suspendedYour subscription lapsed.

Что содержит событие подключения?

id доставки (UUID), имя события, occurred_at в формате ISO 8601 и объект connection с полями id, external_ref, connect_session_id, phone, name, waba_id, phone_number_id, status и token_ready. Некоторые события добавляют поле верхнего уровня: reason в connection.disconnected и connection.suspended; detected_by со значением health_check, когда собственная периодическая проверка easyCoexistence обнаружила отключение, а не вебхук Meta; и connect_session_id, когда событие вызвала сессия подключения.

connection.disconnected
{
  "id": "5c2a9e70-…",
  "event": "connection.disconnected",
  "occurred_at": "2026-10-31T10:15:02.114Z",
  "connection": {
    "id": "<CONNECTION_ID>",
    "external_ref": "customer_4821",
    "connect_session_id": "cs_…",
    "phone": "+55 11 9…",
    "name": "Clínica Sorriso",
    "waba_id": "<WABA_ID>",
    "phone_number_id": "<PHONE_NUMBER_ID>",
    "status": "disconnected",
    "token_ready": true
  },
  "reason": "PRIMARY_INACTIVITY"
}

Что содержит событие канала?

Тот же конверт, но вместо connection объект channel. Это представление GET /channels/{id}: id, channel для сети, external_ref, connect_session_id, name, username, external_id, status, token_ready, webhook_url, disconnected_reason, last_checked_at и created_at. Для каналов token_missing нет, так как вход через соцсеть всегда выдаёт собственный токен клиента. channel.connected, пришедшее из сессии подключения, также содержит connect_session_id на верхнем уровне.

channel.disconnected
{
  "id": "0b7e41d2-…",
  "event": "channel.disconnected",
  "occurred_at": "2026-10-31T10:15:02.114Z",
  "channel": {
    "id": "<CHANNEL_ID>",
    "channel": "tiktok",
    "external_ref": "customer_4821",
    "connect_session_id": "cs_…",
    "name": "Clínica Sorriso",
    "username": "clinicasorriso",
    "external_id": "<TIKTOK_OPEN_ID>",
    "status": "disconnected",
    "token_ready": false,
    "webhook_url": "https://hooks.example.com/social",
    "disconnected_reason": "<THE_NETWORK'S_MESSAGE>",
    "last_checked_at": "2026-10-31T10:15:02.000Z",
    "created_at": "2026-10-28T16:40:09.000Z"
  }
}

Что означают причины отключения?

reason в connection.disconnected это код, который Meta поместила в disconnection_info своего вебхука account_update. Meta включает его для номеров как в приложении WhatsApp Business, так и в Cloud API. Значение null, если Meta не дала причины. Коды из справочника Meta:

  • PRIMARY_INACTIVITY: телефон с приложением WhatsApp Business был неактивен около 14 дней, по правилу 14 дней. Новая сессия подключения переподключает номер.
  • ACCOUNT_DISCONNECTED: аккаунт отключён через меры Meta или самим клиентом, который мог отозвать доступ или удалить аккаунт.
  • COMPANION_INACTIVITY: сопутствующее устройство было неактивно около 30 дней.
  • BUSINESS_DOWNGRADE: номер был зарегистрирован в потребительском приложении WhatsApp.
  • CHANGE_NUMBER и USER_RE_REGISTERED: клиент сменил номер или зарегистрировал его заново на новом устройстве.

Какие заголовки приходят с событием статуса?

Пять, при каждой попытке: Content-Type application/json, User-Agent easyCoexistence-webhooks/1, X-EC-Event с именем события, X-EC-Delivery с тем же id, что в теле, и X-EC-Signature. Подпись имеет вид t=<unix>,v1=<hex>, где v1 это HMAC-SHA256 от t, точки и сырого тела, с ключом из секрета подписи вашего аккаунта, который начинается с whsec_. Каждая попытка подписывается заново, поэтому повтор несёт новый t над тем же телом.

Python: verify, then handle each id once
import hashlib, hmac, json, os, time

SECRET = os.environ["EC_EVENTS_SECRET"].encode()  # whsec_..., shown once in Profile > Developers

def verify(raw: bytes, header: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300:
        return False  # missing, or more than 5 minutes off
    mac = hmac.new(SECRET, t.encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, v1)

def handle(raw: bytes, headers) -> int:
    if not verify(raw, headers.get("X-EC-Signature", "")):
        return 401
    event = json.loads(raw)
    if already_processed(event["id"]):  # the X-EC-Delivery id, the same on every retry
        return 200
    enqueue(event)  # act on event["event"]; the latest occurred_at wins
    return 200

Как повторяются неудачные доставки?

Первая попытка уходит в момент события. Ответ вне 2xx, отсутствие ответа за 10 секунд, сетевая ошибка или перенаправление считаются сбоем, и событие пробуется снова с нарастающими паузами от 1 минуты до 24 часов. Всего семь попыток около 33 часов, после чего событие отбрасывается. Доставка идёт только на HTTPS-адрес, который разрешается в публичный IP. Событие, возникшее, пока эндпоинт не задан, в очередь не ставится, а удаление эндпоинта останавливает всё ожидающее.

Зачем обрабатывать каждый id один раз и проверять occurred_at?

Потому что повтор повторяет доставку точно, с тем же id в теле и в X-EC-Delivery, а повторное событие может прийти после более нового. Сохраняйте id уже обработанных событий и пропускайте повторы. Затем сравните occurred_at с последним состоянием, которое вы записали для этого подключения, или прочитайте GET /connections/{id} либо GET /channels/{id} перед действием по событию, которое может быть устаревшим.

Что должна делать платформа, когда номер отключается?

Действовать по причине. После PRIMARY_INACTIVITY попросите клиента открыть приложение WhatsApp Business и отправьте ему новую сессию подключения для того же номера. Переподключение в том же аккаунте WhatsApp Business сохраняет его ID подключения, возвращает адрес доставки вебхуков и отправляет connection.connected, после чего вы заново читаете его учётные данные. connection.token_missing означает, что Meta не выдала токен в этом запуске. Meta отправляет account_update, стоящий за отключением, только на callback приложения, никогда на ваш URL, поэтому именно это событие сообщает вашей платформе о нём.

Что должна делать платформа, когда аккаунт в соцсети отключается?

По channel.disconnected новая сессия подключения с тем же каналом заново входит в аккаунт под тем же ID канала. channel.removed означает, что доступ потерян: токен забывается, адрес вебхука очищается, поэтому при повторном подключении клиента адрес нужно задать заново. Приостановленный номер или канал возвращается после повторного подключения, когда ваша подписка снова активна.

Распространённые ошибки

  • Принимать повтор за новое событие. Он несёт тот же id в теле и в X-EC-Delivery, поэтому записывайте обработанные id, иначе одно отключение может дважды оповестить клиента.
  • Применять события в порядке поступления. Повторное событие может прийти после более нового, поэтому сравнивайте occurred_at или читайте подключение перед действием.
  • Сохранять URL событий заново, чтобы исправить опечатку, без обновления бэкенда. Сохранение выпускает новый секрет подписи, и каждая доставка не проходит проверку, пока ваш эндпоинт его не использует.
  • Выполнять работу до ответа. Обработчик, который работает дольше 10 секунд, считается сбоем, и событие приходит снова, поэтому сначала отвечайте 2xx, а обрабатывайте потом.
Настройка с EasyCoexistence

easyCoexistence круглосуточно следит за номером WhatsApp и аккаунтами в соцсетях каждого клиента и отправляет вашей платформе подписанное событие, когда что-то подключается, отключается, удаляется или приостанавливается, с причиной от Meta для отключившегося номера. От US$ 9 до US$ 0,75 за подключение в месяц, цена снижается по мере добавления подключений, первые 3 дня бесплатно.

Часто задаваемые вопросы

Что означает PRIMARY_INACTIVITY?

Это причина от Meta для отключения номера Coexistence, приложение WhatsApp Business на основном устройстве которого не использовалось около 14 дней. Новая сессия подключения для этого клиента переподключает номер.

Включают ли события статуса сообщения?

Нет. Они касаются статуса подключения. Сообщения номера идут от Meta на его собственный адрес вебхуков, а комментарии и личные сообщения из соцсетей на адрес каждого канала.

Где задать URL событий?

В панели управления в разделе «Profile», затем «Developers», или через инструмент MCP set_partner_events_url. Секрет подписи показывается один раз, а повторное сохранение URL выпускает новый.

Можно ли игнорировать события каналов, если я обрабатываю только номера?

Да. События channel.* имеют собственные имена и содержат объект channel вместо connection, поэтому получатель может пропускать любое событие, имя которого не начинается с connection.

Читайте дальше

Как получать сообщения клиентов WhatsApp и комментарии соцсетей по вебхукуВебхук на каждое подключение: сообщения WhatsApp напрямую от Meta, защита секретом в URL, а комментарии и DM соцсетей подписаны X-EC-Signature.Как получить API-токены клиентов для WhatsApp, Instagram и TikTokПоля учётных данных для номера WhatsApp и аккаунтов в соцсетях, а также как работают обновление токенов и token_ready.Как импортировать историю чатов и контакты приложения WhatsApp Business через APIИмпорт контактов и чатов за 180 дней из приложения WhatsApp Business через Coexistence: вебхуки history, chunk_order, прогресс и код 2593109.Как построить продукт с ИИ-агентом в WhatsApp, Instagram и TikTok ваших клиентовСоздайте продукт с ИИ-агентом в WhatsApp, Instagram, Facebook и TikTok клиентов: Partner API, своя модель и правила каждой сети.Вебхук account_update и все причины отключенияaccount_update сообщает об изменениях состояния подключения. Полный список причин отключения от Meta, их значение и возможность восстановления.Номер перестал работать: как выяснить причинуЧек-лист в порядке частоты сбоев: токен, переопределение вебхука, отключение за бездействие, качество и ограничение аккаунта.

Подключите первый канал за две минуты.

Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.

  • 3 дня бесплатно
  • Отмена в любой момент
  • Только официальные API
  • Мониторинг 24/7

Проверено по состоянию на