Conversation Control |
Messenger Platform Handover Protocol Conversation Control shows you how to request control of a conversation from another app, pass control to another app, pass metadata about a conversation to another app, and determine which app currently controls a conversation.
This guide assumes you have read the Messenger Platform Overview and implemented the needed components for sending and receiving messages and notifications.
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 ID for the person 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:ID} &metadata=Information about the conversation &access_token=PAGE_ACCESS_TOKEN"
On success, your app will receive a JSON object containing the app ID of the thread owner and the time at which the conversation will return to idle.
{ "data": [ { "thread_owner":{ "app_id": APP-ID "expiration":UNIX-TIMESTAMP } } ] }
Any apps subscribed to the messaging_handover
Webhooks field will receive a notification with the ID for the person who sent the message, the ID for the Facebook Page or Instagram Professional account that received the message, the ID for the previous app that controlled the conversation, the ID for the app that now controls the conversation, and any metadata about the conversation that was sent in the API request that triggered the webhook.
{ "sender":{ "id":"ID" }, "recipient":{ "id":"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.
To extend control of the conversation, 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"
We recommend releasing control of the conversation, returning it to idle, as soon as the app is finished with its flow instead of waiting for the response time to expire.
To release control of a conversation, send a POST
request to the /PAGE-ID/release_thread_control
endpoint with the recipient
parameter set to the PSID for the customer who sent the message and any pertinent information using the metadata
parameter.
curl -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/release_thread_control ?recipient={id:PSID} &metadata=Information about the conversation &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 or Instagram 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 is getting control, and the metadata
parameter (optional) set to information about the conversation that should be passed to other apps.
Note: To pass control to an Inbox, set the target_app_id
to 263902037430900
for the Page Inbox and 1217981644879628
for the Instagram Inbox.
target_app_id
is required or the call will failcurl -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/pass_thread_control ?recipient={id:PSID} &target_app_id=APP-GETTING-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.
Upon success the target app will receive the messaging-handovers
webhooks 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, "pass_thread_control":{ "previous_owner_app_id":"APP-RELEASING-CONTROL", "new_owner_app_id": APP-GETTING-CONTROL, "metadata":"Information about the conversation" } }
For messaging flows that requiring sharing information between apps without changing control of the conversation, you can send a POST
request that will trigger the messaging_handovers
webhook and send a notification to all apps that are connected to your Page.
There may be scenarios where apps may need to pass additional data to other apps connected to the page without passing or taking thread control. For example, a customer service messaging experience may have two apps connected to a business Page. One app is an automated app that can respond to simple inquiries and one app is a customer service app with human agents that can respond to complex inquires. If the support agent updates the status of the case or needs to transfer the case to another department, the customer service app might want to pass this information to the automation app without passing control to the automation app. This passing of information allows the automation app to pass status updates, such as wait times, case status, and more, to the customer.
To share information about the conversation without changing conversation control, send a POST
request to the /PAGE-ID/pass_thread_metadata
endpoint with the recipient
parameter set to the PSID for the customer who sent the message to your business, the target_app_id
parameter set to the ID for the app that will be receiving the metadata, and the metadata
parameter set to the information that needs to be passed.
curl -i -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/pass_thread_metadata ?recipient={ id: PSID } &target_app_id=123456789 &metadata=additional content that the caller wants to set &access_token=PAGE-ACCESS-TOKEN"
Upon success of the POST
call, the target app will receive the messaging_handovers
webhooks notification.
{ "sender":{ "id":"PSID" // The PSID for the customer who sent the message to your business }, "recipient":{ "id":"PAGE-ID" // The ID for the Page for your business }, "timestamp":1458692752478, "pass_metadata":{ "caller_app_id":123456789, "metadata":"additional content that the caller wants to set" } }
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.