Skip to main content

​
Automatic Events API

Updated: Nov 18, 2025 Business customers who access Embedded Signup are given the option to opt-in to automatic event identification: 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 webhook field. You can then report the event for the customer using the Conversions API so that it can be leveraged by the customer using a Meta surface (in 2026, see Limitations below). To learn more about how this feature works, see these additional resources.

​
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 Embedded Signup and are able to onboard business customers who complete flow. Your webhook server 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 > Webhooks > Configuration panel and subscribe to the 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. Include any relevant values from the event webhook, as appropriate. See Send events via Conversions API 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. 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. 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 Thumbs down icon 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