Handover Protocol

The Messenger Platform's handover protocol enables two or more Facebook apps to participate in a conversation by passing control of the conversation between them. This feature can be used in many ways to enrich your Messenger experience. For example, this protocol makes it possible for a Page to simultaneously use one Facebook app to build a bot for handling automated responses, and another Facebook app for customer service with live agents.

By default, all messages are sent to the Primary Receiver app. When control of the conversation is passed to another, the Messenger Platform will send messages from the conversation to it instead. Only one app may control the conversation at a time. All apps that do not have control of the conversation, may continue to listen to the conversation by subscribing to the standby webhook event.

Contents

• Requirements
• Using the Handover Protocol
• Allowed Actions By App Role
• Enabling the Handover Protocol (App Roles)
• Passing Thread Control
• Taking Thread Control
• Requesting Thread Control
• Enabling Live Chat via the Page Inbox
• Retrieving the List of Secondary Receivers
• Webhook Events
  • messaging_handovers
  • standby

Requirements

To use the handover protocol, you must assign only one app the Primary Receiver role and at least one app the Secondary Receiver role in your Facebook Page settings.

Using the Handover Protocol

To familiarize you with the handover protocol, the following is an example you can follow to familiarize yourself with how the protocol works:

1. Subscribe apps to your Page: Subscribe two Facebook apps to receive webhook events for your Facebook Page in the Messenger section of their app settings.

2. Activate the handover protocol: In Page settings > Advance Messaging, assign one Facebook app the Primary Receiver role and the other the Secondary Receiver role. Each app will receive a messaging_handovers webhook event that includes an app_roles property that notifies it of whether it is now a Primary Receiver or Secondary Receiver. Typically, the Primary Receiver would be a bot that can respond to most incoming messages automatically, and the Secondary Receiver would route to chat with a live agent or be a specialized app for handling certain request types.

3. Subscribe to webhook events: Subscribe each app to receive the messages and standby webhook events for your Page.

4. Send a message: Send a message to your Page. If you are logging incoming events in your webhook, you should see a messages event received by the Primary Receiver app, and a standby event receiver by the Secondary Receiver. By default, when a user first interacts with your bot, the Primary Receiver app has control of the conversation, which means it is responsible for either handling and responding to any incoming messages, or passing control to a different app.

5. Pass thread control: At some point in the conversation, a user may choose to do something like interact with a live agent. To handle this, pass thread control from the Primary Receiver to the Secondary Receiver. The Secondary Receiver will receive a messaging_handovers webhook event to notify it that is now controls the conversation.

6. Send a message: Now the the Secondary Receiver has control of the conversation, it will now receive a messages event, and the Primary Receiver will receive a standby event.

7. Take thread control: From the Primary Receiver app, call the Take Thread Control API to return control of the conversation back to the Primary Receiver. Only the Primary Receiver can take thread control.

8. Send a message: The Primary Receiver app now holds the thread control, so it will receive a messages event, and the Secondary Receiver will receive a standby event.

Allowed Actions By App Role

The handover protocol actions an app is allowed to initiate depends on its app role. The following is a summary of the available actions by role. For more information and usage details on each handover protocol action, see below.

Enabling the Handover Protocol (App Roles)

To activate the handover protocol, it is required for a Page to have only one app 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.

Learn More →

Passing Thread Control

The Pass Thread Control API is used to pass control of a conversation between apps. 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.

You can also enable live chat in your bot by passing thread control directly to the Page inbox.

Taking Thread Control

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.

Requesting Thread Control

The Request Thread Control API allows a Secondary Receiver app to notify the Primary Receiver that it wants control of the chat. The Primary Receiver can then take control of the chat if necessary, then pass control to the Secondary Receiver that sent the request. An optional metadata string may also be sent in the request.

The Primary Receiver may also ignore the request, and do nothing.

Enabling Live Chat via the Page Inbox

Building bots that are able to respond to every possible message is extremely difficult. Due to this, it is often desirable to be able to route the conversation to a real person.

To enable this, the handover protocol allows you to pass control of the conversation to the Page inbox, where you can manually respond to messages when needed. This is an ideal fallback to implement for cases when your bot is unable or does not understand how to respond to a message.

Retrieving the List of Secondary Receivers

To programmatically retrieve the list of apps with the Secondary Receiver role for your Page, send a GET request to the Messenger Platform with the page token of the Primary Receiver app:

curl -X GET "https://graph.facebook.com/v2.6/me/secondary_receivers?fields=id,name&access_token=<PAGE_ACCESS_TOKEN>"

The Messenger Platform will respond with a list of apps that have the Secondary Receiver role for your page:

{
  "data":[
    {
      "id":"12345678910",
      "name":"David's Composer"
    },
    {
      "id":"23456789101",
      "name":"Messenger Rocks"
    }
  ]
}

For complete API details and request properties, see Secondary Receivers List API Reference.

Webhook Events

To help you manage your use of the handover protocol and track when control of the conversation is passed between Facebook apps, the Messenger Platform offers the following set of specialized webhook events.

messaging_handovers

The messaging_handovers webhook event is sent to the webhook associated with a Facebook app any time one of the following handover protocol actions is taken on that app:

• Thread control is passed to the app
• Thread control is taken from the app
• App role is changed

For complete details and event properties, see the messaging_handovers Webhook Event Reference

standby

When the handover protocol is set up for a Page, apps that don't have the thread control at the time can optionally subscribe to a separate 'standby' channel to listen to incoming messages. It is important to implement the standby channel, as it allows apps to track the full context of the conversation and be well-informed on how to proceed if control is passed to them.

This webhook event only affects messages, message_reads, and message_deliveries subscriptions.

For complete details and event properties, see the standby Webhook Event Reference