Handover Protocol (beta)
The Messenger Platform handover protocol enables two or more applications to collaborate on the Messenger Platform for a Page. Page admins can enable this feature by configuring roles for the Page's subscribed applications to pass control of a messaging thread from one to another. Messages are delivered to different channels based on whether the application has messaging thread control at the time.
For example, this protocol makes it possible for a page to simultaneously use one application for automated responses and another application for customer service with live agents, without the two interfering with each other.
To allow applications to collaborate and handle messages for the same Page, page admin can set up roles for subscribed applications under Page Settings > Messenger Platform > Subscribed Apps > Role.
To activate the handover protocol, it is required for a page to have one
Primary Receiver, and at least one
Secondary Receiver application role. Once it's configured, messages can be delivered to the application based on one receiver holding a thread control at a time. To begin, a thread control is held by the
Primary Receiver application. Thread control can then be handed over from the
Primary Receiver app to a
Secondary Receiver app using the Pass Thread Control API.
For example, a common use case that involves passing a thread control from one application to another is between an automatic chat and a live chat application. A typical flow would look like this:
The application that can automatically handle user messages is assigned as the
Primary Receiver, while the live chat application is assigned as the
Secondary Receiver. Both applications receive app_role webhook notifications about the role they play in a conversation. The
Primary Receiverapp can also get the list of
Secondary Receiverapps for the page via the Secondary Receivers List.
When a user starts interacting with the page, the
Primary Receiverapp gets the thread control by default, which means it is responsible for handling any incoming user messages.
At some point in the conversation, a user may choose to interact with a live agent. To handle this, the
Primary Receiverapp passes the thread control to the designated
Secondary Receiverapp by making a call to the Pass Thread Control API. The
Secondary Receiverapp gets notified through the pass_thread_control webhook event.
Secondary Receiverapp has access to the standby channel, it can listen to all the messages between the
Primary Receiverapp and the user. This allows the
Secondary Receiverto have the full context of the conversation, and be well-informed on how to proceed with the conversation.
Primary Receiveralso has access to this channel, so it can receive messages exchanged between the user and
Secondary Receiverwhile it does not possess the thread control.
Secondary Receiverapp finishes responding to the user's request, it makes a call to the Pass Thread Control API. The
Primary Receiverapp, gets notified through the pass_thread_control webhook event that it shall gain back the thread control and be responsible for handling messages from the user. The
Primary Receiverapp can call the Take Thread Control API if the
Secondary Receiverapp takes too long to respond or is unresponsive.
Primary Receiverapp now holds the thread control. When a user sends a message to the page, it now gets handled by the automatic chat app again.
Once application roles are configured, the normal
messaging channel should only be active for the application holding the thread control. Other applications may optionally subscribe to the standby channel to listen to incoming messages.
To avoid breaking any bot experience in a way we may not anticipate, please note that either app may respond to messages with the handover protocol.
App Roles Setup
To activate the handover protocol, it is required for a Page to have only one application with the
Primary Receiver role and at least one with the
Secondary Receiver role assigned. By default, the
Primary Receiver app gets the thread control to handle incoming user messages.
A Page admin can setup roles for subscribed applications under Page Settings > Messenger Platform > Subscribed Apps > Role.
When an application's role is changed in Page Settings, the affected application will be notified of the change via the app_role webhook notification.
Secondary Receivers List
The Secondary Receivers List API returns a list of all applications and their roles for a Page. This allows an application to act accordingly in responding to incoming messages.
Primary Receiver application has permission to call this API.
Pass Thread Control API
The Pass Thread Control API is used to pass control of a messaging thread from one application to another. The calling app can pass optional metadata along with the API request. When thread control is passed to an app, the
pass_thread_control webhook event will be sent to this app along with any optional metadata.
Primary Receiver and
Secondary Receiver apps can use this API to pass the thread control.
Take Thread Control API
Take Thread Control API allows the
Primary Receiver app to take control of a messaging thread from the
Secondary Receiver app if it takes too long for the
Secondary Receiver to respond or it's unresponsive.
Primary Receiver app has permission to call this API.
When the handover protocol is set up for a Page, applications that don't have the thread control at the time can optionally subscribe to a separate
standby channel to listen to incoming messages. This new webhook field only affects
Support Live Chat Using the Page Inbox
Please note that you can leverage the handover protocol to supplement your bot experience with live chat through the Facebook page inbox. To do this, you can simply set up the Facebook page inbox as your
Secondary Receiver app, and have your
Primary Receiver app passing the thread control to the Facebook page inbox, which has the app id under
263902037430900. Once the page inbox app is set to be the
Secondary Receiver app, all messages will go to the
Done folder by default.
Primary Receiver can choose to pass control to the page inbox by calling pass_thread_control, which then surfaces the thread from
Inbox. If the page admin finishes handling the conversation, he/she can transfer the thread control back to the
Primary Receiver app by clicking on the Done check mark for this conversation. This will trigger a pass_thread_control from page inbox app to pass control back to the
Primary Receiver app.
Unfortunately, handover protocol is supported in the latest version of page inbox only. We’re still working to gradually migrate Pages at various scale from previous version of page inbox to the new one in this year.