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

Offloading Webhook is for offloading users from bot to human agent. The Webhook channel is a custom integration channel, make sure you don't mix up these two!

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.

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 HTTP 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>

Query Parameters

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

Request Body

Name	Type	Description
timestamp	string	The time at which the message was generated
messages	array	An array of user and bot messages
event	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 -

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

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

// Text Bot Message example
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "emulator-18878e66-03fb-4ee7-b2c4-eb9db1848291",
    "event": "messages",
    "messages": [
        {
            "actor": "bot",
            "message": {
                "text": "Hi Welcome"
            },
            "timestamp": "2021-11-15T07:38:31.387Z"
        }
    ],
    "timestamp": "2021-11-15T07:38:31.387Z"
}

// Quick reply Bot Message example
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "emulator-d3dac415-5263-482c-a30b-d1588c52d918",
    "event": "messages",
    "messages": [
        {
            "actor": "bot",
            "message": {
                "text": "Hi Welcome"
            },
            "timestamp": "2021-11-15T07:47:08.383Z"
        },
        {
            "actor": "bot",
            "message": {
                "text": "Choose what you want to do?",
                "quick_replies": [
                    {
                        "title": "Do API FROM CODE",
                        "payload": "{\"title\":\"Do API FROM CODE\",\"caption\":\"Do API FROM CODE\",\"type\":\"quickreply\",\"parameters\":[],\"nextDialogstateId\":\"19f87132-e23c-4335-877d-6a36f511c2cc\",\"originalTitle\":\"Do API FROM CODE\"}",
                        "content_type": "text"
                    },
                    {
                        "title": "Api Plugin",
                        "payload": "{\"title\":\"Api Plugin\",\"caption\":\"Api Plugin\",\"type\":\"quickreply\",\"parameters\":[],\"nextDialogstateId\":\"e0b327e0-bfa0-42a7-9685-c68491625b6e\",\"originalTitle\":\"Api Plugin\"}",
                        "content_type": "text"
                    },
                    {
                        "title": "SendMessageFromCode",
                        "payload": "{\"title\":\"SendMessageFromCode\",\"caption\":\"SendMessageFromCode\",\"type\":\"quickreply\",\"parameters\":[],\"nextDialogstateId\":\"c125a34e-7fec-4385-8333-6a91e25cdcff\",\"originalTitle\":\"SendMessageFromCode\"}",
                        "content_type": "text"
                    }
                ]
            },
            "timestamp": "2021-11-15T07:47:08.384Z"
        }
    ],
    "timestamp": "2021-11-15T07:47:08.383Z"
}

// carousel / Generic template message
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "emulator-39ac2f23-07ce-4878-bd7d-729e6b39efdf",
    "event": "messages",
    "messages": [
        {
            "actor": "bot",
            "message": {
                "attachment": {
                    "type": "template",
                    "payload": {
                        "template_type": "generic",
                        "elements": [
                            {
                                "title": "Item 1",
                                "image_url": "https://st.depositphotos.com/1708346/1858/i/600/depositphotos_18582903-stock-photo-carousel-at-night.jpg",
                                "buttons": [
                                    {
                                        "title": "Docs",
                                        "url": "https://docs.chatlayer.ai",
                                        "type": "web_url"
                                    }
                                ]
                            },
                            {
                                "title": "Item 2",
                                "image_url": "https://st.depositphotos.com/1708346/1858/i/600/depositphotos_18582903-stock-photo-carousel-at-night.jpg",
                                "subtitle": "Item 2 Subtitle",
                                "buttons": [
                                    {
                                        "title": "Docs",
                                        "url": "https://docs.chatlayer.ai",
                                        "type": "web_url"
                                    }
                                ],
                                "default_action": {
                                    "url": "https://docs.chatlayer.ai",
                                    "type": "web_url"
                                }
                            }
                        ]
                    }
                }
            },
            "timestamp": "2021-11-15T08:24:32.871Z"
        }
    ],
    "timestamp": "2021-11-15T08:24:32.871Z"
}

UserMessage objects may have the following structures:

// UserMessage examples

