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.

550550



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

NameDescription
channelThe channel where the chatbot is answering, can be one of: WEB, FACEBOOK, WHATSAPP.
visitorIdA unique ID identifying the visitor, it will have different format depending on the channel.
websiteIdThe website id where the chatbot is answering
companyIdThis is your company ID
are_you_there.indexIf 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_logIs an array containing all the conversation messages (inbound and outbound).
chat_log.senderWho sent the message, can be 'visitor' or 'chatbot'
chat_log.textYes, it's the text
collected_dataIn 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.intentAn array of detected intents in the whole conversation
collected_data.entitiesAn array of detected entities in the whole conversation
collected_data.customWhen the visitor answers a question with internal_name, that answer is stored here, using the internal_name as key.
collected_data.name.valueThe detected visitor name.
collected_data.email.valueThe detected visitor email.
collected_data.phone.national_formatThe detected visitor phone, in national format
collected_data.phone.international_formatThe detected visitor phone, in international format, this one is the usefull.
fired_triggersAn array containing all the fired trigger IDs
reactivatedA flag indicating if this conversation was reactivated
statusThe conversation status, this should be always ACTIVE
tagsAn array of flags
visitorDataAn object containing specific visitor information, this information is only for WEB channel
visitorData.utmsThe utm parameters the visitor had when arrived to your website.
visitorData.urlThe url where the visitor started the conversation
visitorData.visitorIpThe visitor IP
visitor_statusThe visitor status, this should be always ONLINE
conversationIdThis is the conversation ID
softDisableIf your plan exceeded its limits (only applies to FREE plan)
chatbotNameThe chatbot name
flow.last_question_idThis is the id of the last asked question
flow.retry_countThis is the number of times the question was retried (only for mandatory questions)
last_interaction_dateThe datetime of the last received message
creation_dateThe datetime when the conversation started
lead_post_dateThe 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

NameDescriptionOptional
name.valueWill set the visitor name in the chatbot memoryYes
email.valueWill set the visitor email in the chatbot memoryYes
phone.national_formatWill set the visitor phone in national format in the chatbot memoryYes
phone.international_formatWill set the visitor phone in international format in the chatbot memoryYes
customWill 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 objectYes
response.textAn array with the text you want to sent to the user, each element will be a different messageYes
response.response_typeThe expected response type, can be one of: TEXT, LIST, NAME, EMAIL, PHONEYes
response.response_optionsIf the response_type was LIST, this array allows you to specify the possible response options the question.Yes
response.stopChatIf this field is set to true, the chatbot will stop executing the script util the visitor talks againYes
response.flowThis 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.