![]() | Conversation Control |
Messenger Platform Handover Protocol Conversation Control shows you how to request control for a Messenger from Meta conversation from another app, pass control to another app, pass metadata about a conversation, and discover the app that currently controls the conversation.
This tutorial assumes that you have:
You will need:
If a conversation is idle, or your app is the Primary Receiver, you can send a POST
request to the /PAGE-ID/take_thread_control
endpoint with the recipient
parameter set to the PSID for the customer who sent the message and the metadata
parameter (optional) set to information about the conversation that should be passed to other apps.
curl -X POST -H "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/take_thread_control ?recipient={id:PSID} &metadata=Information about the conversation &access_token=PAGE_ACCESS_TOKEN"
On success, your app will receive the following:
{ "data": [ { "thread_owner":{ "app_id": APP-ID "expiration":UNIX-TIMESTAMP //Time after which the conversation will return to idle } } ] }
Any apps subscribed to the messaging_handover
Webhooks field will receive the following notification:
{ "sender":{ "id":"PSID" }, "recipient":{ "id":"PAGE-ID" }, "timestamp":UNIX-TIMESTAMP, "take_thread_control":{ "previous_owner_app_id":"PREVIOUS-OWNER-APP-ID", "new_owner_app_id": "NEW-OWNER-APP-ID", "metadata":"Information about the conversation" } }
To give your app more time to respond to a message, you can extend control past the 24-hour response time frame. You can extend the time up to 7 days.
Send a POST
request to the /PAGE-ID/extend_thread_control
endpoint with the recipient
parameter set to the PSID for the customer who sent the message and the duration
parameter set to the length of time in seconds.
curl -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/extend_thread_control ?recipient={id:PSID} &duration=86400 //Length of time, in seconds &access_token=PAGE-ACCESS-TOKEN"
To request control of a conversation from another app, send a POST
request to the /PAGE-ID/request_thread_control
endpoint with the recipient
parameter set to the PSID for the customer who sent the message and the metadata
parameter (optional) set to information about the conversation that should be passed to other apps.
curl -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/request_thread_control ?recipient={id:PSID} &metadata=Information about the conversation &access_token=PAGE-ACCESS-TOKEN"
On success, your app will receive the following:
{ "success": true }
In this instance true
does not mean your app now has control. true
means the API call to send the request was successful.
Any apps subscribed to the messaging_handover
Webhooks field, including the app currently in control, will receive the following notification:
{ "sender":{ "id":"PSID" }, "recipient":{ "id":"PAGE-ID" }, "timestamp":UNIX-TIMESTAMP, "request_thread_control":{ "requested_owner_app_id":"APP-ID-REQUESTING-CONTROL", "metadata":"Information about the conversation" } }
For Messenger experiences that enable live chat via the Page Inbox, the Page admin can request control of a conversation by moving the conversation from Done to Inbox. This will trigger a messaging_handovers
Webhooks which will be sent to the controlling app. Apps should honor the request and pass control to the Page Inbox.
When your app receives a webhook notification requesting control of the conversation from another app, send a POST
request to the /PAGE_ID/pass_thread_control
endpoint with the recipient
parameter set to the PSID for the customer who sent the message, the target_app_id
parameter set to the ID for the app that sent the request, and the metadata
parameter (optional) set to information about the conversation that should be passed to other apps.
curl -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/pass_thread_control ?recipient={id:PSID} &target_app_id=APP-REQUESTING-CONTROL &metadata=Information about the conversation &access_token=PAGE-ACCESS-TOKEN"
On success, your app will receive the following response:
{ "success" : true }
Control of the conversation has been passed to another app.
Any apps subscribed to the messaging-handovers
and standby
webhooks will receive the following notification:
{ "sender":{ "id":"PSID" // The Page-scoped ID for the person who sent the message to the Page }, "recipient":{ "id":"PAGE-ID" }, "timestamp":UNIX-TIMESTAMP, "take_thread_control":{ "previous_owner_app_id":"APP-RELEASING-CONTROL", "new_owner_app_id": APP-TAKING-CONTROL, "metadata":"Information about the conversation" } }
To assign an app as a Primary Receiver, you will need to:
Step 1. Go to your Page Settings.
Step 2. Select Advanced messaging.
Step 3. Click the Configure button under Handover Protocol.
Step 4. Using the dropdown, select the app as your Primary Receiver.
Any apps subscribed to the messaging_handovers
Webhooks will receive the following notification:
{ "recipient":{ "id":"PAGE-ID" // The Page-scoped ID for the person who sent the message to the Page }, "timestamp":UNIX-TIMESTAMP, "app_roles":{ "APP-ID":["APP-NAME"] //The app ID and app name for the app assigned as the Primary Receiver } }
When a conversation is not idle and your app is the Primary Receiver, you can find the app that currently controls the conversation.
Send a GET
request to the /PAGE-ID/thread_owner
endpoint with the recipient
parameter set to the Page-scoped ID for the person who sent the message to the Page.
curl -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/thread_owner ?recipient=PSID &access_token=PAGE-ACCESS-TOKEN"
On success, your app will receive the following:
{ "data": [ { "thread_owner":{ "app_id": APP-ID "expiration":UNIX-TIMESTAMP //Time when the conversation will return to idle } } ] }
Note: If the conversation is idle, the response will be an empty dataset.