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.

Note: Conversation Routing is now available, and will soon replace Handover Protocol. You should update your app to use Conversation Routing as soon as possible.

How It Works

A Facebook Page or an Instagram Professional account can use multiple messaging apps to communicate with customers or people interested in their content. 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 or Instagram 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 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.

If an app that is not in control of the conversation tries to send a message to a person, a 400 error will be returned with error subcode 2018300.

Primary Receiver

If you want messages to be handled by a specific app upon receipt, you can assign that app as the Primary Receiver. The Primary Receiver receives all new messages for a conversation, can transfer control to another app or Facebook Page Inbox or Instagram 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, the conversation is set to idle.

If a conversation is idle and a person sends a new message to your Page or account, the Primary Receiver has control of the conversation and receives a webhook notification about the new message.

Note: Setting a Primary Receiver is not required.

Inbox

A Facebook Page Inbox or Instagram 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.

App Review

App Review is required for apps that will:

Be used by people who do not have a role on the app
Allow a human agent to respond to customers

Human Agent Feature

An app will be able to send a person a message even if the app is not in control of the conversation if an app has been approved, through App Review, to use the Human Agent feature and the message is tagged with the human agent tag. This is the only scenario in which a message can be sent by an app not in control of the conversation.

Permissions

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

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 or Instagram 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 or Instagram Inbox. Once the conversation is complete in Facebook Page Inbox or Instagram 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 - Ads that Click to Messenger

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.

Best Practices

We recommend automated experiences to be set as the primary receiver app and any live agent app to be the non-primary app. It’s recommended that the live agent app listens to the standby events and not take action unless needed.
Always use the Get Thread Control API to check if you are in control of the thread or not, then call the other APIs based on the scenario. Do not interject or interrupt if you do not have control.
Please ensure that you do not try to send messages to the thread when another app is in control of the conversation. If you are a Primary app please use the take thread control API only if you see the need to. In non-urgent cases or if you are a non-primary app please request thread control.
Ensure that you honor a request thread control event from any other app in all cases possible and pass thread control to the requesting app. If for any reason you are unable to pass thread control immediately, use the Pass Metadata API to send additional context to the requesting app and maintain a queue to pass thread control when you are done.
If you are done with the conversation, please pass thread control to a previously requesting app still in queue or release thread control to idle, so that any other app can pick up the thread. Not doing so, would result in the thread automatically releasing from your app and going to idle mode after 24 hours. Code this scenario and its associated state changes accordingly.
If you notice the thread to be idle by calling the Get Thread Control API, use Request Thread Control to take control of the thread so that you can exclusively message the user without disruptions and release once done.

Learn more

Learn more about the components of the Handover Protocol.

Next Steps

Now that you know how the Handover Protocol works, to implement the protocol you will need to: