Receiving Events

Standard event types & payload

The unified envelope every delivery carries and the full catalogue of public standard event types. Subscribe per endpoint with subscribed_events using the exact names below, or use ["*"] for all public standard events. Internal raw events are not delivered. The envelope is always id / type / provider / account_id / occurred_at / data; the shape of data depends on type. Доступ к событиям звонков определяется is_beta рабочего пространства. При доступе к тестированию *, пустой или отсутствующий subscribed_events включают события звонков; конкретный список включает только перечисленные события. Без доступа можно использовать wildcard, но события звонков не доставляются; их явная подписка возвращает 403 beta_feature_not_enabled. Право проверяется при каждой доставке, повторе и повторной обработке dead letter; ошибка проверки не даёт доступ. Обычные записи звонков message.* независимы.

Event payload

{
  "id": "evt_2f9c1a4b7e",
  "type": "message.received",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:34:56Z",
  "data": {
    "account": { "provider_account_ref": "8600000000000" },
    "conversation": { "id": "8613912345678", "type": "user", "title": "Jordan Lee" },
    "sender": { "id": "8613912345678", "name": "Jordan Lee", "type": "user" },
    "message": {
      "id": "wamid.HBgM",
      "text": "Hi - is my order shipped yet?",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:34:55Z"
    }
  }
}

Standard event types

call.incoming
call.incoming — зарезервированный контракт: входящие звонки пока недоступны. После запуска рабочие пространства с доступом к тестированию смогут получать его через subscribed_events с точным именем, *, пустым или отсутствующим списком.
call.answered
call.answered сообщает об установлении соединения. При доступе к тестированию используйте subscribed_events с call.answered или *, либо пустой или отсутствующий список.
call.ended
call.ended сообщает об окончании звонка: data.call.id, reason, duration_seconds. При доступе к тестированию используйте subscribed_events с call.ended или *, либо пустой или отсутствующий список.
post.comment.created
Уведомление о комментарии TikTok после распознавания и проверки принадлежности публикации текущему аккаунту. Перед включением проверьте доступность уведомлений в среде и готовность получателя. Опрос по умолчанию выключен; после provider_data.enable_comment=true нужен запуск или переподключение, а изменения онлайн требуют переподключения. Успешный start не подтверждает применение настройки; отключение не отзывает события из очереди. Подпишитесь на post.comment.created либо используйте пустой список подписок или *; сама подписка не включает опрос. Доставка выполняется по возможности: допустимы задержки, дубликаты, нарушение порядка и пропуски, полнота истории не гарантируется. Удаляйте дубликаты по id события. Отсутствие parent_comment_id не доказывает, что это комментарий верхнего уровня, на который можно ответить; перед ответом проверьте цель.
contact.updated
Изменены имена в адресной книге WhatsApp (не whatsapp-protocol). Обновляйте только переданные поля data.contact.address_book: пустая строка очищает значение, отсутствие поля сохраняет его, null недопустим. Псевдоним собеседника и профиль самого аккаунта не перезаписываются. contact.id идентифицирует ресурс контакта, но не обязательно диалог.
message.received
A message was observed on the account; data.message.direction identifies inbound or outbound.
message.updated
A previously delivered message was edited.
message.deleted
A message was deleted or recalled.
message.read
A read receipt — the recipient read a message.
message.reaction
A reaction was added to or removed from a message.
message.delivered
A message was delivered to the recipient's device.
conversation.updated
A conversation-level setting changed — muted/unmuted, archived, pinned, or marked read.
conversation.deleted
A conversation was deleted.
conversation.cleared
A conversation's history was cleared.
conversation.history
Recent WhatsApp history for one conversation was synced after bootstrap or reconnect.
group.updated
Group metadata changed — name, members, or settings.
group.join_request
Someone asked to join a group with join approval enabled. Push is best-effort — poll List group join requests as the reliable source.
account.status.updated
The account runtime / connection status changed.
account.profile.updated
Профиль публичного имени аккаунта синхронизирован; сейчас событие вызывается событиями имени WhatsApp.
account.started
The account runtime connected and is ready to send and receive.
account.history.synced
A WhatsApp history-sync batch finished; data.summary gives the delivered conversation and message counts.
account.auth.required
The account needs (re)authentication — a code, QR scan, or 2FA.
account.auth.succeeded
Авторизация аккаунта завершена. Перед отправкой запросите аккаунт и убедитесь, что runtime_status=running.
account.auth.failed
An authentication attempt failed.

Примечания

For media messages, data.message.attachments[] carries a temporary signed OSS url plus type, mimetype, and size.
subscribed_events must contain exact public standard event names from above or ["*"]. Unknown names are rejected when you create or update the endpoint, and the wildcard does not expose internal raw events.
Not every provider emits every event, and some payload fields differ — see "Webhook standard event differences" for the per-provider matrix.
message.read and message.delivered carry the exact receipt scope: data.message.ids lists every message covered by the receipt, and read_at / delivered_at give the provider-reported time.
WhatsApp inbound messages can include data.message.reply_token — an opaque handle you pass back in reply_to.reply_token of POST /v1/messages to quote the current message. It appears only for real-time message.received when reply-token signing is configured. It is not reply_to_message_id, which identifies the parent of a received quoted reply.