Implementing Login Connect with Messenger

There are 2 main ways to integrate this feature into the Facebook Login flow on your mobile app or website: 1) By having a direct integration, where a single app handles both login and messages, 2) involving a separate app or provider for the Messenger integration. This guide will cover both scenarios.

Direct integration

1. Developer Dashboard configuration

  1. Make sure your Facebook Application has access to pages_messaging and Messenger is correctly configured. If not, you can follow the Messenger getting started guide.
  2. Request the user_messenger_contact to get access to the Login Connect with Messenger section in the developer panel settings. During development, both pages_messaging and user_messenger_contact will work with Admins, Developers and Testers of the app. Once your app is ready to go live, make sure to submit these permissions for App Review. Both pages_messaging and user_messenger_contact permissions can be requested together.
  3. In Facebook login settings, enable the Messenger consent screen
    1. Add the Facebook Page that will be granting messaging permission to the app 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, these steps.
  4. Define the page that will be shown as default when the permission is requested without sending the messenger_page_id parameter. This is mandatory for SDK flows, as the messenger_page_id parameter is not available in the SDK.

2. Configure Login Flow

In the Facebook Login setup, request the user_messenger_contact permission from the user by adding it to scope parameter. 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/v12.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 has 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/v12.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
    

Comply with requirements for Login Connect and set expectations
You must make it clear to users why you contacted them and your messages must match what the user agreed to receive. You can also make it easier for users to interact with you on Messenger using Quick Replies to help guide their responses.

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 (see Requirements for Using Login Connect with Messenger for further requirments):

  • The initial message must be sent within 24 hours from the user opting in to receiving messages.

  • 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. You will need to ensure you comply with the Developer Policies and Developer Documentation requirements, including those specific to Messenger Platform when messaging users.

Your solution might require connecting 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

To send the first message to users when the message_optins event is fired, the recipient object field identifying the user changes from id to login_id. Additionally, to unlock further use cases with login_id, it needs to be mapped to the 'Login App' ASID.

1. Setting up your Login Connect experience

For this integration, there are two distinct Apps: one for requesting a user's permission to receive messages the ‘Login App’), and a second for messaging the user (the ‘Messenger App’). Verify that your customer has access to the user_messenger_contact permission and goes through steps 2 and 3 of the Direct Integrator guide. For the integration to work correctly, the Messenger 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 step 3.1 of the Direct Integrator guide. Once set up, you will receive a messaging_optins event when a user grants the user_messenger_contact permission to the Login App 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/v12.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
    

Set expectations
Remember, you must make it clear to users why you contacted them and be consistent with what the user agreed to receive. You can also make it easier for users to interact with you on Messenger by using Quick Replies to help guide their responses.

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 (see Requirements for using Login Connect with Messenger for further requirments):

  • The initial message must be sent within 24 hours from the user opting in to receiving messages.

  • 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 connecting 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"
   }
}

Resetting Your Messenger State

After a user grants your business Page permission to contact them on Messenger, your Page 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 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 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/v12.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