イベント形式の管理

形式の選択は、Webhook に配信されるイベントの JSON ペイロード構造を定義します。各サブスクリプションは、チャネルのデフォルト形式を自動的に使用しますが、Webhook レシーバーに特定の API バージョンまたは構造が必要な場合は、別の形式を選択できます。

前提条件 [#prerequisites]

イベント形式を管理するには、次のものが必要です。

• NTT CPaaS アカウント: アクティブなアカウント。
• Webhook サブスクリプション: 少なくとも 1 つのサブスクリプションが構成されています。Webhookサブスクリプションの管理を参照してください。
• チャネル認識: サブスクリプションが監視するチャネルに関する知識 (デフォルトの形式はチャネルによって異なります)。

フォーマット選択の概要 [#format-selection-overview]

各サブスクリプションは、イベントの一貫した処理を保証するためにチャネル固有の既定の形式 (イベント スキーマ) を自動的に受け取ります。既定の形式が要件を満たさない場合は、使用可能なチャネルに対してサポートされている別の形式を選択できます。

これにより、次のことが可能になります。

• Webhook に配信される JSON ペイロード構造を制御する
• Webhook が想定する特定の API バージョンに一致する形式を使用する
• 元のメッセージの送信に使用した API バージョンに自動的に適応するペイロードを受信する
• Webhook レシーバー ロジックとの互換性を確保する

チャネルごとの既定の形式 [#default-formats]

各チャネルは、事前定義された JSON 形式を使用してインバウンド メッセージを構造化します。

選択可能な形式 [#selectable-formats]

フォーマットには、次の 2 つのタイプがあります。

• 静的フォーマットは、特定のAPIバージョン(delivery.sms.v3.jsonなど)に関連付けられた固定ペイロード構造を提供します。元のメッセージの送信方法に関係なく、すべてのイベントで同じスキーマが使用されます。
• アダプティブ形式(adaptive.subscription.format)は、ペイロードを、送信者が元のメッセージの送信に使用した API バージョンに動的に一致させます。

選択可能な形式は、次のチャネルとサービスで使用できます。

メッセージング チャネル

Apple Messages for Business、Facebook Messenger、MMS、SMS、オープンチャネル

プラットフォームサービス

モバイルID、ブロックリスト

その他のチャンネルでは、既定の形式が自動的に適用されます。他のチャンネルのフォーマットを変更する場合は、 NTT CPaaSサポートにお問い合わせください。

ソース別に使用可能な形式 [#formats-by-source]

チャネルまたはサービスを展開して、選択可能な形式と、それぞれが生成するペイロードを表示します。タブを使用して、カテゴリを切り替えます。

ChannelsNumbers and sendersTools

Apple Messages for Business

イベント	フォーマット名	ペイロードの例
配達	adaptive.subscription.format	申請で使用された API バージョンに基づいて調整されます
配達	delivery.apple-messages-for-business.v3.json	AMB API: AMB 配信レポートの受信
配達	delivery.apple-messages-for-business.v4.json	メッセージ API: 配信レポートの受信
受信メッセージ	inbound-message.apple-messages-for-business.v1.json	AMB API: 受信 AMB メッセージを受信する
受信メッセージ	inbound-message.apple-messages-for-business.v2.json	メッセージ API: 受信メッセージを受信する

Facebook Messenger

イベント	フォーマット名	ペイロードの例
配達	adaptive.subscription.format	申請で使用された API バージョンに基づいて調整されます
配達	delivery.facebook.v5.json	メッセージ API: 配信レポートの受信
配達	delivery.facebook.v4.json	Messenger API: Messenger配信レポートの受信
受信メッセージ	inbound-message.facebook.v1.json	Messenger API:受信した Messengerメッセージを受信する
受信メッセージ	inbound-message.facebook.v2.json	メッセージ API: 受信メッセージを受信する
見た	seen.facebook.v1.json	Messenger API: 表示されたレポートを受信する
同意の更新	consent-update.facebook.v1.json	Messenger API: Messengerの 同意更新イベントを受け取る
をクリックします。	click.facebook.v1.json	Messenger API: Messenger Marketingクリックイベントの受信

SMS

イベント	フォーマット名	ペイロードの例
をクリックします。	tracking.sms.v1.json	SMS API: SMS トラッキング通知の受信
配達	adaptive.subscription.format	申請で使用された API バージョンに基づいて調整されます
配達	delivery.sms.v2.json	オムニフェイルオーバー API: 配信ステータスレポートの受信
配達	delivery.sms.v3.json	SMS API v2: 送信 SMS メッセージ レポートの受信
配達	delivery.sms.v4.json	SMS API v3: 送信 SMS メッセージ レポートの受信
配達	delivery.sms.v5.json	メッセージ API: 配信レポートの受信
受信メッセージ	inbound-message.sms.v1.json	SMS API: 受信SMS（Short Message Serviceメッセージの受信
受信メッセージ	inbound-message.sms.v2.json	メッセージ API: 受信メッセージを受信する

MMS

イベント	フォーマット名	ペイロードの例
をクリックします。	tracking.mms.v1.json	MMS API: MMS 追跡通知を受信する
配達	adaptive.subscription.format	申請で使用された API バージョンに基づいて調整されます
配達	delivery.mms.v1.json	MMS API v1: 送信 MMS メッセージ レポートの受信
配達	delivery.mms.v3.json	メッセージ API: 配信レポートの受信
配達	delivery.mms.v4.json	MMS API v2: MMS 配信レポートの受信
受信メッセージ	inbound-message.mms.v1.json	MMS API: 受信 MMS メッセージを受信する
受信メッセージ	inbound-message.mms.v2.json	メッセージ API: 受信メッセージを受信する

Open Channel

イベント	フォーマット名	ペイロードの例
配達	event.open-channel.v1.json	オープン チャネル API: オープン チャネル送信メッセージの受信

その他のチャネルとプラットフォームサービスについては、イベントの完全なリストについては、利用可能なWebhookイベントを参照してください。

フォーマットを選択する [#select-format]

サブスクリプションを作成または編集するときに、別の形式を選択できます。

各書式タイプを使用する場合 [#when-to-use]

次の場合に静的形式を使用する

Webhook レシーバーは、特定の API バージョン構造を想定しています。予測可能で不変の JSON ペイロードが必要です。特定の API バージョンから移行しており、下位互換性が必要です。そのタイプのすべてのイベントで一貫性が必要です。

アダプティブフォーマットは、次の場合に使用します。

Webhook レシーバーで複数の API バージョンをサポートします。ペイロードは、各送信者が使用した API バージョンと一致する必要があります。送信者が API バージョンを更新する際の柔軟性が必要です。Webhook は可変 JSON 構造を処理できます。