# Sending WhatsApp conversion events in AWS End User Messaging Social
<a name="conversions-api"></a>

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
<a name="conversions-api-how-it-works"></a>

The end-to-end workflow is:

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

1. The inbound message arrives in your [configured event destination](managing-event-destinations.html) (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.

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

1. 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](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components#messages-object) in the Meta developer documentation.

## Prerequisites
<a name="conversions-api-prerequisites"></a>

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](getting-started-whatsapp.html), 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
<a name="conversions-api-create-dataset"></a>

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
<a name="conversions-api-send-events"></a>

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](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/server-event) in the Meta developer documentation.

### Send a purchase conversion event
<a name="conversions-api-send-purchase"></a>

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
<a name="conversions-api-send-lead"></a>

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
<a name="conversions-api-send-batch"></a>

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
<a name="conversions-api-event-reference"></a>

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](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/server-event) in the Meta developer documentation for the full specification.

### Required event fields
<a name="conversions-api-event-required-fields"></a>


| 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](#conversions-api-event-user-data). | 

### Required user\_data fields
<a name="conversions-api-event-user-data"></a>

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
<a name="conversions-api-event-custom-data"></a>

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
<a name="conversions-api-errors"></a>

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. |