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.

Roles overview

The main roles involved in this integration are App admins and Page admins. Please note that the same person can be an admin of both the page and the app.

Integration steps overview

Review the main steps of the integration for each role.

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.

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

      https://www.facebook.com/v19.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.

      {
        "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.

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.

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/v19.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
    

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

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.

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

3. Send a message

After generating login_id or retrieving from the optin, you can use the Messenger Send API to send message to the user as recipient.login_id.

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/v19.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
    

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.

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/v19.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

• Login Connect with Messenger
• Login Connect FAQ
• Facebook Login
• Messenger Getting Started