Handover Protocol API Reference

To use the Handover Protocol, the Graph API version should be set to 2.6 or greater.

The handover protocol enables two or more applications to collaborate on the Messenger Platform for a Page by passing control of the conversation (thread) between Primary Receiver and Secondary Receiver apps.

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.

For usage details, see Handover Protocol.

Contents

Base URI

https://graph.facebook.com/v2.6/me

Pass Thread Control

Passes thread control from one app to another. The app that will receive thread ownership will receive a pass_thread_control webhook event.

For complete usage details, see Pass Thread Control.

Path

POST /pass_thread_control?access_token=<PAGE_ACCESS_TOKEN>

Example Request

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{"id":"<PSID>"},
  "target_app_id":123456789,
  "metadata":"String to pass to secondary receiver app" 
}' "https://graph.facebook.com/v2.6/me/pass_thread_control?access_token=<PAGE_ACCESS_TOKEN>"

Take Thread Control

Allows the Primary Receiver app to take control of a thread from a Secondary Receiver app. The Secondary Receiver app will receive a messaging_handovers webhook event when it loses thread control.

For complete usage details, see Take Thread Control.

Path

POST /take_thread_control?access_token=<PAGE_ACCESS_TOKEN>

Example Request

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{"id":"<PSID>"},
  "metadata":"String to pass to the secondary receiver" 
}' "https://graph.facebook.com/v2.6/me/take_thread_control?access_token=<PAGE_ACCESS_TOKEN>"

Request Thread Control

Allows the Primary Receiver app to take control of a thread from a Secondary Receiver app. The Secondary Receiver app will receive a messaging_handovers webhook event when it loses thread control.

For complete usage details, see Request Thread Control.

Path

POST /request_thread_control?access_token=<PAGE_ACCESS_TOKEN>

Example Request

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{"id":"<PSID>"},
  "metadata":"additional content that the caller wants to set" 
}' "https://graph.facebook.com/v2.6/me/request_thread_control?access_token=<PAGE_ACCESS_TOKEN>"

Secondary Receivers List

Allows the Primary Receiver app to retrieve the list of apps that are Secondary Receivers for a page. Only the app with the Primary Receiver role for the page may use this API.

For complete usage details, see Retrieving the List of Secondary Receivers.

Path

GET /secondary_receivers?access_token=<PAGE_ACCESS_TOKEN>

Example Request

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

Thread Owner

Allows Primary Receiver and Secondary Receiver apps to retrieve the app ID of the app that currently has thread control.

For complete usage details, see Get Thread Owner.

Path

GET /thread_owner?recipient=<PSID>&access_token=<PAGE_ACCESS_TOKEN>

Example Request

curl -X GET "https://graph.facebook.com/v2.6/me/thread_owner?recipient=<PSID>&access_token=<PAGE_ACCESS_TOKEN>"

Example Response

{
  "data": [ 
    {
      "thread_owner":{
        "app_id": <APP_ID>
       }
    }
  ]
}