// Intro
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "emulator-942c05c5-b9b7-4319-81e7-6d687afaa23f",
    "event": "messages",
    "messages": [
        {
            "actor": "user",
            "message": {
                "channelType": "web",
                "sender": {
                    "id": "emulator-942c05c5-b9b7-4319-81e7-6d687afaa23f",
                    "botId": "ko3123ze",
                    "botType": "web",
                    "preferredLanguage": "en",
                    "firstname": "Guest",
                    "isEmulator": "true"
                },
                "timestamp": "2021-11-15T08:28:05.872Z",
                "messageType": "intro",
                "id": "61921a15cdee7f37a16ee5fc"
            },
            "timestamp": "2021-11-15T08:28:05.872Z"
        }
    ],
    "timestamp": "2021-11-15T08:28:05.908Z"
}

// Text
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "emulator-8f5873aa-8fee-471a-9467-81e30dec693d",
    "event": "messages",
    "messages": [
        {
            "actor": "user",
            "message": {
                "channelType": "web",
                "sender": {
                    "id": "emulator-8f5873aa-8fee-471a-9467-81e30dec693d",
                    "botId": "ko3123ze",
                    "botType": "web",
                    "isEmulator": "true"
                },
                "timestamp": "2021-11-15T08:26:13.154Z",
                "messageType": "text",
                "text": "hi there",
                "id": "619219a5cdee7f9f1b6ee5f7"
            },
            "timestamp": "2021-11-15T08:26:13.154Z"
        }
    ],
    "timestamp": "2021-11-15T08:26:13.193Z"
}

// Upload
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "1636964964162",
    "event": "messages",
    "messages": [
        {
            "actor": "user",
            "message": {
                "channelType": "web",
                "sender": {
                    "id": "1636964964162",
                    "botId": "ko3123ze",
                    "botType": "web",
                    "firstname": "Guest"
                },
                "timestamp": "2021-11-15T08:29:38.900Z",
                "messageType": "fileUploadInputResult",
                "urls": [
                    "https://minio.dev.chatlayer.ai/chatlayer-dev-eu-storage/f42af93e42b350fd7b874300c775756b168cc9ea4475b0c8c80e947228a26404/1636964964162_full.png"
                ],
                "data": {
                    "uploadStatus": "SUCCEEDED",
                    "fileUrl": "https://minio.dev.chatlayer.ai/chatlayer-dev-eu-storage/f42af93e42b350fd7b874300c7asdasdcc9ea4475b0c8c80e947228a26404/1636964964162_full.png"
                },
                "id": "61921a72cdee7fd1c56ee614"
            },
            "timestamp": "2021-11-15T08:29:38.900Z"
        }
    ],
    "timestamp": "2021-11-15T08:29:38.934Z"
}}

// Location
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "emulator-8f5873aa-8fee-471a-9467-81e30dec693d",
    "event": "messages",
    "messages": [
        {
            "actor": "user",
            "message": {
                "channelType": "web",
                "sender": {
                    "id": "emulator-8f5873aa-8fee-471a-9467-81e30dec693d",
                    "botId": "ko3123ze",
                    "botType": "web",
                    "isEmulator": "true"
                },
                "timestamp": "2021-11-15T08:26:13.154Z",
                "messageType": "location", 
                "coordinates": { "lat": 0, "long": 0 } 
                "id": "619219a5cdee7f9f1b6ee5f7"
            },
            "timestamp": "2021-11-15T08:26:13.154Z"
        }
    ],
    "timestamp": "2021-11-15T08:26:13.193Z"
}

// Postback
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "emulator-6d09d652-a971-47ab-8484-223a86ff316e",
    "event": "messages",
    "messages": [
        {
            "actor": "user",
            "message": {
                "channelType": "web",
                "sender": {
                    "id": "emulator-6d09d652-a971-47ab-8484-223a86ff316e",
                    "botId": "ko3123ze",
                    "botType": "web",
                    "isEmulator": "true"
                },
                "timestamp": "2021-11-15T08:33:39.276Z",
                "messageType": "postback",
                "title": "Set Variables",
                "parameters": [],
                "nextDialogstateId": "071abbc7-1d6e-4689-adef-1ea825178a72",
                "id": "61921b63cdee7f21ab6ee621"
            },
            "timestamp": "2021-11-15T08:33:39.276Z"
        }
    ],
    "timestamp": "2021-11-15T08:33:39.309Z"
}

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.
event	string	The type of request, in this case offload
timestamp	string
sessionId	string
version	string
botId	string

