Login Connect with Messenger

With Login Connect, your users can now opt into communicating with your business through Messenger right from the Facebook Login flow on your app or website. This allows you to deepen your user engagement and provide stronger, more efficient customer care by communicating with more customers on the channel they prefer. Enjoy powerful automation on Messenger that cuts down on the time your team spends answering basic requests while providing top-notch customer service.

How It Works

When a user arrives at a third-party site and logs in with Facebook, after proceeding with the standard login flow, they will see a screen inviting them to allow the business to contact them via Messenger to provide offers, support, etc.

The business will be able to contact the user according to the existing Messenger Platform policies (In short, the business has 24 hours to message the user, and 24 hours to respond to every message the user sends to the business. The user, however, can initiate messaging at any time). The business can proactively reach out to the user for certain use cases through Message Tags.

The main difference between these solutions and the existing messenger solutions, is that the user is already at the 3rd party site when they create this connection (as opposed to creating the connection from the business’s Page on FB). It leverages a business’s existing FB Login integration to grow their messenger connections via a new entry point.

If you are interested in integrating this feature into your FB Login implementation, please fill out this form to be notified when we open it publicly.

Before you start

Implementation

There are 3 ways to integrate this feature into a brands login flow. By having a direct integration, where a single app handles login and messages, by using a Messenger provider and/or by using a login provider. This guide will cover the first two scenarios.

Direct integration

1. Developer Dashboard configuration

  1. Request the user_messenger_permission to get access to the Login Connect with Messenger section in the developer panel settings
  2. In Facebook login settings, enable the Messenger consent screen
    1. Add the page that will be used to message users. The page name is going to be shown to the user when going through the Login flow. To find out the ID of your Page, follow this steps.
  3. Define the page that will be show as default when the permission is requested without sending the messenger_page_id parameter

2. Configure Login Flow

In the Facebook Login setup request the user_messenger_contact permission from the user. Also provide the Page ID in the form of a messenger_page_id parameter.

Currently, the new permission is supported by the Javascript SDK Login Dialog, manual Login flow on the Web, Android SDK Login Dialog and iOS SDK login dialog.

JavaScript SDK Login Dialog
      FB.login(function(response) {
      // handle the response
      }, {
      scope: 'public_profile,email,user_messenger_contact',
      messenger_page_id: 12345
      });
Manual Login flow
      https://www.facebook.com/v11.0/dialog/oauth?
      client_id={app-id}
      &redirect_uri={redirect-uri}
      &auth_type=rerequest
      &scope=email,user_messenger_contact
      &messenger_page_id=12345

3. Retrieve or generate `login_id` value

Once a user successfully logged in, you are able to message the user. To do so, you will need to retrieve or generate the login_id.

Option 1: Set up and process Messenger webhooks

Subscribe to the messaging_optins webhook for your app/page. Once set up, you will receive a messaging_optins event when a user grants your app user_messenger_contact during the Login flow.

Note that if you use different apps for Messenger and Login, the webhook event will be sent to the Messenger app. For this purpose, the Messenger app needs to be granted the pages_manage_metadata permission for the page in scope.

      {
        "recipient": {
          "id": "<PAGE_ID>"
        },
       "timestamp": 1234567890,
       "optin": {
          "login_id": "12345",
       }
      }    
    
Option 2: Self-generate on the fly

Generate the SHA-256 hash of the following string with the app's Client Token as the key: umc_<ASID>_<app_id>_<page_id>

You can find the Client Token in the App Dashboard: Settings > Advanced > Security.

If sending messages after a successful user login, verify which permissions the user granted your app by calling the /{user-id}/permissions edge.

Example code in PHP:

      $login_id = hash_hmac(‘sha256’, ‘umc_<asid>_<app_id>_<page_id>’, $client_token);
    

4. Send a message

Use the Messenger Send API to send a message to the user, using login_id from the previous step as recipient.login_id.

In order to send a message on behalf of a page, the app must have the pages_messaging permission for it.

Example request using Quick Replies:

      curl -X POST -H "Content-Type: application/json" -d '{
       "messaging_type":"<MESSAGING_TYPE>",
       "recipient":{
          "login_id":"<LOGIN_ID>"
       },
       "message":{
          "text":"Hello world! Thanks for signing up. Here is what you can do on Messenger...",
          "quick_replies":[
             {
                "content_type":"text",
                "title":"Outfit suggestions",
                "payload":"CURATION"
             },
             {
                "content_type":"text",
                "title":"Talk to an agent",
                "payload":"CARE_HELP"
             }
          ]
       }
    }' "https://graph.facebook.com/v11.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
    

Set expectations
Make sure users understand why you contacted them and how they can interact with you on Messenger. Quick Replies makes it easier for users to answer this first message while guiding them in the experience.

Continue using the same page
Once a message is sent through a page, that page becomes the only page allowed to message a user using the login_id recipient key.

The following conditions apply:

  • The initial message must be sent within 24 hours from the consent or comply with the Messenger policy around message tags.

  • You must use a page access token from a page that has granted the app the pages_messaging permission.

5. Continuing the conversation

When a user continues the conversation with you on Messenger, the user will be identified with a PSID according to the Messenger webhook specifications.

Your solution might require to connect a PSID with the corresponding login_id. If the user responds to your first message which you sent to a login_id, the appropriate event (messages, messaging_postbacks, etc.) will be sent to your webhook, with a prior_message object appended, containing the login_id.

