Passing Thread Control

The Pass Thread Control API of the handover protocol is used to pass control of a conversation from one app to another. The calling app can pass optional metadata to the receiving app in the API request. When thread control is passed to an app, the pass_thread_control webhook event will be sent to that app's webhook.

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/v11.0/me/pass_thread_control?access_token=<PAGE_ACCESS_TOKEN>"

Example `pass_thread_control` Event

{
  "sender":{
    "id":"<PSID>"
  },
  "recipient":{
    "id":"<PAGE_ID>"
  },
  "timestamp":1458692752478,
  "pass_thread_control":{
    "new_owner_app_id":"123456789",
    "metadata":"Additional content that the caller wants to set"
  }
}

Passing Thread Control to the Page Inbox (Live Chat)

The handover protocol can be used to pass thread control from the Primary Receiver app to your Page inbox. This allows you to offer live chat by replying to messages sent to the Page inbox, and is also useful as a fallback if your bot is unable to understand a message.

To enable live chat via the Page inbox, do the following:

Assign the Secondary Receiver role to your Page inbox.
From the Primary Receiver app, pass thread control to the Page inbox by setting the target_app_id property of the request to 263902037430900.

When the Page inbox is assigned the Secondary Receiver role, all messages sent to your bot will appear in the 'Done' folder by default. When the Page inbox has control of the conversation, all messages from the conversation will be moved to the 'Inbox' folder.

Returning Control From the Page Inbox to the Primary Receiver

To return control of the conversation to the Primary Receiver, click the 'Done' checkmark for the conversation.

Requesting Thread Control From the Page Inbox