Sending WhatsApp conversion events in AWS End User Messaging Social

If you run "Ads that Click to WhatsApp" campaigns on Meta, you can send conversion events (such as purchases, leads, or content views) back to Meta for ad attribution and optimization. Send these events directly through AWS End User Messaging Social, without calling the Meta Graph API.

AWS End User Messaging Social provides two APIs for this workflow:

• CreateWhatsAppDataset — Creates (or retrieves) the conversions dataset for your WhatsApp Business Account (WABA). A dataset is the container Meta uses to receive and attribute your conversion events.

• SendWhatsAppConversionEvent — Sends one or more conversion events to the Meta Conversions API, where they are attributed to the ad click that started the WhatsApp conversation.

How conversion event tracking works

The end-to-end workflow is:

1. A customer clicks your "Click to WhatsApp" ad on Meta and starts a conversation with your business.

2. The inbound message arrives in your configured event destination (Amazon SNS topic, Amazon EventBridge, or Amazon Connect). It includes a ctwa_clid (click-to-WhatsApp click ID) that identifies the ad click. Your application must capture and store this value.

3. When a conversion happens (for example, the customer makes a purchase), your application calls SendWhatsAppConversionEvent with the ctwa_clid and event details.

4. AWS End User Messaging Social forwards the event to the Meta Conversions API for attribution.

The ctwa_clid is included in the referral object of the inbound-message webhook payload when a customer starts a conversation from an ad. The following example shows the relevant portion of the webhook message:

{
  "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"
    }
  ]
}

Store the ctwa_clid value from the referral object. Pass it in the user_data of every conversion event you send for this conversation. For more information about the referral webhook, see Webhooks components in the Meta developer documentation.

Prerequisites

Before you send conversion events, you need the following:

• A WhatsApp Business Account (WABA) that is linked to your AWS account.

• An active "Ads that Click to WhatsApp" campaign on Meta.

• Your application must capture the ctwa_clid from the inbound-message webhook when a customer starts a conversation from an ad click. This value is generated by Meta and cannot be fabricated.

Important

If you linked your WhatsApp Business Account (WABA) before August 6, 2026, you must redo the sign-up flow to grant permissions to AWS End User Messaging Social to send conversion events. Follow steps 1 through 14 under "Sign up through the console" in Signing up for WhatsApp, and select the existing WABA and phone number already associated with your AWS account. You can then skip the remaining steps.

Step 1: Create a conversions dataset

Before you can send conversion events, you must create a conversions dataset for your WABA. Each WABA has exactly one dataset (this is enforced by Meta). The operation is idempotent: if a dataset already exists, the existing dataset ID is returned.

The following example creates or retrieves the dataset for a WABA. Replace waba-id with the ARN of your linked WhatsApp Business Account (WABA) (for example, arn:aws:social-messaging:us-east-1:123456789012:waba/a1b2c3d4e5example).

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

The response contains the dataset ID. Save this value. You pass it as the datasetId parameter every time you send a conversion event.

{
    "datasetId": "123456789012345"
}

Step 2: Send conversion events

After you create a dataset, you can send conversion events to Meta using the SendWhatsAppConversionEvent API. Each call delivers one or more events to the Meta Conversions API for attribution.

The event content you send in the event-data parameter follows the Meta Conversions API server-event format. AWS End User Messaging Social forwards this content to Meta. For the complete list of event fields, see the Meta server-event parameters reference in the Meta developer documentation.

Send a purchase conversion event

The following example reports a Purchase conversion. Replace the placeholder values with your own.

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
            }
        }
    ]
}'

The response contains a request ID that identifies your submission:

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

Send a lead conversion event

Non-purchase event types such as LeadSubmitted do not require 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"
            }
        }
    ]
}'

Send multiple events in one request

The data array accepts multiple events in a single call. Meta allows up to 1,000 events per request.

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
            }
        }
    ]
}'

Conversion event reference

The event-data parameter is a JSON object with a data array containing one or more event objects. The following tables describe the most commonly used fields for "Ads that Click to WhatsApp" conversions. Meta is the source of truth for event content; see the Meta server-event parameters reference in the Meta developer documentation for the full specification.

Required event fields

Field	Type	Description
event_name	String	The type of conversion. Case-sensitive. Common values include Purchase, LeadSubmitted, and ViewContent.
event_time	Number	The time the conversion happened, as a Unix timestamp in seconds. Must be within the last 7 days and not in the future.
action_source	String	Must be business_messaging.
messaging_channel	String	The messaging channel. Use whatsapp.
user_data	Object	Information used to match the event to the ad click. See Required user_data fields.

Required user_data fields

The following table describes the required fields in the user_data object.

Field	Type	Description
whatsapp_business_account_id	String	Your numeric Meta WhatsApp Business Account ID (from Meta Business Settings).
ctwa_clid	String	The click-to-WhatsApp click ID from the inbound-message webhook of the conversation the ad started. Meta validates this value; it cannot be fabricated.

Important

If you include personally identifiable information (PII) in user_data, such as email addresses or phone numbers, you must provide the values as SHA-256 hashes. Meta rejects unhashed PII. The ctwa_clid value is not hashed.

The custom_data object

For Purchase events, you must include the custom_data object with the following fields:

Field	Type	Description
currency	String	The ISO 4217 currency code (for example, USD).
value	Number	The monetary value of the conversion.

Error handling

Because AWS End User Messaging Social forwards your event content to Meta, most event-content problems surface as an InvalidParametersException. The error message includes the reason reported by Meta, for example: an unrecognized event name, an event time outside the allowed window, missing currency for a purchase, unhashed PII, or an invalid ctwa_clid.

Error	HTTP status	Meaning
InvalidParametersException	400	The request or event content was invalid. The error message describes the specific problem.
ResourceNotFoundException	404	The specified WABA or dataset could not be found.
AccessDeniedByMetaException	403	Meta rejected the request due to permissions (for example, the underlying Meta access token lacks the required permission or is invalid).
ThrottledRequestException	429	The request rate exceeded the allowed limit. Retry with exponential backoff.
DependencyException	502	A downstream dependency (Meta) returned an error. Retryable.
InternalServiceException	500	An internal error occurred. Retryable.