Use Facebook Handover


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.


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.

Payload is JSONtrue (on)
PayloadJSON { "recipient": { "id": { "$cs": { "script": "", "type": "string" } } }, "target_app_id": 263902037430900, "metadata": "String to pass to secondary receiver app" }

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"


Webhook Subscription

Please note that you need to be subscribed to the "messaging_handovers" webhook event in order to receive the notification for the handover back to the Flow.

You can catch this data input by performing an IF on


Example Cognigy.AI 3.0 Flow

Download an example Flow at