Documentation

1.Getting Started #

Getting started with Hybrid.Chat is easy. Just goto Pricing page and Signup for a plan that suits your needs. There, you will be prompted with Google or Facebook login. Choose the network you wish to use and you will be directly logged in. All plans come with 30 days free trial, except for FREE tier plan, which is free forever.

2.Creating a Chatbot via spreadsheet #

The chatbot generating spreadsheet should be structured in a particular way for the AI engine to understand what you want the bot to do.

Checkout some example Spreadsheets and their rendered chatbots below:

Simple Live Chat
Demo, Spreadsheet

Lead capture for Local Business
Demo, Spreadsheet

Click to Call Chatbot
Demo, Spreadsheet

Hotel Booking Chatbot
Demo, Spreadsheet

Appointment Booking Chatbot
Demo, Spreadsheet

Car Sales FAQ Chatbot
Demo, Spreadsheet

Recruitment Pre-screening Chatbot
Demo, Spreadsheet

Unsplash API Demo Chatbot
Demo, Spreadsheet

Tax Calculation Chatbot
Demo, Spreadsheet

2.1.ID #

ID is the unique ID of the row and it should increase sequentially. It is composed of one main-id and a sub-id which are both whole numbers and are separated by a dot (.). Eg – 1.1, 3.6 are some valid ID’s.

Note: Some rows like the ones containing synonyms or FAQ question/answer or SendEmail type do not require any ID. But for others it is required and both main-id and sub-id should increase sequentially.

2.2.Type Column #

Type column defines the type of chat widget to load in the sequence. There are multiple types of assets supported and we keep on adding different types as well. Here is a list:

  1. Dialogue – Simple text message
  2. Button – In-chat button that routes to other chatflows
  3. SendEmail – Ability to send chatlog to a special email along with variables (data) collected.
  4. User Input Types:
    1. Text-<var> – Asks for text as input via main Send message text box
    2. Phone-<var> – Asks for phone number as input via Send message text box
    3. Email-<var> – Asks for email address as input via Send message text box
    4. Number-<var> – Asks for a numeric value as input via Send message text box
    5. Date-<var> – Asks for a date as input via Send message text box
    6. URL-<var> – Asks for a URL as input via Send message text box
  5. User Input Widgets:
    1. TextWidget-<var> – Same as Text-<var> but uses an in-chat widget for better chatting experience
    2. PhoneWidget-<var> – Same as Phone-<var> but uses an in-chat widget for better chatting experience
    3. EmailWidget-<var> – Same as Email-<var> but uses an in-chat widget for better chatting experience
    4. NumberWidget-<var> – Same as Number-<var> but uses an in-chat widget for better chatting experience
    5. DateWidget-<var> – Same as Date-<var> but uses an in-chat widget for better chatting experience
    6. URLWidget-<var> – Same as URL-<var> but uses an in-chat widget for better chatting experience
  6. FAQ_Q-<qid> – Used to add potential questions that a user may ask
  7. FAQ_A-<qid> – Used to define answers to the questions mentioned via FAQ_Q-<qid>
  8. Synonym-<word> – Used to define synonyms or words within FAQ for better matching of questions with answers.
  9. Fallback – Jump to a chatflow is typed query didn’t match any of the FAQ.
  10. timeout_agent – Jump to a chatflow if Human agent didn’t answer the chat, is away or offline.

2.3.Goto #

Goto is used to control the flow of conversation. It specifies the main-id of the row from which the conversation will continue after current row is complete (for user’s input/validations etc).

An example could be:

ID Type Text Goto
1.1 Text-DontMatter Hi. I am here to help 2
2.1 Dialogue
Hey there! We’re excited to help you out. Let us know your contact details so that we can follow up in case we get disconnected.
2.2 TextWidget-Contact Best Phone number (recommended) or email address to reach you?
2.3 Dialogue What do you need help with today?
2.4 Button New Booking 6
2.5 Button In-Room Service https://someurl.com/page-for-in-room-service

Here you can see the buttons in last 2 rows have been assigned a Goto, to tell the system where to go in the chat dialogue if a button is clicked. Goto column can also make the user navigate to a certain page at any point of the chat flow. It works well when a URL is defined in the Goto of a Button (as shown in 2.5 row above).

In case of Dialogue, FAQ answer the flow immediately transfers after sending the message to the user but if there are buttons after dialogue then the bot will wait for the user’s response before changing the flow.

In case of Button, the flow will change to the specified main-id when the button’s text is sent by the user as a response. In case of User input types, the bot will wait for the user’s response before going to the specified main-id in goto.

For rest of the types, Goto column will not do anything and will be ignored if specified.

3.Building a Bot #

Building a bot with Hybrid.Chat is as easy as editing a spreadsheet file. Follow the instructions below of just start editing one of the many examples provided on the Bot Builder page.

Getting started with Google Spreadsheets to maintain your bot
Hybrid.Chat makes it easy to edit and maintain a chatbot by letting you edit everything from a cloud hosted CSV file. Google Spreadsheets is one of the programs we actively support right now which would allow you and your team to collaboratively refine and grow your chatbot. This is far better than having a chatbot developer being the only one who can go into the system and do this for you. How the spreadsheet works has been defined below.

3.1.Making bot say something #

Hybrid.Chat can say anything via the means of Text or images. Images can be anything that a browser supports, including animated GIFs and JPEGs, lists, tables or even videos.

3.1.1.Dialogue #

