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.

Before You Start

This tutorial assumes that you have:

• Successfully completed the Get Started with the Messenger Platform Handover Protocol guide

You will need:

• The Page-scoped ID (PSID) of the customer who started the 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 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 -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"

Example API Response

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

Example Webhooks Notification

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

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.

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"

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

Page Inbox Control

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.

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 sent the request, 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/pass_thread_control
    ?recipient={id:PSID}
    &target_app_id=APP-REQUESTING-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

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

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.