Messenger API Updates for Europe

Changelog

Jan 20th 2021

Messenger

Jan 6th 2021

Messenger

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

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

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:

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.

AreaFeatureNotes

Receive API (Webhooks)

message (text & image only)

None

Receive API (Webhooks)

message (with product details)

None

Receive API (Webhooks)

messaging_postbacks

Only postback webhooks for get started button, icebreaker and supported templates will be operational. Other postback webhooks will be affected

Receive API (Webhooks)

message_echoes (text, image, generic template, button template, media template only), messaging_handovers, standby

None

Send API

Text

None

Send API

Image (jpg,png,gif)

None

Send API

Generic Template, Button Template, Media Template (images only, other media/attachments including audio, video, and files will return an error message)

Only supported on Android and iOS. Template will not be rendered on web client and chat plugin. Users will see an Attachment unavailable error

Send API

URL Button,Postback Button,Call Button

Only supported on Android and iOS. Template will not be rendered on web client and chat plugin. Users will see an Attachment unavailable error

Send API

Quick replies

None

Send API

Message Tags

None

Entry Points

m.me link

None

Entry Points

Message us plugin

None

Entry Points

Private replies

None

Entry Points

Chat Plugin

None

Entry Points

Chat Plugin Guest Mode

None

Messenger Profile API

Ice breakers, Get started button, Welcome Page, Domain Whitelist, Account Linking URL

None

Conversation API

Conversation API

Only text message will work. shares and sticker field will return null and attachment field will return a fallback message in name field

Handover Protocol

Handover Protocol

None

Handover Protocol

Handover Protocol for ads that click through to Messenger

None

User Profile API

User Profile API

Supported for all fields except for profile_pic. API request with profile_pic field will return an error message

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.

Area: FeatureUser ImpactDeveloper ImpactMitigation

Send API:


Media/attachment (audio, video, files) other than images

Media/attachments on new messages won't render in the thread. Media/attachments on existing messages will still be visible

Returns an error message

Send a URL to the media/attachment as plain text

Send API:


Templates (Receipt template, Airline template)

Templates won’t render in the message thread because API calls will fail. Templates in existing messages will still be visible, but users won’t be able to take any action on them

Returns an error message

Replace templates with a combination of text, quick replies and web views

Send API:


Shops product template

Templates won't render in the thread because API calls will fail.

Returns an error message

N/A

Send API:


Send API with user_ref

No user impact

Returns an error message

N/A

Send API:


One Time Notification (OTN)

Templates won’t render in the thread because API calls will fail. Old templates will still be usable but users won’t be able to take any action on them

Returns an error message. For existing OTN token, Send API calls won't work


For OTN template that were sent out in the past (pending user opt-in), user clicks won't work

N/A

Send API:


Sender actions

Typing indicator won't be visible

Returns an error message

N/A

Receive API (Webhooks):


message (with media/attachment)

User can send attachments but will receive an error message letting them know the business may not have received the attachment

Webhook will be delivered with attachment unavailable fallback payload

N/A

Receive API (Webhooks):


message_echoes(except text and image)

No User Impact

Webhook will be delivered with attachment unavailable fallback payload

N/A

Receive API (Webhooks): message_deliveries, messaging_account_linking, messaging_policy_enforcement, messaging_optins, message_reactions, message_reads, messaging_referrals


No User Impact

Webhook will not be delivered

N/A

Messenger Profile API:


Persistent menu

Users won't see the persistent menu. composer_input_disabled setting will be unavailable.

API call will succeed. Persistent menu won't be shown in thread

Use the Get Started button or a menu keyword. See Messenger Profile API - Persistent menu

Persona API:


Persona

Persona details (name & profile pic) won't show in the thread.

Returns an error message

Introduce another persona. See Persona API fallback

Account linking:


Account linking

None

Returns an error message

N/A

ID Matching:


PSID/ASID matching

N/A

Returns an error message

N/A

Custom Labels:


Custom labels

N/A

Returns an error message

N/A

Entry Points:


Chat Plugin Guest Mode Upgrade

Users are not offered the upgrade dialog

Upgrade webhook is not delivered

N/A

Entry Points:


Web Plugins (Send to Messenger


Checkbox plugin)

Plugins won't render

No change

N/A

Entry Points:


Web Plugins (Checkbox plugin, Chat plugin) prior_message block when user responds to first message

No change

prior_message block won't be available via webhook

N/A

Messenger Extensions SDK:


Messenger Extensions SDK

N/A

Affected fields (psid, tid) will be empty

N/A

Messenger Feature Review API:


Messenger Feature Review API

N/A

Returns an error message

N/A

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?"
   }
}