Conversation Routing

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.

Overview

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.

Default App

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.

Marketing 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.

Limitations

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:

• Human Agent Tag: The tag can be used, but the app using the tag cannot take control from another app. If the app already has thread control, it can continue to use it.
• Idle mode: When using Conversation Routing, threads always have an owner, and can never be idle.
• Handover Protocol APIs: To maintain forward compatibility for existing apps using the Handover Protocol APIs, 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.

Before You Start

Before you can pass conversations between apps, you need the following:

• A Meta Ad Account
• The Meta app ID for your default app
• The Meta app ID for your marketing app
• Connect all apps to your business' Facebook Page
• The person requesting the Page access token must have Admin access or be able to perform the MANAGE task on a Classic Facebook Page, Facebook access (New Pages Experience) for the Facebook Page, or Full control via the Business Settings
• A server to receive Meta Webhooks notifications. We recommend setting up a separate endpoint on your server for each app.
• Subscribe all apps to the following webhooks topics:
  • messages
  • 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.

Assign a Default App

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

Assign a marketing app

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.

Standby Webhook Controls

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.

• [Deprecated] For Classic Pages, go to Page Settings > Advanced Messaging > Connected Apps. Click "Configure" next to an app you want to unsubscribe from the standby webhooks.
• For New Pages Experience, go to Page Settings > Page setup > Advanced messaging > Connected Apps. Click "Edit" next to an app you want to unsubscribe from the standby webhooks.

In the resulting dialog, you can toggle standby access on and off for this app, for both Messenger and Instagram standby webhooks.

Configure apps to take over conversations

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.

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.

Webhooks Notifications

The following table shows the action that triggered the webhooks and the webhooks notifications sent to each app's webhooks server endpoint.

Messaging Feature Status API

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.

Example API Request

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

Thread Control

An application can pass or release thread control using one of two methods: using the Send API, or using the handover protocol API.

Using the Send 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.

Example API Request

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.

Example API Request

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

Reference

Using app_id

You can pass thread control to a specific app by setting app_id and control_type fields in the thread_control parameter.

Example API Request

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.

Example API Request

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

Reference

Using the Handover Protocol API

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.

• Take thread control
• Pass thread metadata
• Request thread control
• Extend thread control

To pass control to the default application, use the pass_thread_control endpoint.

Example API Request

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.

Example API Request

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.

Example API Request

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

Find the App in Control

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.

Example API Request

curl -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/thread_owner
    ?recipient=PSID
    &access_token=PAGE-ACCESS-TOKEN"

Example API response

• If your app is the current thread owner, or if your app is the default app of the page, you'll receive the app_id and the expiration timestamp in the API response;
• Otherwise, if the thread is not idle, you'll will receive the expiration timestamp in the API response;
• Otherwise, you'll receive an empty API response.

{
  "data": [
    {
      "thread_owner": {
        "app_id": APP-ID,
        "expiration": UNIX-TIMESTAMP
      }
    }
  ]
}

Meta Business Suite Inbox Support

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

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

Link routing enables you to configure multiple m.me links, and assign a routing app to each link.

Social/organic Routing

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.

See Also

Learn more about the concepts and components of the Messenger Platform for Instagram Messaging.

• Conversations API – Get more information about a conversation
• Create an ad campaign
• Facebook Page Tasks – Learn more about tasks you can perform on a Facebook Page
• Facebook Pages – Visit the business helpcenter to learn more about Classic and New Pages Experiences
• Handover Protocol – For routing conversations between 3 or more apps
• Instagram Messaging from Messenger Platform
• Marketing Messages – Learn how to get optins and to send recurring marketing messages
• Messaging Insights API – Learn how to get insights into your conversations
• Policies for using Messenger Platform – Learn more about the policies enforced for Messenger Platform
• Standard Messaging Window – Learn more about the 24 hour standard messaging window
• Meta Webhooks for Messenger Platform – Learn more about setting up a webhooks server to receive Meta Webhooks Notifications
• Meta Webhooks Topic Reference for Messenger Platform – See examples of webhooks notifications