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.
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
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.
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.
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.
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.
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.
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.
The following components are needed to successfully implement Handover Protocol for messaging apps that your Facebook Page has subscribed to.
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 is required for apps that will:
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.
pages_messaging permission is required for apps to ask customers for permission to access messaging data.
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.
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.
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.
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.
Now that you know how the Handover Protocol works, to implement the protocol you will need to: