Messenger Lead Generation Ads with target app for follow ups

Advertisers may select a specific app to receive messages from a Messenger Lead Ads campaign. More info on Messenger Lead Ads. To test a Lead Generation Ad you can use this Sample Ad injected into your feed.

The use case for this feature is when a Business drive leads into Messenger but wants to use an app to follow up on collected leads. For the specific use case of leads, the ad delivery model can optimize for lead completion as objective while providing handover functionality for Apps to then handle the follow up for completed leads.

When a person clicks on a Messenger Lead Ads, the app Messenger Leadgen (App Id: 413038776280800) will take thread control. And prompt people with the questions defined on the ad. As a result the person will either complete or not complete the automated flow. After automated flow ends the thread control will be handover to an app (if defined) or thread control will be released (when no app is defined).

While a lead generation ad is ongoing, by default webhooks are not sent to apps but after the flow ends the app can get a summary message of what happened or get the history of messages using Conversation API.

The Page Inbox can always be used to control the thread and reply.

Creating an ad with and app

For this example shows the creation of a Messenger Lead Ad using Ads Manager. For these types of ads you can define the content that will be used to qualify the lead and the target app that will take over to follow up on leads.

Create a Message Template

The Message Template defines the questions used to qualify the lead. This flow defines when the answer means that this is a complete or disqualified lead.

Connect an App

In the Advanced Tab of the Message Template select Connect An App. This toggle is only availble to Pages with authorized app in the Advanced Messaging page setting. Once active you can select the desired app. You can now Save and Finish and expect the target app will get thread control after the lead flow finishes.

Note that you can also select to send a summary message. This setting allows the app to get a message webhook with the content of the information collected during lead submission.

Expected Webhooks

On every lead submission you can use the target app to get thread control. Once that thread control is passed the standard messaging window will be open to allow for follow ups using Send API.

Summary Message

This message is only sent for Lead Ads with summary message enabled and the lead is completeted. The structure of the webhook mocks a message sent by the person to the Page and contains all info shared during the lead flow.

Note that this summary message will not appear in the thread for either the person or the Page. The goal of this message is to help apps that are not listening to messaging_handover get an initial message to trigger them with context to get started.

{
    "object": "page",
    "entry": [
        {
            "time": 1661209504608,
            "id": "104508901353867",
            "messaging": [
                {
                    "sender": {
                        "id": "5794982867201265"
                    },
                    "recipient": {
                        "id": "542998526103632"
                    },
                    "timestamp": 1661209328,
                    "message": {
                        "mid": "m_2OF0H5fb2HNRyjM0rt2FVBAaDQp_p5DQlffdEXNVyOrraxQCt0tFwWXwq3QctcvbpjSX1rSY8BX9Y2IXwPirWA",
                        "text": "Lead summary:
Are you interested in becoming a reseller?: Yes
What city is your store located?: Menlo Park"
                    },
                    "hop_context": {
                        "app_id": 498721317747541,
                        "metadata": "messenger_lead_gen_complete"
                    }
                }
            ]
        }
    ]
}

For Apps subscribed to Handover Protocol Events (HOP)

The change in thread control will trigger webhooks to apps subscribed to the messaging_handover field. In the following example the Ad is configured to pass thread control to app 2262510160704936. So on completion the pass show from leadgen App 413038776280800 to the target app and the metadata will read `messenger_lead_gen_complete .

If the lead flow is dropped or the user is disqualified the metadata will show messenger_lead_gen_incomplete instead. This allows apps to have a fallback experience for non leads.

Note that this webhook triggers on thread control changes, so it will actually arrive before the summary message webhook when enabled. This fact can be used to either ignore or expect the summary webhook.

{
    "object": "page",
    "entry": [
        {
            "id": "104508901353867",
            "time": 1662056205364,
            "messaging": [
                {
                    "recipient": {
                        "id": "542998526103632"
                    },
                    "timestamp": 1662056205364,
                    "sender": {
                        "id": "5794982867201265"
                    },
                    "pass_thread_control": {
                        "previous_owner_app_id": 413038776280800,
                        "new_owner_app_id": 2262510160704936,
                        "metadata": "messenger_lead_gen_complete"
                    }
                }
            ],
            "hop_context": [
                {
                    "app_id": 2262510160704936,
                    "metadata": "messenger_lead_gen_complete"
                }
            ]
        }
    ]
}