Dialogue is the text which the bot says to the user. Inside the text column you can give the text which you want the bot to message to the user. It has been tested on several languages, including traditional Chinese and it seems to work well.

Example:

ID Type Text Goto
1.1 Dialogue Hi there ! I am news-alert-bot. I can message you latest news alerts throughout the day.  

3.1.2.Adding Images #

Images can be added easily by using Markdown formatting. It can be added using DIALOGUE type. Any type of images that are normally supported by HTML 5 or browsers can be supported within, including JPEGs, Transparent PNGs, or animated GIFs.

Example:

ID Type Text Goto
1.1 Dialogue ![alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png “Logo Title Text 1”)

3.1.3.Chat Button options #

At any time in the chat flow, you can ask the user to choose a button to select one of the paths of the dialogue flow. Buttons let you specify where you wish to lead the conversation via Goto column. You can add as many buttons in a sequence as you like and the bot render all buttons the appear consecutively with each other within one dialogue transaction.

Example:

ID Type Text Goto
1.1 Button Reservations 5
1.2 Button Airport Shuttle 6
1.3 Button Restaurant 7

3.1.4.Formatting Text Messages #

You can format the text messages using Markdown formatting

Bold and Italic

You can make text bold or italic.

*This text will be italic*
<i>This text will be italic</i>
**This text will be bold**
<b>This text will be bold</b>

Both bold and italic can use either a * or an _ around the text for styling. This allows you to combine both bold and italic if needed.

**Everyone _must_ attend the meeting at 5 o'clock today.**

You may also use normal HTML tags for bold and italic for any text.
<i>This text will be italic</i>
<b>This text will be bold</b>

Strikethrough

With the option strikethrough enabled, Showdown supports strikethrough elements. The syntax is the same as GFM, that is, by adding two tilde (~~) characters around a word or groups of words.

a ~~strikethrough~~ element

strikethrough element

Emojis

Since version 1.8.0, showdown supports github’s emojis. A complete list of available emojis can be found here.

this is a :smile: smile emoji

this is a :smile: smile emoji

3.2.Making bot asking a Question #

You can design the bot to ask a question or fill a form at any point of the conversation flow, with the options listed below.

3.2.1.User Input Types #

These are used to take input of a specified type from the user. The text field contains the question to be asked to the user. After asking the question, the bot waits for the user’s response, validates the response and continues the conversation if response is validated or repeats the same question again if response is not valid. The value for this type is of the format <type>-<variable_name>.

Here <variable_name> is the unique name of the variable in which the response of the user is stored. This same variable name can be used further inside any field of Text column.

<type> specifies the type of input expected from the user. type can be any of the following below:

3.2.1.1.Text #

Text – anything typed by user is accepted and (optionally) can be stored into a variable.

Example:

ID Type Text Goto
2.1 Text-Name Hi. My name is TravelBot. What is your name? 4

3.2.1.2.Phone #

Phone – valid phone numbers with country code are only accepted

Example:

