WhatsAppのステータスに関するコールバック

Vonage Messages API を使用して WhatsApp メッセージを送信すると、Vonage が配信を行います ステータス・コールバック メッセージの状態が変更されるたびに（たとえば、送信、配信、または既読になったときなど）、設定されたWebhook URLに通知が送信されます。

Vonage は、Meta（WhatsApp の基盤プロバイダー）からステータス更新情報を受け取り、それらを一貫性のあるコールバック形式に変換してから、お客様のアプリケーションに転送します。つまり、Webhook が受信するペイロードは、Meta の Webhook の生のペイロードとは異なる場合があります。

すべてのチャネルにわたるステータスコールバックの概要については、以下を参照してください。 Messages API ステータス・コールバック.

メッセージステータスのコールバック

WhatsAppのメッセージが新しい状態に移行するたびに、Vonageはステータス・コールバックをウェブフックのURLに送信します。以下のステータスがサポートされています：

ステータス	説明
`submitted`	Vonage はそのメッセージを受信し、WhatsApp に転送しました。
`delivered`	メッセージは受信者の端末に配信されました。
`read`	受信者がメッセージを開封しました（開封確認が有効になっている必要があります）。
`rejected`	このメッセージは、Vonage または WhatsApp によって拒否されました。A `error` オブジェクトがペイロードに含まれています。
`undeliverable`	VonageはWhatsAppに接続できず、メッセージを配信できませんでした。

ステータスコールバックのペイロード

次の例は、WhatsAppのステータスコールバックに含まれる可能性のあるフィールドの全一覧を示しています。すべてのコールバックにすべてのフィールドが含まれるわけではありません。たとえば、 error は、以下の目的でのみ含まれています。 rejected または undeliverable ステータス、 workflow これは、メッセージがワークフローの一部として送信された場合にのみ含まれ、 profile / whatsapp.recipient WhatsAppから入手可能な場合にのみ含まれます：

{
  "to": "447700900001",
  "from": "447700900001",
  "channel": "whatsapp",
  "status": "submitted",
  "usage": {
    "currency": "EUR",
    "price": "0"
  },
  "profile": {
    "name": "Jane Smith",
    "username": "janesmith123"
  },
  "whatsapp": {
    "recipient": {
      "user_id": "US.13491208655302741918",
      "parent_user_id": "US.ENT.11815799212886844830",
      "wa_id": "447700900000"
    },
    "waba_id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
    "pricing": {
      "type": "regular",
      "pricing_model": "CBP",
      "category": "service"
    },
    "conversation": {
      "id": "1234567890",
      "origin": {
        "type": "marketing"
      }
    }
  },
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
  "timestamp": "2025-02-03T12:14:25Z",
  "error": {
    "type": "https://developer.vonage.com/api-errors/messages#1000",
    "title": "1000",
    "detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
    "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
  },
  "client_ref": "abc123",
  "workflow": {
    "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
    "items_number": "1",
    "items_total": "2"
  }
}

ステータスフィールドの完全な一覧については、ステータス・コールバック・フィールド Messages API リファレンスの該当セクション。

エラーのコールバック

メッセージが拒否されたり、配信不能になった場合、コールバックには error オブジェクトがある：

{
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2025-02-03T12:14:25Z",
  "status": "rejected",
  "channel": "whatsapp",
  "error": {
    "type": "https://developer.vonage.com/api-errors/messages#1000",
    "title": 1000,
    "detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
    "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
  }
}

受信メッセージのコールバック

WhatsAppユーザーがあなたのWhatsApp Business番号にメッセージを送信すると、Vonageはそのメッセージをあなたの着信Webhook URLに転送します。

[ ] 内で、インバウンド Webhook の URL を設定する必要があります。 Vonage APIダッシュボードまたは、アプリケーションAPIを介して受信メッセージを受け取ります。

受信メッセージのペイロード

以下は、着信テキストメッセージのコールバックの例です：

{
  "channel": "whatsapp",
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2025-02-03T12:14:25Z",
  "profile": {
    "name": "Jane Smith",
    "username": "janesmith123"
  },
  "context_status": "available",
  "context": {
    "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
    "message_from": "447700900000"
  },
  "provider_message": "Message delivered",
  "message_type": "text",
  "text": "Hello from Vonage!",
  "whatsapp": {
    "sender": {
      "user_id": "US.13491208655302741918",
      "parent_user_id": "US.ENT.11815799212886844830",
      "wa_id": "447700900000"
    },
    "referral": {
      "body": "Check out our new product offering",
      "headline": "New Products!",
      "source_id": "212731241638144",
      "source_type": "post",
      "source_url": "https://fb.me/2ZulEu42P",
      "media_type": "image",
      "image_url": "https://example.com/image.jpg",
      "video_url": "https://example.com/video.mp4",
      "thumbnail_url": "https://example.com/thumbnail.jpg",
      "ctwa_clid": "1234567890"
    }
  },
  "_self": {
    "href": "https://api-eu.vonage.com/v1/messages/aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab"
  }
}

受信メッセージのフィールドの一覧については、受信メッセージのフィールド Messages API リファレンスの該当セクション。

非推奨のフィールド

以下のフィールドは非推奨となる予定です：

フィールド	備考
`whatsapp.conversation`	Webhooks API バージョン 23.0 以降では、無料のエントリーポイント会話を除き、非推奨となります。
`pricing.billable`	今後のリリースで非推奨となります。代わりに `whatsapp.pricing` その代わりだ。
`usage.price`	次のように設定されます `"0"` 2025年7月1日より、「メッセージ単位課金（PMP）」モデルに基づき。

詳細情報

Messages API ステータス・コールバック