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.

Before You Start

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:

The ID for the person who started the conversation with your Facebook Page or Instagram Professional account. This ID could be a Page-scoped ID (PSID) or an Instagram-scoped ID (IGSID) Learn how to get information about a conversation.

Take Control

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.

Sample API Request

Formatted for readability.

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"

Example API Response

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

Example Webhooks Notification

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

Extend Control

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.

Sample API Request

Formatted for readability.

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"

Releasing Control

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.

Sample API Request

Formatted for readability.

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"

Request Control

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.

Sample API Request

Formatted for readability.

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"

Example API Response

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.

Example Webhooks Notification

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

Inbox Control

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.

Pass Control to Another App

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.

Limitations

The target_app_id is required or the call will fail
Only the target app will receive a webhooks notification

Sample API Request

Formatted for readability.

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

Example API Response

On success, your app will receive the following response:

{
  "success" : true
}

Control of the conversation has been passed to another app.

Example Webhooks Notification

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

Pass Metadata

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.

Limitations

Only a Primary Receiver app can get IDs for other apps connected to the Page
Only the target app will receive the webhook notification

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.

Example Request

Formatted for readability.

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.

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

Assign a Primary Receiver

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

Find the App in Control

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.

Sample API Request

Formatted for readability.

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

Example API Response

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.