For example, the following messages event would be sent to your webhook if the user responded with a text message:

{
   "sender":{
      "id":"<PSID>"
   },
   "recipient":{
      "id":"<PAGE_ID>"
   },
   "timestamp":1458692752478,
   "message":{
      "mid":"mid.145773344618:41d102a3e1ae206a38",
      "text":"Thanks for messaging me!"
   },
   "prior_message":{
      "source":"fb_login",
      "identifier":"12345"
   }
}

Messenger Provider

1. Brand setup

Verify that your customer has access to the user_messenger_contact permission and goes through steps 1 and 2 of the Direct Integrator guide. For the integration to work correctly, the app should have a Page Access Token with the pages_messaging for each page used during the login flow.

2. Messaging optins

Subscribe to the messaging_optins webhook for all the pages configured in 2.1. Once set up, you will receive a messaging_optins event when a user grants your app user_messenger_contact during the Login flow.

Note that the Messenger app needs to be granted the pages_manage_metadata permission for the page in scope.

All apps connected to a page will receive the webhook event when a user logins and grants the permission.

      {
        "recipient": {
          "id": "<PAGE_ID>"
        },
       "timestamp": 1234567890,
       "optin": {
          "login_id": "12345",
       }
      }    
    

3. Send a message

Use the Messenger Send API to send a message to the user, using login_id from the previous step as recipient.login_id.

In order to send a message on behalf of a page, the app must have the pages_messaging permission for it.

Example request using Quick Replies:

      curl -X POST -H "Content-Type: application/json" -d '{
       "messaging_type":"<MESSAGING_TYPE>",
       "recipient":{
          "login_id":"<LOGIN_ID>"
       },
       "message":{
          "text":"Hello world! Thanks for signing up. Here is what you can do on Messenger...",
          "quick_replies":[
             {
                "content_type":"text",
                "title":"Outfit suggestions",
                "payload":"CURATION"
             },
             {
                "content_type":"text",
                "title":"Talk to an agent",
                "payload":"CARE_HELP"
             }
          ]
       }
    }' "https://graph.facebook.com/v11.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
    

Set expectations
Make sure users understand why you contacted them and how they can interact with you on Messenger. Quick Replies makes it easier for users to answer this first message while guiding them in the experience.

Continue using the same page
Once a message is sent through a page, that page becomes the only page allowed to message a user using the login_id recipient key.

The following conditions apply:

  • The initial message must be sent within 24 hours from the consent or comply with the Messenger policy around message tags.

  • You must use a page access token from a page that has granted the app the pages_messaging permission.

4. Continuing the conversation

When a user continues the conversation with you on Messenger, the user will be identified with a PSID according to the Messenger webhook specifications.

Your solution might require to connect a PSID with the corresponding login_id. If the user responds to your first message which you sent to a login_id, the appropriate event (messages, messaging_postbacks, etc.) will be sent to your webhook, with a prior_message object appended, containing the login_id.

For example, the following messages event would be sent to your webhook if the user responded with a text message:

{
   "sender":{
      "id":"<PSID>"
   },
   "recipient":{
      "id":"<PAGE_ID>"
   },
   "timestamp":1458692752478,
   "message":{
      "mid":"mid.145773344618:41d102a3e1ae206a38",
      "text":"Thanks for messaging me!"
   },
   "prior_message":{
      "source":"fb_login",
      "identifier":"12345"
   }
}

Message Tags

Even if the user does not answer the first message, the login_id can be used to send the user additional messages using Message Tags. The supported tags are currently POST_PURCHASE_UPDATE and ACCOUNT_UPDATE.

For example, after a purchase, the POST_PURCHASE_UPDATE tag can be used to send updates to the user:


      curl -X POST -H "Content-Type: application/json" -d '{
      "messaging_type": "MESSAGE_TAG",
      "tag": "POST_PURCHASE_UPDATE",
      "recipient": {
      "login_id": "<LOGIN_ID>"
      },
      "message": {
      "text": "Your order is in route for delivery!"
      }
      }' "https://graph.facebook.com/v11.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

    

Resetting your Messenger State

After a user grants your application permission to contact them on Messenger, your application has 24 hours to send an initial message. This would normally be performed once per user, but you may need to reset your account’s Messenger state to test changes for your integration.

Developers can reset this state by removing the app in the "Apps and websites" tab of their account settings and then adding the reset_messenger_state parameter with the value of 1 when entering Facebook’s OAuth flow. Once the Facebook Login dialog is loaded, the login user's Messenger state will be reset, allowing the developer to continue testing with the current request on the web, or continuing with on a different request such as with the mobile SDKs.

Please note the following when resetting your Messenger state:

  • This functionality is only available for Admins of your application to perform and won’t reset the state of any other users interacting with your application.

  • Resetting your Messenger state isn’t available through the Mobile SDK’s OAuth flow at this time. Developers must use the JavaScript SDK or construct a manual Login Link to reset their Messenger state.

JavaScript SDK Login Dialog

FB.login(function(response) {
// handle the response
}, {
scope: 'public_profile,email,user_messenger_contact',
messenger_page_id: 12345,
reset_messenger_state: 1
});

Manual Login flow

      https://www.facebook.com/v11.0/dialog/oauth?
      client_id={app-id}
      &redirect_uri={redirect-uri}
      &auth_type=rerequest
      &scope=email,user_messenger_contact
      &messenger_page_id=12345
      &reset_messenger_state=1
    

See Also