Facebook Handover Protocol


Although some Facebook pages may fully automate their Messenger conversations through Flow XO, many (if not most) will also need human participation in at least some scenarios, either because the bot has determined that the current user requires human assistance, or the administrator of the page has noticed a user struggling with an automated conversation and wants to jump in.

While Flow XO has a built-in Live Chat feature which can satisfy these scenarios, many Facebook Page operators may prefer to work directly within the Facebook Inbox to communicate with customers, rather than the Flow XO Live Chat interface.

Additionally, by default, automated conversations appear in the Main folder of the Facebook Inbox, and can overwhelm a page administrator with new messages that, because they are automated, do not require human attention at every phase of the conversation.

To address these issues Facebook provides a 'Handover API' which allows a page admin to configure one or more 'secondary' apps that can request or be given control of any given Messenger conversation thread. This API is designed to allow custom apps to fulfill this role but also exposes the Facebook Inbox as a potential secondary app, which can provide a much cleaner, more streamlined way for Facebook page admins to manage Messenger conversations that need human intervention.

When a secondary app is configured in the Advanced Messaging section of a Facebook Page's settings, messages to and from Flow XO will appear directly in the Page Inbox's Done folder, and not clutter the Main Inbox, unless control is explicitly passed to the Inbox for a specific user.

In general, here's how the handover protocol works. In the diagram, we are assuming the configured secondary app is the Facebook Inbox, but this could be an alternative app as well in advanced scenarios.

Configuring the Handover Protocol

Enabling the Handover Protocol with Flow XO is very simple. The first step is to configure the Facebook Page with Flow XO as the Primary App, and either the Page Inbox or another secondary application as the Secondary App. This setting is found in Page Settings -> Advanced Messaging.


NOTE: If you just want to enable Scenario 1 and 2 above, where conversation control is entirely managed manually by the page admin by moving conversations in between Done and Main, then no further action is necessary. Flow XO will automatically comply with any requests to take or return control of a conversation. 

If you want Flow XO to transfer or take control of a conversation using workflow steps, you'll need to use some custom Facebook Messenger commands. You can access these tools under More Services -> Messenger Actions when adding a new task to your flow.

Transfering Conversation Control to a Secondary App / Page Inbox

To tell Flow XO to transfer control of a conversation to a secondary app, you will need to use a Messenger Actions command Send to Inbox to transfer control to the Page Inbox, or Give Thread Control along with the App ID of the secondary app to pass control to.

 If you wanted to transfer control to another app configured as a secondary on the Page Settings, instead of inbox use the numeric App ID, which can be found in Page Settings:

Taking Control from a Secondary App / Page Inbox

Taking control of a conversation is very similar to passing control - you will need to use a Take Thread Control. There is no need to specify an App ID or 'inbox' when taking thread control because Flow XO will take control from whatever app currently has control, regardless of which app that is:

And that's all there is to it! Whether you just want to prevent automated conversations from cluttering the Inbox or you want to implement a full-featured human handoff using another third-party app, you should be able to accomplish those goals with these simple tools.

Sending Additional Information to the Secondary App

The Facebook handover protocol provides a mechanism to pass custom information to the secondary app when transferring or taking control, in the form of a 'metadata' field. This is a piece of text that the receiving app will know how to interpret, such as an agent queue category or a reason for taking back control. To pass metadata to the secondary app, add a 'metadata' key to the metadata of your request, like so:

This field will work in both the Give Thread Control and Take Thread Control scenarios.


Please see the following link for the official Facebook documentation of the handover protocol: https://developers.facebook.com/docs/messenger-platform/handover-protocol/

Still need help? Contact Us Contact Us