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.

Offloading Webhook API

To send

get

https://api[.staging].chatlayer.ai/v1/offload/webhook/:webhookId
Request
Response
Request
Path Parameters
optional
string
Response
200: OK

Webservice Implementation Reference

Your webservice will need to implement the following API methods for us to communicate with. 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 an event 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.

get
API Health Check

<your_api_url>
You must send the response as described in the Response tab.
Request
Response
Request
Query Parameters
challenge.verifyToken
optional
string
The verifyToken allows you to validate the request is made by Chatlayer
Response
200: OK
{ "status": "ok" }

post
Messages

<your_api_url>
Request
Response
Request
Query Parameters
challenge.verifyToken
optional
string
The verifyToken allows you to validate the request is made by Chatlayer
Body Parameters
timestamp
optional
string
The time at which the message was generated
messages
optional
array
An array of user and bot messages
event
optional
string
The type of request, in this case messages
channel
optional
string
The channel type
sessionId
optional
string
The user's session ID
version
optional
string
The bot version, either DRAFT or LIVE
botId
optional
string
The bot ID
Response
200: OK
We do not expect a response body.

The items in the messages array have the following format -

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

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

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

UserMessage objects may have the following structures:

// UserMessage examples
// Intro
{
"messageType": "intro",
// These fields are also included in every other UserMessage example
// For brievity, we'll only document them once:
"channelType": "web",
"sender": {
// The sender object differs between channelTypes, but will always include:
"id": "123",
"botId": "123"
},
"timestamp": "2020-09-22T19:34:16.049Z"
}
// 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"
}

post
Offload

<your_api_url>
Request
Response
Request
Body Parameters
payload
optional
object
The payload you configured in the action dialogstate
channel
optional
string
transcript
optional
array
An array containing all messages sent throughout the conversation.
event
optional
string
The type of request, in this case offload
timestamp
optional
string
sessionId
optional
string
version
optional
string
botId
optional
string
Response
200: OK
{
"offloadSuccess": true,
"pauseBot": true
}

The items in the transcript array have the same format as in the messages method described above.

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.