Offloading Webhook

Learn how to create your own human handover integration through the Offloading Webhook

The offloading webhook allows you to integrate any human handover live chat platform. You can use the webhook to:

• Receive incoming user messages

• Receive outgoing bot messages

• Act upon offloading requests from a user

This feature is currently in beta. If you would like access, please get in touch.

Configuration

To configure your Chatlayer Offloading Webhook, head over to Settings > Offloading and create a Webhook integration.

Enter the API URL for your webservice and a Verify Token allowing you to validate incoming requests.

We will send a test request to your API URL when you press Save to validate whether your webservice is alive and ready to take requests, described in the Health Check method.

Congratulations! You are ready to start using your custom human handover integration.

API Methods

All requests will arrive in JSON format at the API URL configured during the setup of the offloading webhook in Chatlayer. Every JSON POST request has a body with a type parameter that allows you to distinguish between the different types of data coming in. Different types are explained below.

We expect a status code of 200 for every request made to the webservice. Response data should be in JSON format.

API Health Check

GET <your_api_url>

You must send the response as described in the Response tab.

Query Parameters

Name	Type	Description
challenge.verifyToken	string	The verifyToken allows you to validate the request is made by Chatlayer

200

{ "status": "ok" }

Messages

POST <your_api_url>

Request Body

Name	Type	Description
timestamp	string	The time at which the message was generated
messages	array	An array of user and bot messages
type	string	The type of request, in this case messages
channel	string	The channel type
sessionId	string	The user's session ID
version	string	The bot version, either DRAFT or LIVE
botId	string	The bot ID

200 We do not expect a response body.

The items in the messages array have the following format -

{
    "type": "bot" | "user",
    "message": UserMessage | BotMessage
}

BotMessage objects follow the same structure as that of the Webhook Channel API, documented here.

// BotMessage example
{
    "type": "bot",
    "message": { "text": "Hi, I'm a chatbot" }
}

UserMessage objects may have the following structures:

// UserMessage examples

// Intro
{ "messageType": "intro" }

// Text
{ "messageType": "text", "text": "Hi, I'm a user and I'd like to talk to an agent" }

// Upload
{ "messageType": "upload", "urls": [] }

// Location
{ "messageType": "location", "coordinates": { "lat": 0, "long": 0 } }

// Postback
{ "messageType": "postback", "title": "I'm a button" }

Offload

POST <your_api_url>

Request Body

Name	Type	Description
payload	object	The payload you configured in the action dialogstate
channel	string
transcript	array	An array containing all messages sent throughout the conversation.
type	string	The type of request, in this case offload
timestamp	string
sessionId	string
version	string
botId	string

200

{
    "offloadSuccess": true,
    "pauseBot": true
}

Recipes

User-requested human handover

Use a "Send to offload provider" bot action dialog to trigger an offload call to your API.

Sending messages as an agent

Use the asynchronous actions API to send messages as an agent.