Messenger Platform

Request Thread Control

When using the handover protocol, only the Primary Receiver app is allowed to take control of the conversation by calling take_thread_control. There may be times, however, when it is necessary for a Secondary Receiver app to take control of the conversation.

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.

How it Works

The flow for using the Request Thread Control API looks like this:

  1. The Secondary Receiver app calls /request_thread_control

  2. The Primary Receiver app receives a messaging_handovers webhook event with the request_thread_control property.

  3. If an app other than the Primary Receiver currently has control of the chat, the Primary Receiver calls /take_thread_control to take control of the chat.

  4. The Primary Receiver calls pass_thread_control to pass control to the Secondary Receiver that called /request_thread_control.

  5. The Secondary Receiver app is given control of the chat, and receives a messaging_handovers with the pass_thread_control property.

Example Request

For complete API details and request properties, see the Request Thread Control Reference.

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

Example messaging_handovers Event

{
  "sender":{
    "id":"<USER_ID>"
  },
  "recipient":{
    "id":"<PSID>"
  },
  "timestamp":1458692752478,
  "request_thread_control":{
    "requested_owner_app_id":123456789,
    "metadata":"additional content that the caller wants to set"
  }
}

Requesting Thread Control From the Page Inbox

For Messenger experiences that enable live chat via the Page Inbox, the handover protocol allows the Page admin to manually initiate a request thread control messaging_handovers event by moving the conversation from 'Done' to the 'Inbox'.

It is important that the Primary Receiver app honor the request thread control event and pass control to the Page Inbox. If thread control is not passed to the Page Inbox, the conversation will be returned to 'Done' on page refresh or when a new message is sent or received by the bot.