変換イベント追跡の仕組み前提条件ステップ 1: 変換データセットを作成するステップ 2: 変換イベントを送信する変換イベントリファレンスエラー処理

AWS End User Messaging Social での WhatsApp 変換イベントの送信

で「Ads that Click to WhatsApp」キャンペーンを実行するとMeta、変換イベント (購入、リード、コンテンツビューなど) を Meta に送信して、広告属性と最適化を行うことができます。Graph API Meta を呼び出すことなく、 AWS エンドユーザーメッセージングソーシャルを介してこれらのイベントを直接送信します。

AWS End User Messaging Social には、このワークフロー用に 2 つの APIs。

CreateWhatsAppDataset — WhatsApp Business Account (WABA) の変換データセットを作成 (または取得) します。データセットは、コンテナが変換イベントを受信して属性Meta付けするために使用するものです。
SendWhatsAppConversionEvent — 1 つ以上の変換イベントを Meta Conversions API に送信します。変換イベントは、WhatsApp 会話を開始した広告クリックに起因します。

変換イベント追跡の仕組み

end-to-endのワークフローは次のとおりです。

顧客が「Click to WhatsApp」広告をクリックしMeta、ビジネスとの会話を開始します。
インバウンドメッセージは、設定されたイベント送信先 (Amazon SNS トピック、Amazon EventBridge、または Amazon Connect) に到着します。これには、広告クリックを識別する ctwa_clid (click-to-WhatsApp クリック ID) が含まれます。アプリケーションはこの値をキャプチャして保存する必要があります。
変換が発生すると (顧客が購入するなど）、アプリケーションは ctwa_clidおよびイベントの詳細SendWhatsAppConversionEventを使用してを呼び出します。
AWS End User Messaging Social は、関連付けのためにイベントを Meta Conversions API に転送します。

ctwa_clid は、顧客が広告から会話を開始すると、インバウンドメッセージウェブフックペイロードの referral オブジェクトに含まれます。次の例は、ウェブフックメッセージの関連部分を示しています。


{
  "messages": [
    {
      "from": "12345678",
      "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "referral": {
        "body": "This is a great product",
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a",
        "headline": "Our new product",
        "source_id": "1234567890",
        "source_type": "ad",
        "source_url": "https://fb.me/AAAAA"
      },
      "text": {
        "body": "Can I learn more about your business?"
      },
      "timestamp": "1678189586",
      "type": "text"
    }
  ]
}

referral オブジェクトからctwa_clid値を保存します。この会話に送信するすべての変換イベントの user_data に渡します。紹介ウェブフックの詳細については、デMetaベロッパードキュメントの「Webhooks コンポーネント」を参照してください。

前提条件

変換イベントを送信する前に、以下が必要です。

AWS アカウントにリンクされている WhatsApp Business Account (WABA)。
でのアクティブな「Ads That Click to WhatsApp」キャンペーンMeta。
アプリケーションは、顧客が広告クリックctwa_clidから会話を開始するときに、インバウンドメッセージウェブフックからをキャプチャする必要があります。この値はによって生成Metaされ、作成できません。

重要

2026 年 8 月 6 日より前に WhatsApp Business Account (WABA) をリンクした場合は、サインアップフローをやり直して、変換イベントを送信するためのアクセス許可を AWS End User Messaging Social に付与する必要があります。「WhatsApp にサインアップする」の「コンソールからサインアップする」のステップ 1～14 に従い、 AWS アカウントに関連付けられている既存の WABA と電話番号を選択します。その後、残りのステップをスキップできます。

ステップ 1: 変換データセットを作成する

変換イベントを送信する前に、WABA の変換データセットを作成する必要があります。各 WABA には厳密に 1 つのデータセットがあります (これはによって適用されますMeta)。オペレーションはべき等です。データセットが既に存在する場合、既存のデータセット ID が返されます。

次のの例では、WABA のデータセットを作成または取得します。waba-id を、リンクされた WhatsApp Business Account (WABA) の ARN に置き換えます (例: )arn:aws:social-messaging:us-east-1:123456789012:waba/a1b2c3d4e5example。


aws socialmessaging create-whatsapp-dataset \
    --region us-east-1 \
    --id waba-id

レスポンスにはデータセット ID が含まれます。この値を保存します。変換イベントを送信するたびに datasetIdパラメータとして渡します。


{
    "datasetId": "123456789012345"
}

ステップ 2: 変換イベントを送信する

データセットを作成したら、 SendWhatsAppConversionEvent API Metaを使用して変換イベントをに送信できます。各呼び出しは、属性の Meta Conversions API に 1 つ以上のイベントを配信します。

event-data パラメータで送信するイベントコンテンツは、MetaConversions API サーバーイベント形式に従います。 AWS End User Messaging Social はこのコンテンツをに転送しますMeta。イベントフィールドの完全なリストについては、デMetaベロッパードキュメントのMeta「サーバーイベントパラメータリファレンス」を参照してください。

購入変換イベントを送信する

次のの例では、Purchase変換を報告します。プレースホルダーの値を、独自の値に置き換えます。


