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.
The flow for using the Request Thread Control API looks like this:
The Secondary Receiver app calls /request_thread_control
The Primary Receiver app receives a messaging_handovers webhook event with the request_thread_control
property.
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.
The Primary Receiver calls pass_thread_control
to pass control to the Secondary Receiver that called /request_thread_control
.
The Secondary Receiver app is given control of the chat, and receives a messaging_handovers with the pass_thread_control
property.
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>"
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"
}
}
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.