Messenger API Updates for Europe and Japan

Changelog

Sept 14 2021

Messenger API features restored as of 9/14/2021:

Feature restoration TBD:

Aug 10 2021

Messenger API features restored as of 8/10/2021:

Feature restoration TBD:

Jun 21 2021

  • source attribute in webhooks is not included for accounts affected by the regulations in Europe and Japan

Apr 20 2021

  • messaging_optins webhook is restored for Chat Plugin, Send to Messenger Plugin, and Checkbox Plugin. One Time Notification messaging_optins webhook will be restored in Q2 2021.
  • messaging_referrals webhook is restored for m.me link and Chat Plugin. CTM ads messaging_referrals webhook restoration is TBD.

Apr 15 2021

  • Included CTM HOP details

Apr 13 2021

Messenger API features restored as of 4/13/2021:

Targeting restoration in Q2 2021 (actual dates of restoration may vary):
Feature restoration TBD:

Mar 30 2021

  • Updated context section below to address new privacy rules in Japan
  • Timeline for all feature remediations we had targeted to restore by end of Q1 is now being moved to Q2. Actual dates of restoration may vary

Feb 3rd 2021

Messenger

Targeting restoration in Q1 2021 (actual dates of restoration may vary):
Targeting restoration in Q2 2021 (actual dates of restoration may vary):
Feature restoration TBD:

Older changelog

Older changelog details can be found here.

Context

As part of our efforts to comply with new privacy rules in Europe and Japan, 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/or Japan, and for people in Europe and/or Japan who connect with businesses globally. These changes will impact some APIs and UI components (listed in the next sections) for the following audience:

  • Pages in Europe and Japan
  • Pages with admins in Europe and Japan
  • People in Europe and Japan who message businesses globally

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

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

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, messaging_policy_enforcement

None

Receive API (Webhooks)


message (with media/attachment))

None

Receive API (Webhooks)


message_echoes

None

Receive API (Webhooks)

messaging_optins

None

Receive API (Webhooks)

messaging_referrals

messaging_referrals webhook for m.me link and Chat Plugin will be operational. CTM ads messaging_referrals webhook restoration is TBD.

Send API

Text

None

Send API

Media/attachment (image, audio, video, files)

None

Send API

Shops product template

None

Send API

Send API with user_ref

None

Send API

Generic Template, Button Template, Media Template

Video media type is not supported on Media Template. Restoration is TBD.

Send API

URL Button,Postback Button,Call Button

None

Send API

Quick replies

None

Send API

Message Tags

None

Send API

Receipt template

None

Send API

One Time Notification (OTN)

None

Send API

Sender actions

None

Entry Points

m.me link

None

Entry Points

Message us plugin

None

Entry Points

Private replies

None

Entry Points

Chat Plugin

Source attribute in webhooks originating from the Chat Plugin is not included for accounts affected by the regulations in Europe and Japan

Entry Points

Chat Plugin Guest Mode

Source attribute in webhooks originating from the Chat Plugin is not included for accounts affected by the regulations in Europe and Japan

Messenger Profile API

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

None

Conversation API

Conversation API

sticker field will return null.

Handover Protocol

Handover Protocol

None

Handover Protocol

Handover Protocol for ads that click through to Messenger

None

User Profile API

User Profile API

None

Messenger Profile API

Persistent menu

None

Entry Points

Chat Plugin Guest Mode Upgrade

None

Entry Points

Web Plugins (Send to Messenger, Checkbox plugin)

None

Entry Points

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

None

Messenger Feature Review API

Messenger Feature Review API

None

Customer Feedback Template

Customer Feedback Template

None

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 and Japan. 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 ImpactMitigationTargeted Restoration

Send API:


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

TBD

Receive API (Webhooks)


No User Impact

source attribute in webhooks is not included for accounts affected by the regulations in Europe and Japan

N/A

TBD

Receive API (Webhooks): message_deliveries, messaging_account_linking, message_reactions, message_reads


No User Impact

Webhook will not be delivered

N/A

Q2 2021

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

Q2 2021

Account linking:


Account linking

None

Returns an error message

N/A

Q2 2021

ID Matching:


PSID/ASID matching

N/A

Returns an error message

N/A

TBD

Custom Labels:


Custom labels

N/A

Returns an error message

N/A

TBD

Messenger Extensions SDK:


Messenger Extensions SDK

N/A

Affected fields (psid, tid) will be empty

N/A

TBD

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 and Japan.
                 See developer documentation for more info",
      "type":"OAuthException",
      "code":10,
      "error_subcode":2018336,
      "fbtrace_id":"AUmkjfWVra1NAa-qEH5NcI8"
   }
}

Other Fallback Experiences For Developers

Send API - Templates (Receipt, Airline) 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}}"
         }
      ]
   }
}
      

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

CTM HOP in Ads Manager

CTM Ad campaigns that run for impacted pages or for audiences impacted regions will not be able to use CTM HOP. Campaigns that have the CTM HOP App Id JSON setting will run as if CTM HOP is not active (i.e. will be handled by the primary app for the page).

Area: FeatureUser ImpactDeveloper ImpactMitigationTargeted Restoration

CTM HOP in Ads Manager: CTM HOP

A user responding to a CTM Ad will have their thread routed always to the primary receiver on the page.

A user responding to a CTM Ad will have their thread routed always to the primary receiver on the page.

To re-create a similar behavior to CTM HOP, use the following fallback blueprint:

Welcome Message setup in Ads Manager

Primary Receiver app

  • Perform a check for the given payload, and:
  • Use Handover Protocol to send the user to the app responsible for CTM Ad flow

TBD

Mitigation of Edge Cases

Cannot add such a condition to the primary app or don’t have access to changing the primary app

Example
  • If a brand using Provider A for regular messages, and Provider B as the secondary receiver for CTM messages, where Provider A is unable to set the hand-off to Provider B. This would require the Brand to do the routing with their own solution (essentially acting as provider C).
Solution
  • Create a custom app to be a “router app” and assign it as the new primary app for the page
  • The router app will route all threads that receive the payload to the CTM ad flow app
  • The router app will route al other threads to the default app fo the page (the previous Primary App)

User enters free text instead of clicking on the quick reply or generic template button

Solution #1
  • Determine or estimate percentage of users entering free text. If the volume is within your operational limits, consider transferring them to a live agent.
Solution #2
  • Leverage NLU (Natural Language Understanding) to extract an intent from the free text and determine if the user needs to be handover to the CTM Ad Flow
  • The NLU processing can happen either in your Primary App (if the app/vendor/platform supports this) or programmed in the “router app” discussed earlier.
Solution #3
  • Disable by default free text for the page by disabling the composer at the page level as described here
  • In the CTM Ad welcome message, add either a Quick Reply or Generic Template button to “Talk to an agent”
  • In the page’s default welcome message, add a similar option to add either a Quick Reply or Generic Template button to “Talk to an agent”
  • Enable free text entry only for users who click the relevant Quick Reply or Generic Template button by enabling the user level persistent menu as described here