Chatlayer Documentation
Get in touchAbout Chatlayer
  • Welcome
  • What's new
  • Send feedback
  • start quickly
    • Leadzy tutorial
      • 0. Introduction
      • 1. New bot, new block
      • 2. Understand your users
      • 3. Collect and display user input
      • 4. Steer the conversation with Conditions
      • 5. Empower your bot with Actions
      • 6. Set up a channel and publish your bot
    • Templates
      • Banking
      • E-Commerce Returns
      • E-Bike Shop
      • E-Scooter Support
      • Feedback
      • Find Nearest Location
      • GPT
      • 🆕Gym
      • Job applications
      • Knowledge base AI template
      • Lead generation
      • 🆕NPS
      • Restaurant
      • Retail
  • navigation
    • Analytics
      • Dashboard
      • Customers
      • Conversations
      • User flow
      • Intents
      • 🆕Funnels [Beta]
    • Bot builder
      • Flows
        • Canvas functionalities
        • Collaborate with team members
        • Manage your flows
        • 🆕[Beta] Export and import flows
      • Bot dialogs view
      • Translations
      • Events
    • NLP
      • Dashboard
      • Intents
      • Expressions
      • Entities
      • Train
      • NLP settings
      • Improve
    • Knowledge base AI
      • Add content to your KBAI
      • Build your KBAI flow
      • Use your KBAI source URL in a button
      • Use tags to limit your KBAI content
      • 🆕Use Tables to store your KBAI questions
      • 🆕Manage handover where KBAI is unsatisfactory
    • History
      • Conversations
      • Execution logs
      • Versions
    • Channels
    • Tables
      • Create a table with records
      • Column types
      • Operate on your records
        • Insert record
        • Update record
        • Retrieve record
        • Delete record
      • API
    • Settings
      • Bot settings
      • Offloading
      • Variables
      • Voice
      • Import/Export
  • build your bot
    • Conversation design
      • Plan your bot
      • Conversation design workflow
    • Flow logic
      • Blocks
        • Message
        • Condition
        • Collect input
        • Action
      • Go-to connections
    • 🆕Emulator
    • Tips & best practices
      • Route your flow depending on the time
      • Improve the Not understood block
        • How to create better not understood messages
        • Not understood counter
        • Not understood Google search
      • Go to previous block
      • Recognizing a returning user
      • Skip introduction message
      • Route your flow depending on the channel
      • Reuse flows
      • Connect two bots to each other
  • understand users
    • Natural language processing (NLP)
      • Basic NLP concepts
      • Detect information with entities
        • Match entities
        • Contextual entities
        • System entities
        • Composite entities
      • NLP best practices
        • Word order and diversity of expressions
      • AI intent booster
      • Train your NLP
      • Context
      • NLP import & export
      • Sentiment analysis
    • Languages
      • Supported languages
      • Make your bot multilingual
      • Change language within the conversation
  • set up channels
    • Add a channel to your bot
    • All channels
      • 🚨Facebook Messenger [Deprecated soon]
        • Facebook Admin Removal
        • Facebook Webview Whitelisting
        • Facebook Messenger API updates for Europe
      • 🚨Google Assistant [Deprecated soon]
      • Webhook
      • Web
        • 🚨Web V1 [Deprecated]
          • Customize web widget
          • Live example web widget
        • 🆕Web V2
          • 🆕From Web V1 to V2
          • 🆕Web V2 methods and options
    • Sinch Conversation API
      • Configure your Sinch Conversation API
      • 🆕 Make the most of RCS with Carousels
      • WhatsApp Business API
  • integrate & code
    • API calls
      • Configure your API integration
      • Advanced API features
      • V1 API Reference
      • Custom integrations 101
    • Code editor
      • [Example] Sending data to Airtable (POST)
      • [Example] Retrieving data from Airtable (GET)
      • [Example] Making SOAP requests
    • App integrations
      • Airtable
      • Freshdesk
      • Freshdesk Messaging
      • 🆕Gmail
      • Intercom
      • Mailgun
      • OpenAI: GPT-3, ChatGPT and GPT-4
      • Salesforce
      • 🆕Slack
      • Topdesk
      • Zendesk Support
      • Zendesk Sunshine (beta)
    • 🆕Expression syntax
    • Human handover & live chat
      • Sinch Contact Pro
      • #Interact
      • Genesys Cloud
      • Offloading Webhook
      • Salesforce Service Cloud
      • Sparkcentral by Hootsuite
      • Zendesk Chat
    • Chatlayer messages specifications
  • Publish
    • Publish your bot
      • Publish a flow
  • Analyze & maintain
    • Analytics definitions
    • Data retention
    • Maintenance
    • Session
    • Track events for analytics
  • VOICE
    • 🆕Send bot response as audio
    • Voicebots
      • Create a voicebot
      • Voicebot-specific actions
      • Test your voicebot
      • From chat to voice
  • access & support
    • Identity & Access
      • Single Sign-On (SAML SSO)
    • Billing & subscription
    • Get in touch
    • Chatlayer glossary
    • SaaS Regions & IP Ranges
    • Status
    • Debug your bot
      • No correct response
      • Collect input not working
      • Video isn't working
Powered by GitBook
On this page
  • Configuration
  • Webservice Implementation Reference
  • API Health Check
  • Messages
  • Offload
  • Recipes
  • User-requested human handover
  • Sending messages as an agent
  • Webhook Offloading FAQs

Was this helpful?

  1. integrate & code
  2. Human handover & live chat

Offloading Webhook

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

PreviousGenesys CloudNextSalesforce Service Cloud

Last updated 1 year ago

Was this helpful?

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

{ "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

The items in the messages array have the following format -

{
    "actor": "bot" | "user",
    "message": UserMessage | BotMessage
}
// 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

{
    "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

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.

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

Use the to send messages as an agent.

here
conversation actions API
Webhook channel