Bots API

Engage Digital’s Bots API is our way to integrate bots into Engage Digital chat channels. This guide is meant to provide integrators a comprehensive overview of the available features for them to be able to create an implementation.

Currently it's only available on Messenger channels, whose associated documentation on Facebook is available here.

Setup

First you will need to choose which Facebook app is primary (ED or BOT app), based on that, handover protocol behavior won’t be exactly the same, see aforementioned Facebook documentation for more information.

You can change the app’s role for the source page whenever you want, you need to go on the Facebook’s page -> Settings -> Advanced messaging:


If your page uses New Pages Experience you will have to switch to your page’s profile. Then you go in Settings & privacy -> Settings -> New Pages Experience -> Advanced messaging:

After you’re done configuring that you will need to ensure that the bots uses well our new Bots api endpoint

Using the endpoint

Format

JSON response when trying to proceed to handover respects following format:

{
  "status": 200,
  "message": "Success",
}

Handover from bot to agent

Request example

curl -X POST "https://domain-test.api.engagement.dimelo.com/1.0/bots/handover?access_token=<access_token>&identity_foreign_id=<foreign_id>&from=bot&to=agent&type=messenger"

Query Parameters

Parameter Description
access_token API identification token
identity_foreign_id The foreign_id of the identity for which you want to do the handover
from The app that has thread control before handover
to The app that should get thread control after handover
type The type of channel

When calling this endpoint, ED Facebook app will use Facebook’s request_thread_control api to ask for thread control, see Facebook's documentation.

The Bot (or the app controlling the thread) app will then receive a webhook from Facebook. When the webhook is received , it's important for the bot app to call Facebook’s pass_thread_control endpoint to give agent an ability to control the thread, see Facebook's documentation for more details.

Handover from agent to bot

Request example

curl -X POST "https://domain-test.api.engagement.dimelo.com/1.0/bots/handover?access_token=<access_token>&identity_foreign_id=<foreign_id>&from=agent&to=bot&type=messenger&app_id=<bot_app_id>"

Query Parameters

Parameter Description
access_token API identification token
identity_foreign_id The foreign_id of the identity for which you want to do the handover
from The app that has thread control before handover
to The app that should get thread control after handover
type The type of channel
app_id The id of the Facebook's app that controls the Bot

This call will only pass if there is currently no intervention engaged with the linked identity.

If the call passes, ED Facebook app will use the pass_thread control Facebook API to give thread control back to the Bot app

HOP features

On Facebook's side, when a customer sends a message to a Facebook page the thread control will go to the primary app. When no primary app is setup the Messenger thread will stay in IDLE mode

When an agent tries to send a message via ED while another app has thread control we will either:

  • Request thread control if Bot app is primary
  • Take thread control if ED app is primary

After that we will retry the synchronization of the content

When the intervention is closed, we will release thread control

Workflow

Bot primary

ED primary

No specified primary

When agent interrupts bot