Note: Pages configured to use Conversation Routing will not be able to use most Handover Protocol APIs. If your Page has a Default App for Conversation Routing and also attempts to use the Handover Protocol APIs, you will receive an error stating "Handover Protocol APIs disabled for this page."
At this time, you can still use the Handover Protocol API to pass and release thread control, but you should update your app to use the Send API as soon as possible. See Thread Control on this page for more information.
Conversation Routing allows Meta to route conversations between your business and customers, or prospective customers, to the app that you have specified to respond in the conversation. This routing allows your business to create rich conversations with people and to minimize API calls to Meta's servers.
This document shows you how to configure your apps for Conversation Routing.
The conversation entry point determines which app Meta routes the conversation to when your business uses Conversation Routing.
When a person taps your ad and starts a conversation, Meta routes the conversation to the marketing app, the app that handles responses to your ad, and sends Meta Webhooks notifications about the conversation. This process allows the marketing app to get information about the conversation without additional API calls to Meta servers. If the conversation requires more attention after the marketing app handles the action taken in your ad, Meta routes the conversation to the default app and sends webhooks notifications. If the conversation is completed by the marketing app, the app releases the conversation and the conversation is routed to the default app. When the marketing app releases a conversation no webhooks notifications are sent.
When a person enters a conversation via any other entry point, Meta routes the conversation to the default app and sends webhooks notifications about the conversation.
Your default app should handle conversations started via any entry point except Click to Message (CTM) ad campaigns. When a person starts a conversation with your Page from a non-CTM entry point, or the marketing app passes or releases control of a conversation, or a user sends a message after the standard 24 hour messaging window, Meta routes the conversation to this app.
Your marketing app should handle conversations for a specific Click to Message (CTM) ad campaign. When a person taps on a CTM ad, Meta routes the conversation to your marketing app. Once the marketing app has completed the conversation, you send a request to Meta to either release or pass control of the conversation to the default app.
Note: The marketing app should pass or release control to the default app as soon as the app is done with the conversation. This step ensures future conversations are handled by the default app and that these future conversations are not counted towards CTM ad performance.
If a default app is configured for your Facebook Page, the Page can not use Handover Protocol. Conversation Routing doesn't support the following features available in Handover Protocol:
pass_thread_control
and release_thread_control
will continue to work for now. However, this is a temporary feature; access to these APIs will be blocked in the future.En esta guía se da por sentado que has leído la información general sobre la plataforma de Messenger e implementado los componentes necesarios para enviar y recibir mensajes y notificaciones.
Before you can pass conversations between apps, you need the following:
MANAGE
task on a Classic Facebook Page, Facebook access (New Pages Experience) for the Facebook Page, or Full control via the Business Settingsmessages
messaging_referral
messaging_handover
messaging_postbacks
standby
Note: Your default app may need to subscribe to other messaging webhooks depending on other conversation entry points you use.
You can assign a default app in your Facebook Page settings. You may need to login as the Page.
[DEPRECATED] For Classic Pages, go to Settings > Conversation Routing
For New Pages Experience Pages, go to Settings > Page setup > Messenger conversation routing
NOTE: The config to enable your default app to take over a conversation has been deprecated. Instead, you can now grant this ability for each individual connected app in the "Connected apps" section of Advanced messaging.
See Configure apps to take over conversations on this page for more information.
You can assign a marketing app in the Ads Manager during ad creation.
Step 1. Create an ad in the Meta Ads Manager.
Step 2. Navigate to the Message Template > Advanced Setup and tap Edit.
Step 3. Set the receiving_app_id
parameter to the marketing app ID.
Step 4. Publish the ad.
Step 5. Optional but recommended: test Conversation Routing flow by targeting the ad to your test user.
When you assign a Page's default app for Conversation Routing for the first time, all connected apps are automatically subscribed to the Standby webhooks. You can unsubscribe connected apps in your Facebook Page settings.
In the resulting dialog, you can toggle standby access on and off for this app, for both Messenger and Instagram standby webhooks.
You have the option to allow any connected app to send a message even if it's not the current thread owner. Once this ability is enabled for an app, when it sends a message this way, it also receives thread control. This can be useful if the other apps haven't yet been updated to use Conversation Routing and release thread control in a timely manner.
We highly recommend using this feature only for apps that provide human agent support.
To enable/disable this capability for a certain app, go to Page Settings > Page setup > Advanced messaging > Connected Apps. Click Edit next to an app, and toggle "Take control of conversations" on/off.
The following table shows the action that triggered the webhooks and the webhooks notifications sent to each app's webhooks server endpoint.
Possible Actions | Webhooks Notifications Sent to the Marketing App | Webhooks Notifications Sent to the Default App |
---|---|---|
|
|
|
|
|
|
The conversation becomes idle | No webhooks are sent | No webhooks are sent |
The conversation requires further messaging to complete the conversation | No webhooks are sent |
|
The conversation is complete and no further messaging is required | No webhooks are sent | No webhooks are sent |
You can use the Messaging Feature Status API to check the Conversation Routing status of a Facebook Page for Messenger or a business ID for Instagram Direct (IGD) messaging.
curl -X GET "https://graph.facebook.com/v12.0/me?fields=messaging_feature_status&access_token=<ACCESS_TOKEN>"
On success, your app receives the following JSON object.
{ "messaging_feature_status": { "hop_v2": false, "msgr_multi_app": true, "ig_multi_app": false }, "id": "<page_id>" }
An application can pass or release thread control using one of two methods: using the Send API, or using the handover protocol API.
To pass the conversation to the default app, send a POST request to the /PAGE-ID/messages
endpoint with messaging_type
set to RESPONSE
, and the payload
field of the thread_control
parameter to pass_thread_control
.
Currently, this method can only be used to pass control to the default receiver.
curl -X POST -H "Content-Type: application/json" -d '{ "messaging_type": "RESPONSE", "thread_control": { "payload" : "pass_thread_control" }, "recipient": { "id": "<PSID>" }, "message": { "text" : "Let me transfer you to our live agent" } }' "https://graph.facebook.com/v12.0/me/messages?access_token=<ACCESS_TOKEN>"
On success, your app receives the following JSON object with the recipient ID and the message ID.
{ "recipient_id":"<PSID>", "message_id":"MESSAGE-ID" }
To release the conversation, send a POST request to the /PAGE-ID/messages
endpoint with messaging_type
set to RESPONSE
, and the payload
field of the thread_control
parameter to release_thread_control
.
curl -X POST -H "Content-Type: application/json" -d '{ "messaging_type": "RESPONSE", "thread_control": { "payload" : "release_thread_control" }, "recipient": { "id": "<PSID>" }, "message": { "text" : "Thank you for contacting us." } }' "https://graph.facebook.com/v12.0/me/messages?access_token=<ACCESS_TOKEN>"
On success, your app receives the following JSON object with the recipient ID and the message ID.
{ "recipient_id":"<PSID>", "message_id":"MESSAGE-ID" }
Parameter | Description |
---|---|
| Contains the Possible values:
|
app_id
You can pass thread control to a specific app by setting app_id
and control_type
fields in the thread_control
parameter.
curl -X POST -H "Content-Type: application/json" -d '{ "messaging_type": "RESPONSE", "thread_control": { "app_id": "<APPLICATION_ID>", "control_type": "pass" }, "recipient": { "id": "<PSID>" }, "message": { "text" : "Let me transfer you to our live agent" } }' "https://graph.facebook.com/v12.0/me/messages?access_token=<ACCESS_TOKEN>"
On success, your app receives the following JSON object with the recipient ID and the message ID.
{ "recipient_id":"<PSID>", "message_id":"MESSAGE-ID" }
Releasing thread control using this method is similar, but control_type
is set to release
.
curl -X POST -H "Content-Type: application/json" -d '{ "messaging_type": "RESPONSE", "thread_control": { "app_id": "<APPLICATION_ID>", "control_type": "release" }, "recipient": { "id": "<PSID>" }, "message": { "text" : "Thank you for contacting us." } }' "https://graph.facebook.com/v12.0/me/messages?access_token=<ACCESS_TOKEN>"
On success, your app receives the following JSON object with the recipient ID and the message ID.
{ "recipient_id":"<PSID>", "message_id":"MESSAGE-ID" }
Parameter | Description |
---|---|
| Describes who should own the thread.
|
Note: Payload-based and id-based parameters cannot be combined in the same API call. If you set the payload
field, you cannot set the app_id
field, and vice versa.
You can also use the Handover Protocol API to pass and release thread control. Note that not all Handover Protocol thread control APIs are available with Conversation Routing. The following actions are not supported.
To pass control to the default application, use the pass_thread_control
endpoint.
curl -X POST -H "Content-Type: application/json" -d '{ "recipient": { "id": "<PSID>" }, "metadata": "Passing thread control to the default application" }' "https://graph.facebook.com/v12.0/me/pass_thread_control?access_token=<ACCESS_TOKEN>"
On success, your app receives the following JSON object.
{"success: "true"}
To pass thread control to a specific application, rather than the default application, add a target_app_id
parameter to the request payload.
curl -X POST -H "Content-Type: application/json" -d '{ "recipient": { "id": "<PSID>" }, "target_app_id": "<MARKETING_APP_ID>", "metadata": "Passing thread control to the marketing application" }' "https://graph.facebook.com/v12.0/me/pass_thread_control?access_token=<ACCESS_TOKEN>"
On success, your app receives the following JSON object.
{"success: "true"}
Releasing thread control using the Handover Protocol API passes thread control to the default application. This works the same way as using the Handover Protocol, except that once thread control is released, the default application will still be able to message the user.
curl -X POST -H "Content-Type: application/json" -d '{ "recipient": { "id": "<PSID>" }, "metadata": "Release thread control to default application" }' "https://graph.facebook.com/v12.0/me/release_thread_control?access_token=<ACCESS_TOKEN>"
On success, your app receives the following JSON object.
{"success: "true"}
You can find the app that currently controls the conversation by sending 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"
{ "data": [ { "thread_owner": { "app_id": APP-ID, "expiration": UNIX-TIMESTAMP } } ] }
Conversation routing allows your business to use Meta Business Suite Inbox as another application connected to your page, which can be used to continue conversations with your users. An inbox can also be assigned as a default application. Additionally, if you move a message to the Main folder or respond to a message in a conversation not controlled by the inbox, the inbox takes control of the conversation.
Entrypoint routing enables you to route conversations to specific apps based on based on a user's entrypoint. You can configure these routes on the Conversation Routing tab of your Facebook Page's settings. There are two types of entrypoint routing available: Link Routing and Social/organic routing.
Link routing enables you to configure multiple m.me links, and assign a routing app to each link.
Social/organic routing enables you to configure one app that will get thread control when a user enters an idle thread (no user messages in the last 24 hours) or clicks a Get Started button.
Learn more about the concepts and components of the Messenger Platform for Instagram Messaging.