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

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.


Did this page help you?