aws socialmessaging send-whatsapp-conversion-event \
    --region us-east-1 \
    --id waba-id \
    --dataset-id dataset-id \
    --event-data '{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": 1720000000,
            "action_source": "business_messaging",
            "messaging_channel": "whatsapp",
            "user_data": {
                "whatsapp_business_account_id": "meta-waba-id",
                "ctwa_clid": "click-id"
            },
            "custom_data": {
                "currency": "USD",
                "value": 99.99
            }
        }
    ]
}'

レスポンスには、送信を識別するリクエスト ID が含まれています。


{
    "requestId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}

リード変換イベントを送信する

などの非購入イベントタイプLeadSubmittedには、は必要ありませんcustom_data。


aws socialmessaging send-whatsapp-conversion-event \
    --region us-east-1 \
    --id waba-id \
    --dataset-id dataset-id \
    --event-data '{
    "data": [
        {
            "event_name": "LeadSubmitted",
            "event_time": 1720000000,
            "action_source": "business_messaging",
            "messaging_channel": "whatsapp",
            "user_data": {
                "whatsapp_business_account_id": "meta-waba-id",
                "ctwa_clid": "click-id"
            }
        }
    ]
}'

1 つのリクエストで複数のイベントを送信する

data 配列は、1 回の呼び出しで複数のイベントを受け入れます。 Metaは、リクエストごとに最大 1,000 個のイベントを許可します。


aws socialmessaging send-whatsapp-conversion-event \
    --region us-east-1 \
    --id waba-id \
    --dataset-id dataset-id \
    --event-data '{
    "data": [
        {
            "event_name": "ViewContent",
            "event_time": 1720000000,
            "action_source": "business_messaging",
            "messaging_channel": "whatsapp",
            "user_data": {
                "whatsapp_business_account_id": "meta-waba-id",
                "ctwa_clid": "click-id"
            }
        },
        {
            "event_name": "Purchase",
            "event_time": 1720000500,
            "action_source": "business_messaging",
            "messaging_channel": "whatsapp",
            "user_data": {
                "whatsapp_business_account_id": "meta-waba-id",
                "ctwa_clid": "click-id"
            },
            "custom_data": {
                "currency": "USD",
                "value": 149.00
            }
        }
    ]
}'

変換イベントリファレンス

event-data パラメータは、1 つ以上のイベントオブジェクトを含むdata配列を持つ JSON オブジェクトです。次の表は、「Ads that Click to WhatsApp」変換で最もよく使用されるフィールドを示しています。 Metaはイベントコンテンツの信頼できるソースです。詳細な仕様については、デMetaベロッパードキュメントのMeta「サーバーイベントパラメータリファレンス」を参照してください。

必須イベントフィールド

フィールド	タイプ	説明
`event_name`	文字列	変換のタイプ。大文字と小文字を区別する。一般的な値には`Purchase`、、`LeadSubmitted`、およびが含まれます`ViewContent`。
`event_time`	Number	変換が発生した時刻。Unix タイムスタンプを秒単位で表します。過去 7 日以内でなければならず、今後は使用できません。
`action_source`	String	`business_messaging` を指定してください。
`messaging_channel`	String	メッセージングチャネル。`whatsapp` を使用します。
`user_data`	オブジェクト	イベントを広告クリックに一致させるために使用される情報。「必須の user_data フィールド」を参照してください。

必須の user_data フィールド

次の表に、 user_data オブジェクトの必須フィールドを示します。

フィールド	タイプ	説明
`whatsapp_business_account_id`	文字列	数値の Meta WhatsApp ビジネスアカウント ID (Metaビジネス設定から）。
`ctwa_clid`	String	広告が開始した会話のインバウンドメッセージウェブフックからの click-to-WhatsApp クリック ID。はこの値Metaを検証します。これは作成できません。

重要

E メールアドレスや電話番号などuser_data、個人を特定できる情報 (PII) をに含める場合は、値を SHA-256 ハッシュとして指定する必要があります。はハッシュされていない PII Metaを拒否します。ctwa_clid 値はハッシュされません。

custom_data オブジェクト

Purchase イベントの場合、次のフィールドを持つ custom_data オブジェクトを含める必要があります。

フィールド	タイプ	説明
`currency`	文字列	ISO 4217 通貨コード (例: `USD`)。
`value`	Number	変換の金額。

エラー処理

AWS End User Messaging Social はイベントコンテンツをに転送するためMeta、ほとんどのイベントコンテンツの問題はとして表示されますInvalidParametersException。エラーメッセージには、認識されないイベント名Meta、許可されたウィンドウ外のイベント時間、購入通貨の欠落、ハッシュされていない PII、無効ななど、によって報告された理由が含まれますctwa_clid。

エラー	HTTP ステータス	意味
`InvalidParametersException`	400	リクエストまたはイベントの内容が無効です。エラーメッセージは、特定の問題を記述します。
`ResourceNotFoundException`	404	指定された WABA またはデータセットが見つかりませんでした。
`AccessDeniedByMetaException`	403	Meta アクセス許可が原因でリクエストが拒否されました (基盤となるMetaアクセストークンに必要なアクセス許可がないか、無効など）。
`ThrottledRequestException`	429	リクエストレートが許可された制限を超えました。エクスポネンシャルバックオフを使用して再試行してください。
`DependencyException`	502	ダウンストリーム依存関係 (Meta) がエラーを返しました。再試行可能。
`InternalServiceException`	500	内部エラーが発生しました。再試行可能。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

一時的な適格性エラー

Responding to a received message