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.

Contents

Overview

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:

  1. 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 Receiver app can also get the list of Secondary Receiver apps for the page via the Secondary Receivers List.

  2. When a user starts interacting with the page, the Primary Receiver app gets the thread control by default, which means it is responsible for handling any incoming user messages.

  3. At some point in the conversation, a user may choose to interact with a live agent. To handle this, the Primary Receiver app passes the thread control to the designated Secondary Receiver app by making a call to the Pass Thread Control API. The Secondary Receiver app gets notified through the pass_thread_control webhook event.

  4. Since the Secondary Receiver app has access to the standby channel, it can listen to all the messages between the Primary Receiver app and the user. This allows the Secondary Receiver to have the full context of the conversation, and be well-informed on how to proceed with the conversation. Primary Receiver also has access to this channel, so it can receive messages exchanged between the user and Secondary Receiver while it does not possess the thread control.

  5. When the Secondary Receiver app finishes responding to the user's request, it makes a call to the Pass Thread Control API. The Primary Receiver app, 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 Receiver app can call the Take Thread Control API if the Secondary Receiver app takes too long to respond or is unresponsive.

  6. The Primary Receiver app 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.

Learn More →

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.

Only the Primary Receiver application has permission to call this API.

Learn More →

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.

Both Primary Receiver and Secondary Receiver apps can use this API to pass the thread control.

Learn More →

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.

Only the Primary Receiver app has permission to call this API.

Learn More →

Standby Channel

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 message, read, and delivery subscriptions.

Learn More →

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 Done to 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.