> ## Documentation Index
> Fetch the complete documentation index at: https://whatsapp-docs.kap.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Automatic events api

# Automatic Events API

Updated: Nov 18, 2025

Business customers who access Embedded Signup are given the option to opt-in to automatic event identification:

![](https://scontent-fra5-2.xx.fbcdn.net/v/t39.2365-6/503425036_1029531339304862_7305936950282438326_n.png?_nc_cat=106\&ccb=1-7&_nc_sid=e280be&_nc_ohc=dvRMnhPj-J0Q7kNvwFR7U9L&_nc_oc=AdnAG_I64XBcUXhCny1VZCY2seVhvVaLc7PokZ9Yaz3KJ8QbNU0x2e11zYo26tf6_hk&_nc_zt=14&_nc_ht=scontent-fra5-2.xx&_nc_gid=-t7Kq3xSQEFsOnkF9LY4xg\&oh=00_AfkhWcOdFqWDVza2NbtInLYXsaWYSL6xA1VsNs1_3gomnw\&oe=69552E4D)

If a business customer opts-in, we use a combination of regex and natural language processing to analyze the customer’s new message threads that originate from a Click-to-WhatsApp ad. If our analysis determines that a lead gen or purchase event has occurred, you can be notified of the determination by subscribing to the [automatic\_events](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/automatic_events) webhook field. You can then report the event for the customer using the [Conversions API](https://developers.facebook.com/docs/marketing-api/conversions-api) so that it can be leveraged by the customer using a Meta surface (in 2026, see [Limitations](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/automatic-events-api#limitations) below).

To learn more about how this feature works, see these [additional resources](https://l.facebook.com/l.php?u=https%3A%2F%2Fmeta.highspot.com%2Fitems%2F6839e4fecd0bb354418ee7ec\&h=AT0cNFHk7IIHHbbKoOoMoN312b3zpFI5ivBLGzN5Jk0hPENceUCCAChdMT33qA9HRGxVh60JToTYrL3_aYMZsj4qpb3CrLua6sbuIPbcRGJLvx12mHYGLMmGMXSwWquozWKSodNpfk-0gw).

## Limitations

Automatic event identification is a new feature, so your business customers won’t be able to see or leverage automatic events reported via Conversions API in any Meta surfaces until 2026. However, if you wish, you can surface this information to your customers using your own solution before then, so they can gain a deeper understanding of their own customers’ needs, preferences, and ad performance.
Automatic event identification is not available to business customers in the European Union, United Kingdom, or Japan.

## Requirements

You have already [implemented](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/implementation) Embedded Signup and are able to onboard business customers who complete flow.
Your [webhook server](https://developers.facebook.com/docs/graph-api/webhooks/getting-started/webhooks-for-whatsapp) is successfully digesting webhooks.

## Setup

Automatic event identification is available as an opt-in feature to all business customers automatically. To be informed of an event, you must subscribe your app to the **automatic\_events** webhook field. However, as soon as you do this, you may begin receiving these webhooks before you are able to digest them. Therefore, we recommend that you complete these steps using a test app before moving your code to production and subscribing your production app to the webhook field.

### Step 1: Subscribe to the automatic\_events webhook field

Navigate to the [App Dashboard](https://developers.facebook.com/apps) > **Webhooks** > **Configuration** panel and subscribe to the [automatic\_events](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/automatic_events) webhook field.

### Step 2: Adjust your webhook callback

Adjust your webhook callback code so that it can successfully digest **automatic\_events** webhook payloads.

#### Lead gen event structure

```
\{
  "object": "whatsapp_business_account",
  "entry": [\
    {\
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",\
      "changes": [\
        {\
          "value": {\
            "messaging_product": "whatsapp",\
            "metadata": {\
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",\
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"\
            },\
            "automatic_events": [\
              {\
                "id": "<WHATSAPP_MESSAGE_ID>",\
                "event_name": "LeadSubmitted",\
                "timestamp": <WEBHOOK_TRIGGER_TIMESTAMP>,\
                "ctwa_clid": "<CLICK_ID>"\
              }\
            ]\
          },\
          "field": "automatic_events"\
        }\
      ]\
    }\
  ]
}
```

#### Lead gen event example

```
\{
  "object": "whatsapp_business_account",
  "entry": [\
    {\
      "id": "102290129340398",\
      "changes": [\
        {\
          "value": {\
            "messaging_product": "whatsapp",\
            "metadata": {\
              "display_phone_number": "15550783881",\
              "phone_number_id": "106540352242922"\
            },\
            "automatic_events": [\
              {\
                "id": "wamid.HBgLMTIwNjY3NzQ3OTgVAgASGBQzQUY3MDVCQzFBODE5ODU4MUZEOQA=",\
                "event_name": "LeadSubmitted",\
                "timestamp": 1749069089,\
                "ctwa_clid": "Afc3nYt4TTydumlFFsatFz8bR2yHCtVA92Veu_zDE4DgAI-QqCwM6eC3-K3lTGHRiLxRTVXFEsdyKQQSa-2obZyuGBq_EYypt_OwbMihBV0pbUoRmrGnEjwFTHop-Px0TfA"\
              }\
            ]\
          },\
          "field": "automatic_events"\
        }\
      ]\
    }\
  ]
}
```

#### Purchase event structure

```
\{
  "object": "whatsapp_business_account",
  "entry": [\
    {\
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",\
      "changes": [\
        {\
          "value": {\
            "messaging_product": "whatsapp",\
            "metadata": {\
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",\
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"\
            },\
            "automatic_events": [\
              {\
                "id": "<WHATSAPP_MESSAGE_ID>",\
                "event_name": "Purchase",\
                "timestamp": <WEBHOOK_TRIGGER_TIMESTAMP>,\
                "ctwa_clid": "<CLICK_ID>",\
                "custom_data": {\
                  "currency": "<CURRENCY_CODE>",\
                  "value": <AMOUNT>\
                }\
              }\
            ]\
          },\
          "field": "automatic_events"\
        }\
      ]\
    }\
  ]
}
```

#### Purchase event example

```
\{
  "object": "whatsapp_business_account",
  "entry": [\
    {\
      "id": "102290129340398",\
      "changes": [\
        {\
          "value": {\
            "messaging_product": "whatsapp",\
            "metadata": {\
              "display_phone_number": "15550783881",\
              "phone_number_id": "106540352242922"\
            },\
            "automatic_events": [\
              {\
                "id": "wamid.HBgLMTIwNjY3NzQ3OTgVAgARGBIwRkU4NDI5Nzk3RjZDMzE2RUMA",\
                "event_name": "Purchase",\
                "timestamp": 1749069131,\
                "ctwa_clid": "Afc3nYt4TTydumlFFsatFz8bR2yHCtVA92Veu_zDE4DgAI-QqCwM6eC3-K3lTGHRiLxRTVXFEsdyKQQSa-2obZyuGBq_EYypt_OwbMihBV0pbUoRmrGnEjwFTHop-Px0TfA",\
                "custom_data": {\
                  "currency": "USD",\
                  "value": 25000\
                }\
              }\
            ]\
          },\
          "field": "automatic_events"\
        }\
      ]\
    }\
  ]
}
```

### Step 3: Trigger webhooks

To trigger an **automatic\_events** webhook:

Access your test implementation of Embedded Signup.
Authenticate the flow using a business that has a Click-to-WhatsApp ad already configured.
In the WABA section screen, check the **Instruct Meta to automatically identify order and lead events checkbox**, and complete the flow.
Access the Click-to-WhatsApp ad and click it to send a message to the business.
Use the business to reply to the message with one of the strings below (must be exact).

**For a purchase event:** *Your tracking number is AB123456789BR*
**For a lead gen event:** *I am interested in learning more about the product*

After you have triggered both **automatic\_events** webhook payloads, confirm that your webbook callback has digested each webhook according to your business needs.

### Step 4: Report each event using Conversions API (Optional)

If you wish, you can report each event using the [Conversions API](https://developers.facebook.com/docs/marketing-api/conversions-api/business-messaging). Include any relevant values from the event webhook, as appropriate.

See [Send events via Conversions API](https://developers.facebook.com/docs/marketing-api/conversions-api/business-messaging#send-events-via-the-conversions-api-2) for additional information about reporting events.

#### Lead gen syntax

```
curl 'https://graph.facebook.com/<API_VERSION>/<DATASET_ID>/events' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-d '
\{
  "data": [\
    {\
      "event_name": "LeadSubmitted",\
      "event_time": <WEBHOOK_TRIGGER_TIMESTAMP>,\
      "action_source": "business_messaging",\
      "messaging_channel": "whatsapp",\
      "user_data": {\
        "ctwa_clid": "<CLICK_ID>"\
      },\
      "messaging_outcome_data": {\
        "outcome_type": "automatic_events"\
      }\
    }\
  ]
}
'
```

#### Purchase event syntax

```
curl 'https://graph.facebook.com/<API_VERSION>/<DATASET_ID>/events' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-d '
\{
  "data": [\
    {\
      "event_name": "Purchase",\
      "event_time": <WEBHOOK_TRIGGER_TIMESTAMP>,\
      "action_source": "business_messaging",\
      "messaging_channel": "whatsapp",\
      "user_data": {\
        "ctwa_clid": "<CLICK_ID>"\
      },\
      "custom_data": {\
        "currency": "<CURRENCY_CODE>",\
        "value": <AMOUNT>\
      },\
      "messaging_outcome_data": {\
        "outcome_type": "automatic_events"\
      }\
    }\
  ]
}
'
```

## Enabling and disabling via Meta Business Suite

Business customers who have already been onboarded via Embedded Signup can enable automatic event identification using Meta Business Suite.

![](https://scontent-fra3-2.xx.fbcdn.net/v/t39.2365-6/503429874_596845240111750_4726469615509960636_n.png?_nc_cat=111\&ccb=1-7&_nc_sid=e280be&_nc_ohc=WKCbU6Ko9VEQ7kNvwGfP-0I&_nc_oc=AdlUGd_-XZmJoCi9w9-XoyzQsNcg3WG1nWa-B63NZXaJmI3VRLINZ2mQEU9iONQNCgo&_nc_zt=14&_nc_ht=scontent-fra3-2.xx&_nc_gid=-t7Kq3xSQEFsOnkF9LY4xg\&oh=00_AfkO1XmW1z251Dp2SKrFjN7SmTzE1fkPvrRc1DvyrnwkuA\&oe=69551DEB)

If a business customer who you have already onboarded wants to enable this feature, you can send them these instructions:

Access Meta Business Suite at [https://business.facebook.com](https://business.facebook.com/).
Navigate to **Settings** > **Accounts** > **WhatsApp accounts** and click your WhatsApp Business Account.
In the **Summary** tab, scroll down to **Privacy and data sharing**.
Use the “ **Automatically identify**... “ toggles to enable or disable automatic event identification as desired.

Did you find this page helpful?

![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg)

![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg)

ON THIS PAGE

Limitations

Requirements

Setup

Step 1: Subscribe to the automatic\_events webhook field

Step 2: Adjust your webhook callback

Lead gen event structure

Lead gen event example

Purchase event structure

Purchase event example

Step 3: Trigger webhooks

Step 4: Report each event using Conversions API (Optional)

Lead gen syntax

Purchase event syntax

Enabling and disabling via Meta Business Suite

***