Messenger API Updates for Europe

Changelog

Jan 20th 2021

Messenger

• Messenger Feature Review API is currently not supported.
• Conversation API sticker field is currently not supported and will return null. Developer should rely on webhooks to get the sticker details.
• Composer input disable settings in Messenger Profile API is currently not supported.

Jan 6th 2021

Messenger

• Messenger Extensions SDK will return an empty response for impacted fields (psid, tid).
• Send API with user_ref is currently not supported.

Dec 16th 2020

Messenger

Added below features to No changes section

• User Profile API will be supported for all fields except for profile_pic. API calls with profile_pic field will return an error message.
• Receive API (Webhooks) message_echoes will support templates(generic, button, media)

Dec 7th 2020

Messenger

• Updated guidance on how to check Page impact using Messenger Profile API subject_to_new_eu_privacy_rules flag. Developers will now have the option to either use Messenger Profile API or the tool via app dashboard.
• Updated mitigation/fallback guidance for User Profile API. Developers can leverage participants field in Conversation API to retrieve the user's name.

Dec 4th 2020

• Added Frequently asked question (FAQ) section.

Dec 2nd 2020

Messenger

Added below features to No changes section

• Handover Protocol and Handover Protocol for ads that click through to Messenger will be supported.
• Receive API - messaging_handovers and standby webhooks will be supported.

Dec 1st 2020

Messenger

• Updated guidance on how to check User Thread Impact using User Level Menu API. Please see here for more details.

Nov 30th 2020

Messenger

Added below features to No changes section

• Generic Template, Button Template, Media Template. Only supported on Android and iOS. Template will not be rendered on web client.
• URL Button, Postback Button, Call Button. Only supported on Android and iOS. Template will not be rendered on web client.
• Image support for Send and Receive API (webhooks).
• message_echoes webhook. Only supported for text and image.

Context

As part of our efforts to comply with new privacy rules in Europe, we're making updates that will impact some developers and businesses that use our Messenger API. Beginning December 16th, several Messenger APIs will be unavailable for developers and businesses in Europe, and for people in Europe who connect with businesses globally. These changes will impact some APIs and UI components (listed in the next sections) for the following audience:

• Europe pages in all chats
• Pages with admins in Europe in all chats
• Any chats with people in Europe

Impacted countries: All of the 30 European Economic Area (EEA) countries, which includes:

• All 27 European Union member states
• Norway
• Iceland
• Liechtenstein
• United Kingdom

Given the impact listed previously, we recommend providing an alternate experience using quick replies, text and inline URLs for webviews for the impacted scenarios. The two tables that follow provide:

• Features and APIs with no changes
• Affected Features and APIs with Mitigations

We are currently working to restore these features and will continue to update this document and the changelog section with the details as they are available. You can also refer to the FAQ section for more details on frequently asked questions.

Features and APIs with no changes

Following is a list of features and APIs that are not affected by these changes. Any exceptions are listed in the Notes column.

Affected features and APIs with mitigations

The following actions can help you determine scenarios that are impacted by these changes:

• Page Impact - To determine go to your app dashboard and navigate to the Messenger Settings menu. Enter page IDs in the section titled Will your page be affected by updates due to new privacy rules in Europe. Note that your app must have 'pages_messaging' permission for the Pages you're querying. Developer can also leverage subject_to_new_eu_privacy_rules flag on Messenger Profile API to check for page impact.
• User Thread Impact - To determine, invoke the User Level Menu API. If you get a valid response, there is no impact. If you get an error message with code 10, subcode 2018336, the thread is impacted. NOTE: This status can change over time. Use care if you are caching this data and update it regularly.
• Any API call which results in error code 10, subcode 2018336

The table that follows provides more details and recommendations for alternatives on heavily-used APIs.

Error Response

The following error is returned for API calls that are not operational due to the new privacy rules in Europe. You should leverage the unique error code and error subcode that follows to identify errors and handle the fallback gracefully.

{
   "error":{
      "message":"(#10) This action was not submitted due to new privacy rules in Europe.
                 See developer documentation for more info",
      "type":"OAuthException",
      "code":10,
      "error_subcode":2018336,
      "fbtrace_id":"AUmkjfWVra1NAa-qEH5NcI8"
   }
}

Webhook - Attachment unavailable fallback

The following fallback webhook will be delivered when user sends a message with unsupported media/attachment.

{
  "message":{
      "mid":"m_toDnmD...",
      "text":"Some text",
      "attachments":[
         {
            "type":"fallback",
            "payload":{
               "url":null,
               "title":"Attachment Unavailable"
            }
         }
      ]
   }
}
    

Conversation API - Attachment field fallback

The following API response will be returned when you query the Conversation API that contains an unsupported attachment/media.

GET {{MESSAGE_ID}}?fields=id,message,attachments,...

{
  "id":"{{MESSAGE_ID}}",
  "message":"{{MESSAGE_TEXT}}",
  "attachments":{
    "data":[
      {
        "id":1234, //dummy id
        "name":"Media not available due to new privacy rules in Europe.
                See developer documentation for more info"
      }
    ]
  }
}
    

Other Fallback Experiences For Developers

Send API - Media/attachment (audio, video, files) fallback

Instead of sending the media as an attachment, you can send the raw media/attachment URL as a text. This will allow users to open/view the media/attachment via Messenger In-app browser.

