New message webhook (Fulfillment)
How to configure a 'new message' webhook on Cliengo.
TL;DR
For each received message, we will send this request and expect this response, it's easy, isn't it?
Introduction
Cliengo will send a new HTTP POST after processing an incoming message, by responding to this request you will be able to set some information in the chatbot memory or to force some specific chatbot behavior.
When will Cliengo send the webhook?
We will send the webhook after running our heuristics to detect information over each message, but before answering it, so you'll have the chance to override the response.
If the conversation is intervened, you will still receive the webhook, but you won't be able to force the chatbot to send a specific text.
What will Cliengo send in the webhook?
We will send the whole "chatbot memory", there you'll find all asked questions, the parsed information, and the question the user was asked.
Request (POST) JSON example
{
"channel":"WEB",
"visitorId":"[email protected]",
"websiteId":"5de12d55e4b096a8283b6ed8",
"companyId":"5de12d55e4b096a8283b6ed6",
"are_you_there":{
"index":0
},
"chat_log":[
{
"sender":"visitor",
"text":"Hi! I'm Ariel, my email is [email protected]"
},
{
"sender":"chatbot",
"text":"Ok. I need your phone number please"
}
],
"collected_data":{
"intent":[
],
"entities":[
],
"custom":{
"custom_field": "example"
},
"name":{
"value":"ariel"
},
"email":{
"value":"[email protected]"
},
"phone":{
"national_format":"011 3815-2222",
"international_format":"+541138152222"
}
},
"fired_triggers":[
"11123d55e4b096a8283b6ed8"
],
"reactivated":false,
"status":"ACTIVE",
"tags":[
"fired_new_lead"
],
"visitorData":{
"utms": "&utm_source=Instagram&utm_medium=IGAds&utm_campaign=Campaign1",
"url":"https://lw.cliengo.com/?companyId=5",
"visitorIp":"13.90.115.123"
},
"visitor_status":"ONLINE",
"conversationId":"5f0cbe62162e0dec1910d197",
"softDisable":false,
"chatbotName":"Martín",
"flow":{
"last_question_id":3,
"retry_count":0
},
"last_interaction_date":"2020-07-13T20:04:59.595Z",
"creation_date":"2020-07-13T20:04:51.904Z",
"lead_post_date":"2020-07-13T20:05:59.606Z"
}
Request (POST) fields description
Name | Description |
---|---|
channel | The channel where the chatbot is answering, can be one of: WEB, FACEBOOK, WHATSAPP. |
visitorId | A unique ID identifying the visitor, it will have different format depending on the channel. |
websiteId | The website id where the chatbot is answering |
companyId | This is your company ID |
are_you_there.index | If the visitor has been idle for a minute, the chabot ask if someone is still there, in this field we store the number of times we send the message. |
chat_log | Is an array containing all the conversation messages (inbound and outbound). |
chat_log.sender | Who sent the message, can be 'visitor' or 'chatbot' |
chat_log.text | Yes, it's the text |
collected_data | In this field, we store all the information parsed from the text. When we talk about "chatbot memory", we are talking about this field |
collected_data.intent | An array of detected intents in the whole conversation |
collected_data.entities | An array of detected entities in the whole conversation |
collected_data.custom | When the visitor answers a question with internal_name, that answer is stored here, using the internal_name as key. |
collected_data.name.value | The detected visitor name. |
collected_data.email.value | The detected visitor email. |
collected_data.phone.national_format | The detected visitor phone, in national format |
collected_data.phone.international_format | The detected visitor phone, in international format, this one is the usefull. |
fired_triggers | An array containing all the fired trigger IDs |
reactivated | A flag indicating if this conversation was reactivated |
status | The conversation status, this should be always ACTIVE |
tags | An array of flags |
visitorData | An object containing specific visitor information, this information is only for WEB channel |
visitorData.utms | The utm parameters the visitor had when arrived to your website. |
visitorData.url | The url where the visitor started the conversation |
visitorData.visitorIp | The visitor IP |
visitor_status | The visitor status, this should be always ONLINE |
conversationId | This is the conversation ID |
softDisable | If your plan exceeded its limits (only applies to FREE plan) |
chatbotName | The chatbot name |
flow.last_question_id | This is the id of the last asked question |
flow.retry_count | This is the number of times the question was retried (only for mandatory questions) |
last_interaction_date | The datetime of the last received message |
creation_date | The datetime when the conversation started |
lead_post_date | The datetime when the conversation was posted to the CRM. |
How can I answer the webhook?
By answering the webhook you can make three different things:
- Save information in the chatbot memory
- Force the chatbot to send a text
- Change the current active question
Response JSON example
All fields are optional
{
"name": {
"value": "Juan Roman",
},
"email": {
"value": "[email protected]"
},
"phone": {
"national_format": "1234542123",
"international_format": "12343132112"
},
"custom": {
"userType": "advanced",
"thing1": "something",
"thing2": "something"
},
"response": {
"text": ['Ok', 'What model are you interested in?'],
"response_type": 'LIST',
"response_options": ["Model 3", "Model Y"],
"stopChat": true,
"flow": 5
}
}
Response fields description
Name | Description | Optional |
---|---|---|
name.value | Will set the visitor name in the chatbot memory | Yes |
email.value | Will set the visitor email in the chatbot memory | Yes |
phone.national_format | Will set the visitor phone in national format in the chatbot memory | Yes |
phone.international_format | Will set the visitor phone in international format in the chatbot memory | Yes |
custom | Will set the key and value in the chabot memory, this information will be posted later to the CRM, you can send more than one attribute inside this object | Yes |
response.text | An array with the text you want to sent to the user, each element will be a different message | Yes |
response.response_type | The expected response type, can be one of: TEXT, LIST, NAME, EMAIL, PHONE | Yes |
response.response_options | If the response_type was LIST, this array allows you to specify the possible response options the question. | Yes |
response.stopChat | If this field is set to true, the chatbot will stop executing the script util the visitor talks again | Yes |
response.flow | This is used to change the current active question (for example, using this you can skip a questions or not depending on the user answer), | Yes |
How to set up the webhook?
You can set up a different webhook URL for each specific question or you can set one URL for all the questions. Currently the webhook URL is not editable by users, but please contact us, we can help you with this.
Updated about 4 years ago