API リファレンス

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 の *、空配列、省略に通話イベントも含まれ、個別リストは指定したイベントのみを対象とします。非ベータでもワイルドカードを利用できますが通話イベントは届かず、通話イベントの個別登録は 403 beta_feature_not_enabled になります。配信、再試行、デッドレター再実行のたびに資格を確認し、照会失敗時は許可しません。通常の 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.