ID Type Text Goto
2.1 Phone-number Please enter your phone number to start receiving alerts. (Accepted format: +XX (Country code)(Phone Number) 4

Best practice:
If you receive a lot of local traffic, its best to store phone number as a TEXT rather than a Phone number to avoid validations that can be frustrating.

3.2.1.3.Email Address #

Email – valid emails are accepted

Example:

ID Type Text Goto
2.1 Email-emailaddress Please enter your email address to start receiving alerts. 4

 

3.2.1.4.Number #

Number – any number entered by user is accepted

Example:

ID Type Text Goto
2.1 Number-guests Please enter the amount of guests who would be checking in 4

3.2.1.5.Date #

Date – only valid dates are accepted

Example:

ID Type Text Goto
2.1 Date-CheckinDate And when would you like to checkin? (Accepted format: MM/DD/YY)  

Best Practice:
Its best to use DateWidget instead of date to avoid user side errors for formatting issues.

3.2.1.6.URL #

URL – valid URL’s are accepted

Example:

ID Type Text Goto
2.1 URL-resumeurl Please enter your Linkedin URL or a link to your resume / CV 4

 

3.2.2.User Input Widgets #

Just like User Input types mentioned above, but loaded in user friendly widgets. Each of the input type has a corresponding input widgets which are shown as a special floating dialog inside the chat message window. Like an example EmailWidget is shown below.

As with other input types, the value for this type is of the format <type>Widget-<variable_name>. Here <variable_name> is the unique name of the variable in which the response of the user is stored. This same variable name can be used further inside any field of Text column.

<type> specifies the type of input expected from the user. type can be any of the following below:

3.2.2.1.Text Input Widget #

TextWidget – anything typed by user is accepted and (optionally) can be stored into a variable.

Example: 

ID Type Text Goto
2.1 TextWidget-Name Hi. My name is TravelBot. What is your name?  
 

3.2.2.2.Phone Input Widget #

PhoneWidget – valid phone numbers with country code are only accepted

Example: 

ID Type Text Goto
2.1 PhoneWidget-number Please enter your phone number to start receiving alerts. (Accepted format: +XX (Country code)(Phone Number) 4

Best practice:
If you receive a lot of local traffic, its best to store phone number as a TEXTWIDGET rather than a Phone number to avoid validations that can be frustrating. A similar widget may look something like this:

3.2.2.3.Email Address Widget #

EmailWidget – valid emails are accepted (optionally) with the support to store that in a variable.

Example: 

ID Type Text Goto
2.1 EmailWidget-emailaddress Please enter your email address to start receiving alerts.  

 

 

3.2.2.4.Number Input Widget #

NumberWidget – any number entered by user is accepted

Example: 

ID Type Text Goto
2.1 NumberWidget-guests Please enter the amount of guests who would be checking in

3.2.2.5.Date Input Widget #

DateWidget – only valid dates are accepted

Example: 

ID Type Text Goto
2.1 DateWidget-CheckinDate And when would you like to checkin? (Accepted format: MM/DD/YY)  

The date widget actually loads a complete calendar component within the chat, supported by browser’s inbuilt validations.

3.2.2.6.URL Input Widget #

URLWidget – valid URL’s are accepted

Example: 

ID Type Text Goto
2.1 URLWidget-resumeurl Please enter your Linkedin URL or a link to your resume / CV  

 

 

3.2.3.Set Variable Values #

Chatbot can set variables and its values at any time of the chat flow. It comes handy when you have to pass specific variables and values into Webhooks or API calls you make via Chatflow, or store the user button choices somewhere for later use.

ID Type Text Goto
SetVariable-LoanChoice Home Loan

Optionally, you can also specify the type of the variable to be set. By default if no type is specified in SetVariable, it assumes “text” type. The valid types supported are date and number. Date can be used to manipulate the date and store it as string in the desired format. Example:

ID Type Text Goto
SetVariable-start_date-date Date=today,format=YYYYMMDD

Number can be used to do any arithmetic operation on variables and store the result in a new variable. Example:

ID Type Text Goto
SetVariable-num-number ({{vars.num}}+1)*2

 

 

3.2.4.Pass Variables as Parameters #

Variables can also be set by passing them as URL Parameters or Embed Parameters.

 

1. Passing Variables as URL Parameters

If the URL of your bot is “https://botId.hybrid.chat”, and you have to pass a variable name whose value is somename, then you can pass URL parameters as

https://botId.hybrid.chat/chat.html?name=somecoolname

If parameters are more than one, then simply append them with an &.

https://botId.hybrid.chat/chat.html?name=somecoolname&age=22

 

2. Passing Variables as Embed Parameters

Suppose you have embed code for your bot as follows

<div id="embed">
  <script src='https://app.hybrid.chat/scripts/welcome.js'>
  </script>
  <script>
    welcome('botId' , 'hybrid.chat', {"loadHistory": false});
  </script>
</div>

Then, simply pass the parameters as an object with the following structure

"vars": {
  "name": "somecoolname",
  "age": "22"
}

For eg.

<div id="embed">
  <script src='https://app.hybrid.chat/scripts/welcome.js'>
  </script>
  <script>
    welcome('botId' , 'hybrid.chat', {"loadHistory": false,
    "vars": {"name": "somecoolname", "age": "22"}});
  </script>
</div>

3.2.5.Answers your bot already knows #

There is a lot that your bot already knows about a person you are chatting with. These are published as Global variables that you can call like other variables you define within the chat. Besides knowing more about to whom you are talking to, you can use the same variables within your chatflow dialogue or pass this to webhook for further transactions. Here is a list of these global variables:

Variable How to call in chat flow Example format
IP Address vars.GLOBAL.ip 111.111.111.11 (IPv4) OR 2001:0db8:0000:0042:0000:8a2e:0370:7334 (IPV6)
IP Type vars.GLOBAL.type ipv4 or ipv6
Country Name vars.GLOBAL.country_name United States
Country Code vars.GLOBAL.country_code US
Region Name vars.GLOBAL.region_name California
Region Code vars.GLOBAL.region_code CA
City Name vars.GLOBAL.city Los Angeles
Zip Code vars.GLOBAL.zip 90001
Latitude vars.GLOBAL.latitude 11.0123
Longitude vars.GLOBAL.longitude 22.0123
Continent Name vars.GLOBAL.continent_name North America
Continent Code vars.GLOBAL.continent_code NA
Geoname ID vars.GLOBAL.location.geoname_id 5368361
Capital vars.GLOBAL.location.capital Washington D.C
Language* vars.GLOBAL.location.languages.0.name English
Native Language vars.GLOBAL.location.languages.0.native English
Language Code vars.GLOBAL.location.languages.0.code en
Country Calling code vars.GLOBAL.location.calling_code 1
Timezone Name vars.GLOBAL.time_zone.id America/Los_Angeles
Current Time vars.GLOBAL.time_zone.current_time 2018-03-29T07:35:08-07:00
Timezone code vars.GLOBAL.time_zone.code PDT
Country currency vars.GLOBAL.currency.name US Dollar
Currency code vars.GLOBAL.currency.code USD
Currency in Plural vars.GLOBAL.currency.plural US Dollars
Currency Symbol vars.GLOBAL.currency.symbol $
Native Currency Symbol vars.GLOBAL.currency.symbol_native $
Current URL  vars.GLOBAL.bot_url  https://yourdomain.com/somepage.html

* This is an array and more languages may appear, which can be accessed by incrementing the ordinal in the end.

In case you are building a Facebook bot, some of these variables are available to you via Facebook, as soon as user initiates a chat:

Variable How to call in chat flow Example format
First Name vars.fb_user.first_name John
Last Name vars.fb_user.last_name Wick
Profile Picture URL vars.fb_user.profile_pic https://someurloffacebook.com/
Gender vars.fb_user.gender male or female
Locale vars.fb_user.locale Locale of the user on Facebook. Example: en_US. For supported locale codes, see Supported Locales.
Timezone vars.fb_user.timezone Timezone, number relative to GMT. Example -7 or 5.5
Page Specific User ID vars.fb_user.id The user’s PSID

Read more about these available fields here.

4.Chat Intelligence #

You can make your bot react differently to different responses it gets from the users. This makes the bot sound a lot smarter. 

4.1.If response is #

Parsing responses is easy and is supported by following tags:

  1. Response-case_insenstive_match
  2. Response-exact_match
  3. Response-regex_match
  4. Response-intent_match
  5. Response-less_than
  6. Response-less_than_equal_to
  7. Response-greater_than
  8. Response-greater_than_equal_to
  9. NoResponse-<seconds>

Response-case_insenstive_match
Like the name suggests, it matches the user response without considering the case of the text (if it is capital or small).

ID Type Text Goto
Response-case_insenstive_match hi, hello, hola, namaste, I am here, I am here now, I am back 10

Response-exact_match
This tag would trigger only if the user response EXACTLY matches the string you define next to it in Text column.

ID Type Text Goto
Response-exact_match SecreT 11

Response-regex_match
This tag would trigger only when the user response matches the REGEX pattern provided in the Text Column. This is useful to parse anything from email address to ETH Wallet address.

ID Type Text Goto
Response-regex_match .* Human

Response-intent_match
This tag would trigger only if the user response matches the intent_name trained using the Intent type. The intent_name is to be given in the Text column.

ID Type Text Goto
Response-intent_match greeting 1

Response-less_than (less_than_equal_to, greater_than, greater_than_equal_to)
This tag would trigger only if the user response is of type number and it is less than (less than equal to, greater than, greater than equal to) the number given inside the Text column.

ID Type Text Goto
Response-less_than 10 1

NoResponse-<seconds>
This tag is triggered if there is no response from the user for X seconds (defined right after the tag).

ID Type Text Goto
NoResponse-15 11

4.2.If variable is #

Just like we parsed the Response using the various Response-<match_criteria> tags. We can also change the flow of conversation based on the value of some variable at any point inside the spreadsheet. For this, the IF type is used. Its format is IF-<var_name>-<match_criteria>. The <var_name> is the source variable whose value is matched with the value given in the Text column using the <match_criteria>. Like Response, the match_criteria can be:

  1. exact_match
  2. regex_match
  3. case_insenstive_match
  4. intent_match
  5. less_than
  6. less_than_equal_to
  7. greater_than
  8. greater_than_equal_to

If the match is successful, it goes to the thread_id mentioned inside the Goto column of that row. Otherwise it continues the conversation from the next row. If the match_criteria is omitted, then it checks for the truth value of the variable i.e. the variable’s value is not false, null, undefined, empty etc. If it is not falsey value, it goes to the thread_id mentioned inside the Goto of that row. If both the variable_name and match_criteria are omitted, it simple goes to the thread_id mentioned in the Goto column of that row. So, this can be used as an ELSE condition inside the spreadsheet.

Example:
Suppose a variable input is defined using SetVariable or otherwise.

ID Type Text Goto
IF-input-case_insenstive_match yes, yup, yeah 10
IF 11

 

4.3.Performing calculations #

You can perform basic calculations within your chatbot easily. Just use SetVariable to do the same. See this example chatbot that does calculations:

Tax Calculation Chatbot
DemoSpreadsheet

4.4.Schedule #

Schedule can be used to schedule messages to be sent by the bot at any time in the future. Currently, Schedule works in SMS bot only. Using schedule you can specify the Date when to schedule message, manipulate the date and specify the Goto from where the conversation will be initiated by the bot. Schedule takes various parameters which include:

  1. Date – Date when to schedule message in format YYYY-MM-DD HH-mm-ss, e.g 2019-01-22 12:33:12
  2. Year – To set, increment or decrement the year relative to the Date specified earlier. Year can be given values 2019 (to set year), +2 (to increment by 2 years) and -1 (to decrement) etc.
  3. Month – Similar to year, it can be used to set, increment or decrement the months.
  4. Day – To set, increment or decrement days
  5. Hour -To set, increment or decrement hours
  6. Minutes – To set, increment or decrement minutes
  7. Seconds – To set, increment or decrement seconds
  8. Timezone – Timezone (UTC offset ) in which to interpret the date.

Example

ID Type Text Goto

Schedule-Date={{vars.Checkin}},Hours=8,Minutes=30,Timezone=+0530

5

 

4.5.Fallback #

Fallback is a special type which is used to define the id of the row from which conversation will continue if bot does not know how to respond. This happens when user types message which is not the text of any button shown with the dialogue and neither it is an FAQ question. In such case, the bot does not know what to say next. In the Goto column of fallback type, the id of row can be defined from where to continue the conversation in such case.

Example:

ID

Type

Text

Goto

6.1

Dialogue

Sorry, I did not understand.

1

 

fallback

 

6

Recommended:
Fallback can be used to connect to a human if the bot couldn’t understand any input from the user.

4.6.Agent Timeout #

timeout_agent – The format for this type is timeout_agent-<X seconds>. It is also a special type which is used to define the id of the row from which to continue conversation if human agent does not respond for past X seconds. Once the bot has connected to a Messaging Platform, it will observe for X seconds whether human has responded or not. If not it will continue the flow from the ID specified in the Goto column in this row. Now if anytime human agent responds, bot will stop its normal flow and human agent will complete the conversation. If it has, then bot will not do anything and human agent will manage the rest of the conversation.

Example:

ID Type Text Goto
7.1 Dialogue Seems like all agents are busy right now. We promise to contact you as soon as possible. 🙂 1
timeout_agent-10 7

 

4.7.Intent #

Intents can be trained using the Intent type. It’s format is Intent-<intent_name>. In the text column you an specify the examples (new line separated) to be trained in that intent. The goto column can be used to specify an ID which is called when the intent matches the user response at any point in conversation. Intent can also be used with the Response-intent_match type. When Response-intent_match is specified, the flow of conversation goes to it’s goto instead of the goto specified in Intent-<intent_name> type.

Example:

ID Type Text Goto
Intent-greeting
hi
hello
hey
heya
1
Intent-end
bye
later
bye bye
talk later
see you
see ya
not interested
 10

4.8.FAQ Chatbot #

The format for this type is FAQ_Q-<qid>, FAQ_A-<qid> for question and answer respectively. For FAQ_Q type, in the text field you can specify the actual question which the user can ask anytime during the conversation. qid is the unique ID of the question. The corresponding answer can be given in the text field of FAQ_A type row. 

Note that qid is different from the ID in the ID column and can be anything.

By having multiple FAQ_Q rows with the same qid, you can specify different variations of asking the same question. Similarly if multiple FAQ_A rows are specified with the same qid, bot will randomly select an answer and give it as response to the user.

Example:

ID Type Text Goto
FAQ_Q-1 What can you do ?
FAQ_Q-1 Who are you ?
FAQ_A-1 I am news-alert-bot. I can message you latest news alerts throughout the day. 2
FAQ_Q-2 I would like to talk to a human
FAQ_Q-2 Human please
FAQ_Q-2 Human 2
FAQ_Q-2 Talk to a Human 2
FAQ_A-2 Connecting to a human. Please stay online. Human

4.9.Synonyms #

Synonyms can be used to improve upon the accuracy of the FAQ part of the chatbot. It is used to specify the synonyms of a word. It’s format is Synonym-<word>. In the text field you can specify the comma separated synonyms of the word. By training the synonyms of a word, variations of the FAQ question (asked by the user) which contains the synonym instead of actual word are also matched (with the question trained by the bot creator). So, bot is able to give answer to these questions too.

Example:

ID Type Text Goto
  Synonym-human human,agent,person,real person,real human, someone real  
  Synonym-booking booking,reservation,accommodation,book a room,book an accommodation  

 

4.10.Ending Chat Conversation #

At times, you just need to end the chat session at an appropriate time to ensure the user can reinitiate the session again. In just case, just use ‘End’ tag in Goto and the bot would end the session and stop talking. 

ID Type Text Goto
5.4 Dialogue Alright. Thanks for connecting with us today. End

4.11.Connecting to Human Agent #

This one is similar to Goto as mentioned above, but instead of a number, you can just write HUMAN.

This basically transfers the flow to the hybrid chat client which is enabled while creating the bot. The logs of the bot’s conversation are sent as the first message. After that the bot stops and the communication happens directly between the customer and the human agent.

Example:

ID Type Text Goto
5.1 Dialogue Alright. Please stay online while I transfer to a Human agent Human

 

 

 

5.Connecting to External Services #

Hybrid.Chat allows you to communicate data outside the chatflow or move things around in various ways.

5.1.Send Email #

SendEmail as the name suggests will send the email to the bot’s creator (to the email entered while creating the bot). As soon as the flow of conversation reaches SendEmail, an Email is sent with the logs of the chat before that point. The user can customize the subject of the email by specifying the same in the Text column. The text field can contain the variable_name (2.4.1) as in the case of Dialogue (explained in 2.1.1).

Note: An email is also automatically sent with the logs when the conversation times out (10 mins after user has not interacted with the bot.)

Example:

ID Type Text Goto
5.1 Dialogue Thank You ! You will start receiving alerts soon.
SendEmail New Phone Number: {{vars.number}}

 

5.2.Send SMS #

Your chatbot can send text message (SMS) to any phone number in the world at any step of the chat flow. As soon as the flow of conversation reaches SendSMS, An SMS is sent using Twilio Telephony service.  When you create an SMS bot or Web bot that uses SMS, Bot builder will automatically ask you for Twilio Credentials (Account SID and Auth Token, you can get these here). 

Example:

ID Type Text Goto
5.1 Dialogue Thank You ! You will start receiving alerts soon.
SendSMS-<Your_Twilio_Phone_no>-<Target_Phone_no> Sample SMS Message
SendSMS-+12223334444-+19998887777 Sample SMS Message

You can also use a variable value captured by the bot to send an SMS too (if you are trying to send SMS to the person who is chatting with the bot. It will go like this:

Example:

ID Type Text Goto
5.1 Dialogue Thank You ! You will start receiving alerts soon.
SendSMS-<Your_Twilio_Phone_no>-{{vars.Phone_captured}} Sample SMS Message
SendSMS-+12223334444-{{vars.Phone_captured}} Sample SMS Message

Note:
1. It is important to mention the phone number you have already bought in your Twilio Account to let Twilio make this call. If you have not bought one, you can buy one here.

5.3.Make a Phone Call #

Chatbots can create a telephonic conference call between 2 or more phone numbers. As soon as the flow of conversation reaches ‘Conference’, a conference call is created using Twilio Telephony service.  When publishing your bot that uses ‘Conference’ tag for the first time, Bot builder will automatically ask you for Twilio Credentials (Account SID and Auth Token, you can get these here). 

Example:

ID Type Text Goto
5.1 Dialogue Connecting you with someone is staff. You will get a phone call now.
Conference-<Your_Twilio_Registered_Phone_no> “<Phone number 1>”,”<Phone number 2>”
Conference-+12223334444 “+14445556666″,”+17778889999”

You can also use a variable value captured by the bot to create a conference call, if you are trying to create a conference call with to the person who is chatting with the bot. It will go like this:

Example:

ID Type Text Goto
5.1 Dialogue Connecting you with someone is staff. You will get a phone call now.
Conference-<Your_Twilio_Registered_Phone_no> {{vars.Phone}},”<Phone number 2>”
Conference-+12223334444 {{vars.Phone}},”+17778889999″

Note:
1. It is important to mention the phone number you have already bought in your Twilio Account to let Twilio make this call. If you have not bought a Twilio Phone number yet, you can buy one here.
2. Make sure the Voice Conference Call settings are Set to Agent Conference (Default is Twilio Conference). You can set it here.

5.4.Webhooks & API Requests #

SendRequest can be used to send a new webhook request to any url or fetch data from an API call. As soon as the flow of conversation reaches SendRequest, a new request is sent with the text column as the body of the request. The method of request can be GET or POST. The format for this type is SendRequest-<method>-<url>. Here the method can be GET or POST and the url is the webhook url which is listening for requests. The server must send a 200 response to the request. Otherwise the request will be retried again. The request is retried for a maximum of 3 times in 1 minute intervals.

Example: SendRequest-GET-https://your-webhook-url.com/path

The ID and Goto are not required in the SendRequest row. The text column can be used to specify the header, body of the request as well to save the response in a variable. The format of text column is a JSON object which has “body” as a key in whose value (can be JSON) is sent as body of request, a “headers” key which is a JSON object containing the header key/value pairs and a “save_to_var” key inside which a variable name can be specified in which the response is saved. The response is also saved as a JSON object whose keys are “statusCode”, “body” and “headers” of response.
Note, the text column can contain any of the variables which are populated before sending the request. The same is true for the query params inside url too. Inside url too, any variables captured during chat can be included. One common use case is to send the variables as JSON in the text column which can be processed further. An example of this is given below.

Example:

ID Type Text Goto
5.1 Dialogue Thank You ! you will start receiving alerts soon.
SendRequest-POST-https://webhook.com/catch {“headers”: {“Authorization”: “Basic token_here”}, “body”: {“phone”: “{{vars.number}}”}}

Here is a sample Chatbot spreadsheet that uses SendRequest

5.5.Database Queries #

You can use QueryDB command within Chat flow to connect to any SQL database and perform a database query to inject within Dialogue text or other widgets available to you. Only MySQL database connection is supported for now, while we are working on other types of DB connections.

  QueryDB {“name”: “mysql“, “config”: {“host”: “hostname_comes_here“, “user”: “Username_of_db“, “password”: “password_of_db“, “database”: “database_to_connect_to“}, “query”: “SQL query comes here“, “format”: “row_or_column“, “save_to_var”: “variable_to_save_response_to“}

Parameters:

  1. name: Lets you define the name of database management system (DBMS) your chatbot needs to connect to.
    1. config: Helps you define the database connection details
      1. host: Database hostname comes here
      2. user: Database username
      3. password: Database password
      4. database: Database within the DB server to connect to
    2. query: You may type in the exact SQL query to be performed in this parameter. All the variables asked by the chatbot or global variables are available to you that can be used here.
    3. format: Specifies if the data needs to be read in row or column format. Generally, databases exist in row format, which is what you would be using most of the time.
    4. save_to_var: Name of the variable in which you wish to store the query response. Use these variables to call in any part of the chatbot conversation.

Here is a sample spreadsheet that Queries a MySQL Database for Chatbot.

6.Advanced chatbot functions #

Chatbot can support some pretty advanced features with the help of simple spreadsheet as well.

6.1.Embedding external Wigets #

You can embed external widgets within your website chat easily with your chatbot flow. Hybrid.Chat will load anything that can be loaded into an <iframe>. Maximum size supported for EmbedWidget is 350 px X 500 px.

Example:

ID Type Text Goto
2.1 EmbedWidget <iframe src=” URL comes here “></iframe> 4

Sometimes, you need more space than what is possible to fix into 350 x 500 px space. So, there is an another form of EmbedWidget which you can use to utilize the complete screen’s real estate.

Example:

ID Type Text Goto
2.1 EmbedWidgetMaximize <iframe src=” URL comes here ” width=”100%” height=”500px”></iframe> 4

Expert Tip:
You can also pass variables into the widgets to make them look more intelligent and pre populate all the information you already know. Some widgets support this quite well that you may want to use. See section 2.2.2 of this documentation for more details on variables.

6.3.LoadData #

As the name suggests, this command can be used to access data in a sheet in same spreadsheet where your chatbot exists or a different spreadsheet altogether. A use case could be to host a calculator within spreadsheet and let chatbot return the values, or there are gazillions of plugins that feed data into Google Spreadsheet, that you can access easily and create a chatbot that uses that data.

  LoadData
{“from”: {“type”: “spreadsheet“, “config”: {“url”: “url_of_spreadsheet“, “sheet_name”: “sheet_name_comes_here“}, “range”: “A1:G5.0.1“, “headers”: 1 or 0, “format”: “row_or_column“}, “save_to_var”: “variable_to_load_data-in“}

Parameters:

  1. from: Lets you get data from multiple sources, shall there be a requirements. So, suppose you can get some data from a spreadsheet and some from a remote database
    1. type: Lets you define the type of data source it is. Supported formats are spreadsheet (Supports any Google spreadsheet) for now. More formats are coming soon
      1. config: Helps you to specify the path of the spreadsheet and name of the sheet that you need to access
        1. url: You can specify url of an another Google spreadsheet here. If the sheet already exists within your chatbot spreadsheet, just say “this”
        2. sheet_name: Specify the name of the sheet from where data should be sourced
      2. range: Specify the range of cells (in spreadsheet above) from where data needs to be sourced. A range is defined by the reference of the upper left cell (minimum value) of the range and the reference of the lower right cell (maximum value) of the range. The notation for this range is (A1:C6).
      3. headers: Specify if data has a header row or not. Accepted values are 0 (for No headers) and 1 (for headers in first row).
      4. format: Specifies if the data needs to be read in row or column format. Generally, spreadsheets exist in row format, which is what you would be using most of the time.
    2. save_to_var: Name of the variable in which you wish to load the data. Use these variables to call in any part of the chatbot conversation.

Here is a sample Chatbot spreadsheet that uses LoadData

6.4.Inserting variables inside text #

variables in text – The message can be formatted to include the value of variable_name (2.4.1). This is helpful if we want to confirm the input entered by the user in any variable or if we want to display the details entered by the user, at the end. The format to include variable is {{vars.<variable_name>}}. eg. if the Text field contains “You entered {{vars.input}}”. The bot will replace the {{vars.input}} with the actual value of the variable input before sending the message to the user.

Example:

ID Type Text Goto
1.1 TextWidget-Name Hi. My name is BotGenuis. What’s yours?
1.2 Dialogue Hello {{vars.Name}}, Nice to meet you. 2
2.1 Dialogue What would you like to do today?

If the variable contains a data array, you can use index to load row and column of the data array to pin point a specific data point. Index can be specified like this: variable_name.0.1, where 0 is row and 1 is column number.

Here is a sample chatbot spreadsheet that uses variables within the text. Here is another that loads a data array within the text.

Carousel:

  • To render HTML inside Carousel, use jsonEscape and removeHtml functions. For eg., say a variable var1 contains HTML, then use{{#jsonEscape}}{{#removeHtml}}{{{vars.var1}}}{{/removeHtml}}{{/jsonEscape}} to render it properly.
  • If a variable contains a URL, then use triple curly braces ({{{}}}) instead of double curly braces ({{}}) to unescape the URL characters. For eg., if var1 is a URL to an image, then write it as {{{vars.var1}}} for the URL to load properly.

6.5.Changing the typing indicator #

Typing indicator of the bot can be changed using CSS. By default, bot shows this typing indicator –

1. Show <agent name> is typing …

Step 1: In the chat window CSS, find the selector .typing-indicator and set the display to none

.typing-indicator {
    display: table;
    margin: 0 auto; /*chatbox typing indicator margin*/
    position: relative;
  }

Step 2: Add the following CSS

.typing-indicator-agent {
    display: table;
    font-size: 12px;
    color: gray;
    font-style: italic;
  }

  .typing-indicator-agent:after {
    content: ' .';
    animation: dots 1s steps(5, end) infinite;
  }
  
  @keyframes dots {
    0%, 20% {
      color: rgba(0,0,0,0);
      text-shadow:
        .25em 0 0 rgba(0,0,0,0),
        .5em 0 0 rgba(0,0,0,0);}
    40% {
      color: gray;
      text-shadow:
        .25em 0 0 rgba(0,0,0,0),
        .5em 0 0 rgba(0,0,0,0);}
    60% {
      text-shadow:
        .25em 0 0 gray,
        .5em 0 0 rgba(0,0,0,0);}
    80%, 100% {
      text-shadow:
        .25em 0 0 gray,
        .5em 0 0 gray;}
      }

After this, typing indicator will look like this

2. Showing a loading GIF

Step 1: In the chat window CSS, find the selector .typing-indicator and set the display to none

.typing-indicator {
    display: table;
    margin: 0 auto; /*chatbox typing indicator margin*/
    position: relative;
  }

Step 2: Add the following CSS

.typing-indicator-agent {
    display: table;
    font-size: 12px;
    color: transparent;
    font-style: italic;
    background-image: url()
  }

After this, typing indicator will look like this

7.Contact Manager #

Contact Manager allows you to add/edit/delete contacts. Bots can be initiated with these contacts with a single click.

A contact has 5 fields – nameemailphonetags, and metadata. Some guidelines on these fields –

  • The phone number should be entered with country code, without spaces, brackets, hyphens or any other special symbol. Only + is allowed at the beginning of country code.
  • The tags field is supposed to have a list of tags. These tags work as a label to categorize a contact into a certain group. For example, all of the contacts which are potential leads can have a Lead tag in them. This tags can be used to filter contacts or for setting up Contact Triggers which will be explained further.
  • To add tags, type in a tag and then press Enter. A tag will be added in the same input box.
  • Metadata should be a JSON object, containing any extra fields that you want to keep.

To add a new contact – 

Step 1: Goto Hybrid.Chat Contact Manager

Step 2: To add a new contact, click the plus symbol on the top right corner.

Step 3: A form will appear on the bottom right part of the screen which looks something like this.

Step 4: Below is how a filled form looks. Please follow the field guidelines given above.

Step 5: Click on the Submit button. The contact will be added and will appear on the contact manager screen.

To edit a contact –

Step 1: Tick the checkbox of the contact you want to edit. Only one contact can be edited at once.

Step 2: Click on the edit button on the top right corner.

Step 3: Make changes in the form and then click on Submit to save your changes.

To delete a contact –

Select the contacts you want to delete. Multiple contacts can be selected at once for this operation. After that click on the delete button and confirm your action.

7.1.Import Contacts via Webhook #

The contact manager allows you to import contacts from an external data source via webhooks. To import contacts, you need the Webhook URL and API Secret.

Following are the steps to import contacts from an external source –

Step 1: Go to Contact Manager page and get the Webhook URL.

Step 2: Click on the Generate Secret button. It will take you to your account settings page.

Step 3: Click on Generate button to generate your API Secret. It will appear in the API Secret field left of the button.

Step 4: Now that you these, you can use the Webhook URL to receive data from an external source. Make note of the following points –

  • The method used for invoking webhook should be POST.
  • Include this header in your request – “Authorization: Bearer YOUR_API_SECRET
  • Make sure the request body is in the following format –

 

{
  "contact": {
    "name": "CONTACT_NAME",
    "email":  "EMAIL",
    "phone": "PHONE_WITH_COUNTRY_CODE",
    "tags": ["Tag1", "Tag2"],
    "override_tags": "true",
    "meta": {
      "Country": "USA",
    }
  }
}
  • The “override_tags” field is optional. If you receive a contact multiple times with a change in status/some_other_info and want to append any new info to tags, then set this value to “false”. Setting it to “true” will override all previously existing tags for the same contact. This parameter can be ommitted. It’s default value is false.
  • Any extra fields can be included inside the “meta” field.

7.2.Tags and Triggers #

Tags and Triggers help you initiate a chatbot automatically with a webhook (which can be tied to your CRM, Phone Contact update, Incoming calls, Emails or anything you like).

Every contact can have a tag assigned to it, which when defined in a trigger, can trigger a bot immediately with the contact. To define triggers, just goto Triggers in your account, Add a Trigger

And Define Trigger name, Tag it should be expecting, and Bot it should trigger.

Next time, whenever webhook adds a contact with a particular trigger, the set bot would invoke and start interacting with your contact immediately.

Note: Triggers are available for SMS bots only for now.

8.Connecting with Slack #

Connecting to Slack is easy, and can get you started within minutes. Here is how to go about it.

Expert Tip: You can optimize Slack mobile app for Live chat conversations easily. Follow these mobile notification settings and some special settings for Android.

Step 1: Goto Hybrid.Chat Dashboard and Create a New Bot

Step 2: After filling all the bot details, you will get an option to Connect to Messengers. Click CONNECT next to Slack

Step 3: Authorize Hybrid.Chat to connect to your Slack Workspace

Step 4: Select the users that will invited to Slack Chatrooms created by Hybird.Chat. Just start typing and Hybrid.Chat will try to autocomplete the username for you. Once you are done, click CONFIRM

Step 5: Publish your Bot by clicking CREATE BOT or UPDATE BOT

9.Connecting with Mattermost #

Connecting to Mattermost is easy, and can get you started within minutes. Here is how to go about it.

Step 1: Enable Personal Access Tokens in System Console -> Custom Integrations

Step 2: Assign appropriate permissions to the Bot User.

Hint: If you are confused on what user group to assign to the Bot user, just give Administration permissions so that you can test the working first and scale down the permissions later, if required.

Make sure the roles look like in above.

Step 3: Goto Hybrid.Chat Dashboard and Create a New Bot

Step 4: After filling all the bot details, you will get an option to Connect to Messengers. Click CONNECT next to Mattermost

Step 5: This is where you add in Mattermost access details.

Hostname: The URL where Mattermost is hosted
Username: Enter the username that will be used by Hybrid.Chat to login into Mattermost
Password: Password for the username above

Hint: You may create new account, specially for bot user.

Step 6: Select the Mattermost team where you want all chats to appear. You may create a dedicated team room, just for website chats, shall you wish. Just start typing and the teams that are accessible to this username (that you added in Step 3) would appear.

Note: The bot user must be a member of the selected team.

Step 7Select the users that will invited to Mattermost Chatrooms created by Hybird.Chat. Just start typing and Hybrid.Chat will try to autocomplete the username for you. Once you are done, click CONFIRM

Step 8: Publish your Bot by clicking CREATE BOT or UPDATE BOT

10.Publishing a Facebook bot #

Step 1:
Choose Facebook as publishing platform from bot builder page. It will ask you for Page Access token.

Step 2:
Goto Facebook Developer Dashboard and create an new app. It will navigate to ‘Add Product’ page.

Step 3:
Click on Messenger Setup button

Step 4:
Select the page you wish to connect your bot to and generate its token (You may Create a new page, if required) . Paste this token in the Hybrid.chat configuration window.

Step 5:
Now, its time to setup webhooks. Click on Setup Webhooks button (just below page token).

When you generate facebook bot via Bot builder, Hybrid.Chat would give you Webhook callback URL and verify token.

You you can paste here. Along with that, check the following permisisons to enable the bot.

Press ‘Verify and Save’

Final Step: After setting the webhook, it will allow you to choose which page to hook it up with. Choose the page where you wish to setup your chatbot.