Facebook Messenger: Use Facebook Handover

This page elucidates how Facebook Handover enables two or more Facebook applications to participate in a conversation by passing control of the conversation between them.

The Facebook Messenger Platform's handover protocol enables two or more Facebook apps to participate in a conversation by passing control of the conversation between them. This feature can be used in many ways to enrich your Messenger experience. For example, this protocol makes it possible for a Page to simultaneously use one Facebook app to connect to a Cognigy Flow to handle customer messages automatically and another to provide customer service through live agents. This How-To describes how to implement such functionality.

For example purposes, we will set up the bot to hand thread control to the Facebook Page Inbox. You could alternatively also hand thread control to another app.

Requirements

You will need:

1. A Facebook Page
2. A Facebook App that connects to Cognigy

Perform the basic Facebook Setup

As described Deploy a Messenger Endpoint

Setting up the App

Go to the Facebook Developer Portal and make sure that your app in addition to the standad events also subscribes to the messaging_handovers webhook event.

Set up the Page

In your Facebook Page settings under Messenger Settings, set up your app as the Primary Receiver and your Page Inbox as the Secondary Receiver.

Build the Handover into your Flow

In your Cognigy Flow, find the spot where you want to hand control to the Page Inbox. Include a HTTP Request Node with the following parameters.

This HTTP Request will cause the thread control to be passed to the Page Inbox. If you want to pass it to another app, change the target_app_id accordingly.

Moving Control back to Cognigy

When the conversation between the user and the live agent are done, the live agent presses the Mark as Done button, which will cause the thread to be passed back to Cognigy.

Cognigy will receive an input with no text and the following data input.

{
    "request": {
        "recipient": {
            "id": "xxx"
        },
        "timestamp": 1529677137937,
        "sender": {
            "id": "xxx"
        },
        "pass_thread_control": {
            "new_owner_app_id": xxx,
            "metadata": "Pass thread control from Page Inbox"
        }
    },
    "pageAccessToken": "xxx",
    "appId": "xxx"
}

You can catch this data input by performing an IF on ci.data.request.pass_thread_control