Facebook Messenger Bot integration

Suppose you would like to use your chatbot with Facebook Messenger but wish to hand over certain conversations to agents in VCC Live. In that case, you can use the Handover Protocol for Facebook Messenger.
This guide explains how to implement Facebook Messenger’s Handover Protocol to pass control of a conversation from your primary app (e.g. a chatbot) to VCC Live, enabling seamless interaction management between two apps.

Overview

The Handover Protocol allows multiple apps to manage conversations on a single Facebook Page. In this scenario:

• Primary Receiver: The app that currently controls the conversation, e.g. your chatbot
• Secondary Receiver (VCC Live): The app waiting in the background that can be assigned control.
• Thread Control: A set of APIs that allows apps to pass, take, and request control of a conversation.

Prerequisites

1. Facebook Page: Both apps must be subscribed to the Facebook Page you are managing.
2. App Registration: Ensure that your primary app is registered in the Facebook for Developers platform.
3. App Permissions: Both apps need the following permissions:
   • pages_messaging
   • pages_messaging_phone_number
   • pages_show_list

Pass Thread Control to VCC Live

Once your primary app has completed the initial interaction with the user, it can pass the conversation to VCC Live using the Pass Thread Control API.

API Request

POST https://graph.facebook.com/LATEST-API-VERSION/me/pass_thread_control?access_token=<PAGE_ACCESS_TOKEN>

Request Body

{
  "recipient": {
    "id": "<USER_PSID>"
  },
  "target_app_id": "<VCC_LIVE_APP_ID>",
  "metadata": "Passing control to VCC Live for live agent assistance"
}

Parameters

• <PAGE_ACCESS_TOKEN>: The page access token for your Facebook Page.
• <USER_PSID>: The Page Scoped ID (PSID) of the user.
• <VCC_LIVE_APP_ID>: The App ID of VCC Live.

Example Request

curl -X POST "https://graph.facebook.com/LATEST-API-VERSION/me/pass_thread_control?access_token=EAAGm0PX4ZCpsBAI5ZA" 
  -H "Content-Type: application/json" 
  -d '{
    "recipient": {
      "id":"1234567890"
    },
    "target_app_id":"9876543210",
    "metadata":"Passing control to VCC Live for live agent assistance"
  }'

In this example:

• 1234567890 is the user’s PSID.
• 9876543210 is the App ID of VCC Live.
• The metadata provides additional context, which is optional.

Note: The team at VCC Live can help you identify the relevant App IDs.

Handle Standby Events

When VCC Live takes control of the conversation, the primary app will receive a standby event, notifying it that it is no longer the active app.

Webhook Event Example (Standby Event)

{
  "object": "page",
  "entry": [
    {
      "id": "<PAGE_ID>",
      "time": 1458692752478,
      "standby": [
        {
          "sender": {
            "id": "<USER_PSID>"
          },
          "recipient": {
            "id": "<PAGE_ID>"
          },
          "timestamp": 1458692752478,
          "message": {
            "mid": "mid.1457764197618:41d102a3e1ae206a38",
            "text": "User's message"
          }
        }
      ]
    }
  ]
}

Additional Resources

• Meta Messenger API Documentation
• Handover Protocol
• Webhooks Setup