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.