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

Messages API は、次のように送信します。 ステータス・コールバック を Webhook URL に追加すると、イベントがメッセージの状態を変更するたびに通知されます（たとえば、送信、配信、拒否など）。

これらのコールバックは、以下のようなすべてのサポートされたチャネルにわたって、メッセージのライフサイクルに一貫した可視性を提供します。 ショートメール, MMS, RCSそしてアプリ： WhatsApp, バイバーそして フェイスブックメッセンジャー.

メッセージのステータスが変更されるたびに、Messages API は設定した Webhook にステータスのコールバックを送信します。
このコールバックには、メッセージのUUID、チャネル、タイムスタンプ、配送状況、そして該当する場合は価格やネットワークのメタデータなどの重要な情報が含まれます。

異なるチャンネルは、異なるイベントや洞察のレベルをサポートしています。例えば

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

ステータスの読み取りコールバック

WhatsAppやViberのようなOTTチャンネルでは、Messages APIは、次のようなメッセージを送信することができます。 read プロバイダがエンドユーザのデバイスでメッセージを読んだことを示すときにコールバックされます。

提出されたステータスのコールバック

このステータスは、Messages APIがメッセージをメッセージング・プロバイダに渡したことを意味する。

配信不能ステータスのコールバック

このステータスは、Messages APIがメッセージング・プロバイダに接続できなかったことを意味します。これは、メッセージングプロバイダの停止やその他のインシデントが原因である可能性があります。

拒否されたステータスのコールバック

メッセージが拒否される理由はいくつかある：

• Messages API はメッセージを処理できない（例えば、無効なパラメータやサポートされていないメディア）。
• プロバイダーはメッセージを拒否する。例えば、サポートされていない国へのMMS送信など。
• メッセージのTTL(time-to-live)は、配信される前に切れてしまう。

このような場合 rejected コールバックは、失敗を記述したエラーオブジェクトとともに送られる。

コールバックの例

SMS（マルチパートメッセージ）

{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2023-05-01T14:00:00.000Z",
  "status": "submitted",
  "usage": {
    "currency": "EUR",
    "price": "0.0333"
  },
  "client_ref": "string",
  "channel": "sms",
  "destination": {
    "network_code": "12345"
  },
  "sms": {
    "total_count": "2"
  }
}

RCS（SMSフェイルオーバーによるリクエスト拒否）

{
  "message_uuid": "001",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2024-01-01T14:00:00.000Z",
  "status": "rejected",
  "channel": "rcs",
  "destination": {
    "network_code": "12345"
  },
  "error": {
    "type": "https://developer.vonage.com/api-errors/messages#1260",
    "title": 1260,
    "detail": "Destination unreachable - The message could not be delivered to the phone number.",
    "instance": "abc102"
  },
  "workflow": {
    "id": "1001",
    "item_number": "1",
    "items_total": "2"
  }
}

ネットワーク・コード

Messages APIには network_code は、メッセージを処理するオペレータを識別するためのコールバックで使用される。ネットワークコードは、Mobile Country Codes (MCC)とMobile Network Codes (MNC)の組み合わせであり、SMS、RCS、およびMMSに適用される。