Onboarding Bot

Walkthrough Level: Advanced

Filling out a website form is soooo 2000s.

Bots make great vehicles to not only communicate information, but also to collect user input, which can be later accessed in the format that best meet your team's needs.

Consider using a bot to conduct a customer service feedback survey, to collect RSVPS for an event, to register emails for a mailing list, to inquire on product quality... the possibilities are endless!

Sign me up


This Onboarding Bot walkthrough will show you how to create a bot that will collect information on a new employee and add it to an existing Employee Directory.

This bot will introduce a few unique concepts that we haven't touched in other walkthroughs before:

In this exercise, we'll be using Airtable, a platform to create and organize your own spreadsheet-database hybrids. To follow along with this tutorial, you may need to create an account on Airtable.


Welcome to the team!

Congrats, it's your first day on the job! 🎉

Before we can get started, we'll just need you to answer a few fun questions, like...

How do I frame this question?

There are many ways to organize a bot that will capture question responses, but Dexter's recommended method is to split each question into a separate topic. How might we do this?

  1. Create a new topic for each question.
  2. Within each topic, include a single wildcard trigger.
  3. The response for this wildcard trigger will store any incoming user input to a variable.
  4. After setting this variable, you could:
    • (optionally) include some text that references the answer from the previous question,
    • then prompt the user to answer the next question,
    • before finally redirecting the user to the topic for the next question.

See this in action in the example below:

> topic default
+ *
- Hi, welcome to Dexter! We're so happy that you'll be joining us. We'll just need a few things to add you to the Employee Directory. <send> First off, what's your full name? {topic=name}
< topic
 
> topic name
+ *
- <set name=<star>> Nice to meet you, <get name>! Which team will you be joining? ^buttons(Engineering, Design, Product Management, Business Development, Sales) {topic=team} 
< topic
Wait, I changed my answer...

We get it, sometimes people give an answer before they fully understand the question.

Consider adding a confirmation question at relevant points in your bot to make sure that the data you've saved to a bot variable has been accurately captured:

> topic name
+ *
- <set name=<formal>> Nice to meet you, <get name>! That is your name, right? ^buttons(Yes, No)
 
+ no
- No? What is your name then?
 
+ yes
- Great! Next, tell us what team you'll be joining! ^buttons(Engineering, Design, Product Management, Business Development, Sales) {topic=team} 
< topic

Now, when a user types back "My name is John", the user will have another chance to change their name from "My name is John" to just "John". You may even consider including a trigger that captures for popular ways to introduce themselves by name, like so:

+ [my name is|i am called|call me|i am|they call me] *
- <set name=<formal>> Nice to meet you, <get name>! That is your name, right? ^buttons(Yes, No)
Tips for Saving Answers
Formal Capitalization

You might have noticed that instead of using <star> in the above example, we used <formal>. Using the <formal> tag allows us to take the wildcard stored in <star>, which is automatically converted to lowercase, and apply capitalization rules to it.

Now, if Abraham Lincoln were to use this bot, his <formal> name would appear as Abraham Lincoln and not abraham lincoln.

Punctuation!?$#%...

We also recommend adding a # punctopic nostrip to the top of your bot script. Why? You may recall that we strip out all the punctuation the user types to the bot so that something like "HEY YOU!!!" will match to the same trigger as "hey you.".

However, this won't do if we're looking to capture content like email addresses, which commonly have punctuation. Now you can safely save <set email=<star>> without worrying you'll capture a value like dummytest@emailcom.

Adding to the Employee Directory

After directing the user through multiple questions, we'll finally run out of questions to ask. Now it's time to save all that data we've been keeping in bot variables to somewhere a little more permanent.

That's where our $ syntax for API requests come in.

Dollar sign

Dexter allows your bot to make API requests from within the bot script. It is easy to pass in bot variable values as query parameters or within the request body of your call.

But first... in the topic for our final question which is named "birthday", we do a final topic redirect to the "addtotable" topic where we have a "post_request" trigger which will kick off an API request.

> topic birthday
+ *
- > 🎂 We can't wait to celebrate with you! {topic=addtotable} {@ post_request}
< topic
Our Employee Directory Spreadsheet

In this example, our employee directory will be a simple spreadsheet on Airtable, which offers an easy platform for organizing database data with a variety of different templates. We'll be using their template for an Employee Directory, with a few slight modifications (i.e. removing Social Security #).

You can see the sample "Employee Directory" here, this is not our real one! 😉

Not our real employee directory

The very well-documented Airtable API will teach you how to make requests for whichever template / Base you use with your bot.

For the purposes of our bot, we want to simply add a record to the existing Employee Directory. Since this is an edit to the existing database, we will be doing a POST request to the provided url from the Airtable API docs.

> topic addtotable
 
> object currentDate javascript
  return new Date(Date.now()).toLocaleDateString()
< object
 
+ post_request
$ POST https://api.airtable.com/v0/appyaI2Wcb3DICUGX/Employee%20Directory {"headers": {"Authorization": "Bearer API_KEY", "Content-Type": "application/json"}, "body": {"fields": {"Name": "<get name>", "Department": "<get team>", "Home Address": "<get address>", "Phone #": "<get phone>", "Personal Email Address": "<get email>", "Birthday": "<get birthday>", "Date Added": "<call>currentDate</call>" }}}
* ${{__status}} != 200 => ${{error.message}}
- You've been added! You can see the full employee directory at ^link(http://bit.ly/2rAeMDF). {topic=default}
 
< topic

Ooph, that's a lot of text to process -- don't worry, it's just a few core elements.

The above JSON is the same as the below:

{
    "headers": {
        "Authorization": "Bearer API_KEY"
        , "Content-Type": "application/json"
    }
    , "body": {
        "fields": {
            "Name": "<get name>"
            , "Department": "<get team>"
            , "Home Address": "<get address>"
            , "Phone #": "<get phone>"
            , "Personal Email Address": "<get email>"
            , "Birthday": "<get birthday>"
            , "Date Added": "<call>currentDate</call>" 
        }
    }
}

Now, hopefully it's a little clearer to see how you can pass in user variables and even pass in results from any called macros into the request body!

HTTP NOT OK

It is best practice to include a conditional to look out for response errors after a request has been made. We want our bot to respond differently if the API request failed.

To do so, we add a line after the $ POST reuqest that looks out for when the returned response status code is not 200.

* ${{__status}} != 200 => ${{error.message}}

In this case, we return back the error message that comes back in the unsuccessful response using mustache syntax.

This ${{error.message}} syntax applies to the Airtable API error responses. Your mileage may vary with a different API. Try confirming what comes back in an error response by first having the bot respond with ${{__text}} and testing in the phone tester.
HTTP OK

If the API request works out, we'll have our bot respond with a success message before redirecting back to the "default" topic.

Considerations when using $ syntax

Let's Get You to Work!

Our usage of Airtable should serve as one example of a service that will let you pull in external data or save inside of your bot. Choose the solution that best matches your needs!

We leave you with a few exercises you can try at home (if you're not there already) on how to improve upon this Onboarding Bot example:

As always, message us from live chat if you get stuck, we're happy to help!