Before

{
   "recipient":{
      "id":"{{PSID}}"
   },
   "messaging_type":"response",
   "message":{
      "attachment":{
         "type":"{image|video|audio|file}",
         "payload":{
            "url":"https://example.com/video.mp4"
         }
      }
   }
}
  

After

{
   "recipient":{
      "id":"{{PSID}}"
   },
   "messaging_type":"response",
   "message":{
      "text":"https://example.com/video.mp4"
   }
}
  

Send API - Templates (Receipt, Airline, Product) fallback

Instead of sending the information as a template, you can use a combination of plain text and quick replies instead. This enables users to have enough context/information to continue the conversation.

• Images can be sent as a plain text url. Users will then have to click on it and it wil open up Messenger In-app browser.
• Buttons can be replaced with quick replies because you will still receive the message payload when users click on it.
• Title and description can be sent as a separate messages.
• More complex templates such as the airline and receipt templates can be simplified by ignoring some fields or you can recreate a similar template hosted at a external URL and serve the template by providing the URL link.

Before

{
   "recipient":{
      "id":"{{PSID}}"
   },
   "message":{
      "attachment":{
         "type":"template",
         "payload":{
            "template_type":"{{SOME_UNSUPPORTED_TEMPLATE}}",
            "elements":[
               {
                  "title":"Welcome!",
                  "image_url":"https://petersfancybrownhats.com/company_image.png",
                  "subtitle":"We have the right hat for everyone.",
                  "buttons":[
                     {
                        "type":"web_url",
                        "url":"https://petersfancybrownhats.com",
                        "title":"View Website"
                     },
                     {
                        "type":"postback",
                        "title":"Start Chatting",
                        "payload":"DEVELOPER_DEFINED_PAYLOAD"
                     }
                  ]
               }
            ]
         }
      }
   }
}
  

After

{
   "recipient":{
      "id":"{{PSID}}"
   },
   "messaging_type":"response",
   "message":{
      "text":"Welcome! We have the right hat for everyone.",
      "quick_replies":[
         {
            "content_type":"text",
            "title":"View Website",
            "payload":"{{DEVELOPER_DEFINED_PAYLOAD}}"
         },
         {
            "content_type":"text",
            "title":"Green",
            "payload":"{{DEVELOPER_DEFINED_PAYLOAD}}"
         }
      ]
   }
}
      

Send API - URL Button fallback

The URL Button opens a webpage in the Messenger webview. This button can be used with the Button and Generic Templates. You can send the URL link directly in plain text instead of wrapping it with a URL button. Users will be able to click the plain text URL and the URL will open inside the Messenger in-app browser. You can also use a URL-shortener service to convert a lengthy URL to its short form so it easier for users to remember and type.

Before

{
  "recipient":{
    "id":"{{PSID}}"
  },
  "message":{
    "attachment":{
      "type":"template",
      "payload":{
        "template_type":"button",
        "text":"Try the URL button!",
        "buttons":[
          {
            "type":"web_url",
            "url":"https://www.messenger.com/",
            "title":"URL Button"
          }
        ]
      }
    }
  }
}

After

{
   "recipient":{
      "id":"{{PSID}}"
   },
   "messaging_type":"response",
   "message":{
      "text":"https://www.messenger.com/"
   }
}

Messenger Profile API - Persistent menu fallback

You can use the Get Started button to set the context and introduce the various menu/options available to the user. When the Get Started button is clicked, a combination of text and quick replies can be used as a replacement for persistent menu experience.

You should also provide a special keyword menu to display the menu options. This will allow the user to type menu at any point in the conversation and bring up the menu options in the form of text and quick replies.

Before

{
  "persistent_menu":[
    {
      "locale":"default",
      "composer_input_disabled":false,
      "call_to_actions":[
        {
          "type":"postback",
          "title":"Talk to an agent",
          "payload":"CARE_HELP"
        },
        {
          "type":"postback",
          "title":"Outfit suggestions",
          "payload":"CURATION"
        },
        {
          "type":"web_url",
          "title":"Shop now",
          "url":"https://www.originalcoastclothing.com/",
          "webview_height_ratio":"full"
        }
      ]
    }
  ]
}

After

{
   "recipient":{
      "id":"{{PSID}}"
   },
   "messaging_type":"response",
   "message":{
      "text":"Welcome to Original Coast Clothing. At any point in time,
              you can type 'menu' to bring up the list of menu options.
              Here are some of the available options:",
      "quick_replies":[
         {
            "content_type":"text",
            "title":"Talk to an agent",
            "payload":"CARE_HELP"
         },
         {
            "content_type":"text",
            "title":"Outfit suggestions",
            "payload":"CURATION"
         },
         {
            "content_type":"text",
            "title":"Shop now",
            "payload":"SHOP_URL"
         }
      ]
   }
}

Persona API fallback

You can use a message to introduce a different persona in the conversation flow. This will let users know that a different agent is handling the conversation despite the profile picture being unchanged.

Before

{
  "recipient":{
    "id":"{{PSID}}"
  },
  "message":{
    "text":"How can I help you?"
  },
  "persona_id":"{{PERSONA_ID}}"
}

After

{
   "recipient":{
      "id":"{{PSID}}"
   },
   "messaging_type":"response",
   "message":{
      "text":"Hi, this is Joe from OCC, How can I help you?"
   }
}