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 a complete API reference, see Pass Thread Control API Reference.

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 take_thread_control webhook event when it loses thread control.

For a complete API reference, see Take Thread Control API Reference.

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>"

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 a complete API reference, see Secondary Receivers List API Reference.

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>"