200 For successful offloading, we expect following response

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

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

One example of the offload request can be as follows:

// Some code
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "emulator-714a7b79-d674-4a62-a9a9-49581d7451e5",
    "timestamp": "2021-11-15T08:36:21.527Z",
    "event": "offload",
    "transcript": [
        {
            "actor": "bot",
            "message": {
                "text": "Hi Welcome"
            },
            "timestamp": "2021-11-15T08:36:11.991Z"
        },
        {
            "actor": "bot",
            "message": {
                "text": "Choose what you want to do?",
                "quick_replies": [
                    {
                        "title": "Do API FROM CODE",
                        "payload": "{\"title\":\"Do API FROM CODE\",\"caption\":\"Do API FROM CODE\",\"type\":\"quickreply\",\"parameters\":[],\"nextDialogstateId\":\"19f87132-e23c-4335-877d-6a36f511c2cc\",\"originalTitle\":\"Do API FROM CODE\"}",
                        "content_type": "text"
                    },
                    {
                        "title": "Api Plugin",
                        "payload": "{\"title\":\"Api Plugin\",\"caption\":\"Api Plugin\",\"type\":\"quickreply\",\"parameters\":[],\"nextDialogstateId\":\"e0b327e0-bfa0-42a7-9685-c68491625b6e\",\"originalTitle\":\"Api Plugin\"}",
                        "content_type": "text"
                    },
                    {
                        "title": "carousel",
                        "payload": "{\"title\":\"carousel\",\"caption\":\"carousel\",\"type\":\"quickreply\",\"parameters\":[],\"nextDialogstateId\":\"0844670c-ee9f-43eb-9102-f50321cb4921\",\"originalTitle\":\"carousel\"}",
                        "content_type": "text"
                    },
                    {
                        "title": "first options",
                        "payload": "{\"title\":\"first options\",\"caption\":\"first options\",\"type\":\"quickreply\",\"parameters\":[],\"nextDialogstateId\":\"13fc7f3e-80e5-45b8-862b-d2ff436eae0e\",\"originalTitle\":\"first options\"}",
                        "content_type": "text"
                    }
                ]
            },
            "timestamp": "2021-11-15T08:36:11.992Z"
        },
        {
            "actor": "user",
            "message": {
                "parameters": [],
                "text": "first options",
                "messageType": "postback",
                "title": "first options",
                "nextDialogstateId": "13fc7f3e-80e5-45b8-862b-d2ff436eae0e",
                "channelType": "emulator",
                "sender": {
                    "id": "emulator-714a7b79-d674-4a62-a9a9-49581d7451e5",
                    "botId": "ko3123ze"
                }
            },
            "timestamp": "2021-11-15T08:36:15.009Z"
        },
        {
            "actor": "bot",
            "message": {
                "attachment": {
                    "type": "template",
                    "payload": {
                        "template_type": "button",
                        "text": "What do you want to do?",
                        "buttons": [
                            {
                                "title": "Set Variables",
                                "type": "postback",
                                "payload": "{\"title\":\"Set Variables\",\"caption\":\"Set Variables\",\"type\":\"button\",\"originalTitle\":\"Set Variables\",\"nextDialogstateId\":\"071abbc7-1d6e-4689-adef-1ea825178a72\",\"parameters\":[]}"
                            },
                            {
                                "title": "offload",
                                "type": "postback",
                                "payload": "{\"title\":\"offload\",\"caption\":\"offload\",\"type\":\"button\",\"originalTitle\":\"offload\",\"nextDialogstateId\":\"408c102e-7215-48f8-a76c-5a45d70dcd9d\",\"parameters\":[]}"
                            }
                        ]
                    }
                }
            },
            "timestamp": "2021-11-15T08:36:15.010Z"
        }
    ]
}

Recipes

User-requested human handover

Use a "Send to offload provider" Action block to trigger an offload call to your API.

Sending messages as an agent

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

Webhook Offloading FAQs

Here you can find frequently asked questions regarding Webhook offloading

Why do I get requests on the offloading endpoint even though the user is not yet offloaded?

We send the details of all the conversations that are happening in between user and the bot to the offloading endpoint under the event: "messages" so you can takeover the conversation if need be. This would also allow customers to keep track of all the conversations if need be.