Handover Protocol

The Messenger Platform Handover Protocol enables two or more apps to participate in a conversation by passing control of the conversation between them. Apps subscribed to by a Facebook Page automatically have Handover Protocol enabled.

How It Works

A Facebook Page can use multiple messaging apps to communicate with customers. For example, for customer support customers can be sent to an automated experience but if the automated experience is unable solve the customer's issue, the customer can be sent to another app with live support agents. To transfer the conversation, and metadata about the conversation, from one app to another, or between an app and a Facebook Page Inbox, control of the conversation must pass from one app to the other. The Handover Protocol enables this transfer.

By default, when a customer sends a message to start a conversation, the conversation is idle. Apps will receive a notification, via Webhooks, that a message has been received and is waiting for a response. In order to receive this notification an app needs to be subscribed to the handover specific Webhooks.

Any app can take control of the conversation while the conversation is idle. The app in control of the conversation has the exclusive ability to respond to the message. Only one app has control at a time and other apps are not be able to send a message until the controlling app releases control. Once an app releases control, the conversation returns to idle, and then the next app can take control.

For the app that controls the conversation, the app will receive notifications from the messaging webhooks. All other apps will receive notifications from the handover specific webhooks.

A conversation will automatically return to idle when it has received no activity for 24 hours. A controlling app may extend control past 24 hours if needed.

Primary Receiver

If you want messages to be handled by a specific app upon receipt, you can assign app as the Primary Receiver. The Primary Receiver receives all new message conversations for a conversation, can transfer control to another app or Facebook Page Inbox, and can take control of a conversation from another app, if necessary. When a non-Primary Receiver app is finished with the conversation, and releases control, control returns to the Primary Receiver app.

If a Primary Receiver app is set, the primary app will receive messaging webhooks notifications, via the messaging Webhooks, that a message has been received and is waiting for a response. All other apps will receive standby webhooks notifications.

Note: Setting a Primary Receiver is not required.

Page Inbox

A Facebook Page Inbox can not be assigned as a Primary Receiver. However, if you move the message to the Main folder or respond to a message in a conversation not controlled by the inbox, the inbox takes control of the conversation. If you respond to a message that is marked as Done in the inbox, control remains with the previous controlling app, the Primary Receiver, if set, or is released to idle.

Conversation Entry Points

A conversation can be assigned to a specific app when using a Click to Messenger (CTM) conversation entry point. A business can use a CTM to start conversations with customers to generate leads, raise brand awareness, and more.

Persistent Menu

Any app can set the Page level menu unless a Primary Receiver has been set. If a primary app has been set, only the primary app will be able to set or delete a Page level menu.

The app in control of the conversation can set or delete User level menu even if the app is not the Primary Receiver, and any app can set user level menu when the conversation is idle.

When a customer selects an item from a menu, the app that created the menu will get control of conversation. This is done since the app that created the menu is configured to handle that data.

Postback Call-To-Action

When a customer clicks a Postback Call-To-Action (CTA), the app that created the postback CTA will get control of the conversation even if another app had control. This is done since the app that created the postback CTA is configured to handle that data.

Customer Surveys

If a survey is sent while another app controls the conversation it will not be delivered until the app releases control and the conversation is idle.

Components

The following components are needed to successfully implement Handover Protocol for messaging apps that your Facebook Page has subscribed to.

Access Tokens

A Page access token requested by a person who can perform the MODERATE task on the Page is needed for calls to the Handover Protocol endpoints.

Permissions

The pages_messaging permission is required for apps to ask customers for permission to access messaging data.

Human Agent Feature

If an app has been approved through App Review to use the Human Agent feature, the app will be able to take control of the conversation when necessary as long as the message sent to the customer includes the human agent tag. For all other message tags, a message will not be delivered if another app is in control. One of the common use cases for this is when the customer is stuck in a conversation with an automated app and the agent needs to intervene.

App Review

App Review is required for apps that will:

  • Access data owned by people who do not have a role on the app
  • need the Human Agent feature to allow a live agent to respond to customers

Webhooks

In the Handover Protocol there are two sets of webhooks an app should subscribe to, the messaging webhooks and the standby webhooks. The notifications that an app receives are dependent on conversation control. If an app is in control of a conversation, the app receives the messaging webhooks notifications. If an app is not in control of the conversation, the app receives the standby webhooks notifications.

Common Uses

Customer Support

A business uses one app for automated experiences for frequently asked questions but transfers the customer to another app for live support if the automated experience does not solve the customer's issue. The automated app is set as the Primary Receiver so all conversations are owned by the automated app. When a live support agent needs to join the conversation, the live support app can request conversation control. Once live agent app has completed the conversation, conversation control is released back to the automation app. If the live agent app needs more time to handle a customer's issue, the app can request an extension. Both apps should subscribe to the webhooks to ensure the conversation flows properly.

Marketing Campaign - Product Leads

A business runs a marketing campaign and uses an automated experience to qualify leads or provide product recommendations based on a product quiz. After the lead qualification, the business uses the Facebook Page Inbox to follow up with the prospective customers. The automated app is set as the Primary Receiver so all conversations are owned by the automated app. Once the automated app has completed the lead qualification phase, conversation control is passed to the Facebook Page Inbox. Once the conversation is complete in Facebook Page Inbox, mark the conversation as Done. This will release the conversation control to primary app. Both apps should subscribe to the webhooks to ensure the conversation flows properly.

Marketing Campaign - Click to Messenger Ads

A business runs a marketing campaign and sends prospective customers to an automated app for a specific Messenger experience. The automated app is set as the Primary Receiver so all conversations are owned by the automated app. When a live support agent needs to join the conversation, the live support app can request conversation control. Once live agent app has completed the conversation, conversation control is released back to the automation app. If the live agent app needs more time to handle a customer's issue, the app can request an extension. Both apps should subscribe to the webhooks to ensure the conversation flows properly.

Recommendations

We recommend the following:

  • Assign apps that have an automated experience to be the Primary Receiver. These apps can field some of the initial inquiries from customers before transferring them to a human agent.
  • Set live agent apps to monitor webhooks notifications and take action only when necessary. Misuse of this feature can result in policy enforcement.
  • Send messages to a conversation only if the app controls the conversation.
  • Take control of the conversation before sending a message.
  • Always pass conversation control to a requesting app. If for any reason you are unable to pass conversation control immediately, send additional context to the requesting app and maintain a queue to pass conversation control when you are done.
  • Always return conversation control to the previous app or to idle to allow other apps to take control of the conversation.
  • Take control of an idle conversation to provide a seemless customer conversation experience.