Artibot
 

Introduction to Code Messages

The ArtiBot API allows you to develop and execute custom code arbitrarily to process user input in a custom way.

This allows for limitless possibilities like:

  • dynamic branching
  • a/b testing different conversation flows
  • looking up information in an external system
  • custom integrations
  • whatever else you can dream up!

The ArtiBot API enables this functionality by providing the ability to run custom javascript.

Once the conversation receives input from an API question or encounters an API action, your code is executed.

Your code can control almost anything in the chat including:

  • emit custom messages in conversations
  • branch to anywhere in the conversation flow
  • reprompt the user if their input was invalid
  • return a custom value to store against the lead for that question
  • store additional pieces of information on the lead or the chat for use later in the conversation

Simple Tutorial

Let’s look at a simple example to illustrate some of these capabilities.

Say you prompted the user to enter an order number.

Your code could lookup the given order number by making a request out to your backend system.

If the order is not found, the user could be told that their order was not found.

If the order was found, you could store the order number against the lead.

You could also store on the lead that the user was a long-standing customer or the status of the order.

You could use this information later in the conversation to thank them for being a long-standing customer or ask them a different set of questions depending on the status of the order for example.

Don’t have a backend system that you would like to interface with? No problem!

You can do dynamic things such as custom branching without calling into any external system.

Let’s consider an example of this. What if your ArtiBot asked the user to enter their age. If they were under 19 you could provide them with an entirely different conversation flow than if they were 19 or over.

The possibilities are endless for the ArtiBot API.

Implementation

All of these powerful features are available to you through the API type in ArtiBot. Add an API question to your ArtiBot and paste in the following code: 

exports.handler = (artibotContext) => {
    const isHeads = (Math.floor(Math.random() * 2) === 0);
        return {
            value: isHeads ? "heads" : "tails"
        };
};

This simple example demonstrates a simple coin flip and stores either "heads" or "tails" on the lead as the answer to the API question.

What do you have access to inside of your code:

The artibotContext parameter holds all kinds of goodness with full access to:

  • artibotContext.input - Input to the question
  • artibotContext.lead - Data stored on the lead so far
  • artibotContext.meta - Metadata associated with the conversation
  • artibotContext.is_test - Whether the session was a test

Here is an example of what the artibotContext looks like: 

{                                                                                                                                         
    "is_test": true,                                                                                                                        
    "input": "nougat",                                                                                                                      
    "lead": {                                                                                                                               
        "id": "00000000-0000-0000-0000-000000000000",                                                                                         
        "create_date": "2019-05-30T21:11:14.5140626Z",                                                                                        
        "modify_date": "2019-05-30T21:11:14.5140627Z",                                                                                   
        "bot_id": "9207a2de-3b13-4d31-8242-9564e1c328d1",                                                                              
        "bot_version_id": "855f9a3b-866a-4fcd-888f-9325f2354a7e",                                                                         
        "account_id": "dd8554fd-9905-4d37-83d2-9e56f0cfbb28",                                                                    
        "contact_id": "00000000-0000-0000-0000-000000000000",                                                               
        "status": 0,                                                                             
        "version": 1,                                                                                                                     
        "data": {                                                                                                                       
            "Some date time": {                                                                                                           
                "input": "5/30/2019, 2:10 PM",                                                                                                 
                "type": "date_time",                                                                                                    
                "display_value": null,                                                                                                    
                "value": "2019-05-30T21:10:00Z"                                                                                           
            },                                                                                              
            "Favorite Color": {                                                                                                             
                "input": "Light Purple",                                                                                                    
                "type": "text",                                                                                                      
                "display_value": null,                                                                                                   
                "value": "Light Purple"                                                                                                   
            }                                                                                                           
        }                                                                                                               
    },                                                                                                                                  
    "meta": {                                                                                                                         
        "chat_start_page": "https://artibot.ai",                                                                                        
        "ip_address": "1.2.3.4",                                                                                          
        "location": {                                                                                              
            "country_abbreviation": "US",                                                                                                     
            "country": "United States of America",                                                                                                            
            "state": "Arizona",                                                                                               
            "city": "Scottsdale",                                                                                                      
            "latitude": "33.6125",                                                                                                    
            "longitude": "-111.8924"                                                                                            
        },                                                                                                                            
        "browser": {                                                                                                                       
            "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.121 Safari/537.36",
            "name": "Chrome",                                                                                             
            "version": "72",                                                                                                                  
            "major": null,                                                                                                             
            "is_mobile": false                                                                                                             
        }                                                                                                                     
    }                                                                                                                                
}

Node Modules:

You can require in any packages available by default in node 10.x. You can find the list here.

So then in your code you can do something like this:

const https = require('https');

Using this you could make requests using the https package.

artibotContext

Name Type Description
is_test boolean This field lets you know if the execution of your code is taking place in response to testing within the ArtiBot dashboard. If false then the code is executing in response to a real chat happening rather than a test.
input string This field indicates the value that was entered by the user for an API question. If no question was asked (this is an API action) then this value will be null and can be ignored.
lead object The lead object holds several interesting pieces of data about what has been stored so far on the lead.
meta object The meta object holds metadata associated with the conversation.

lead

Name Type Description
id GUID The unique identifier of the lead.
create_date Date The time in UTC that the lead was created.
modify_date Date The time in UTC that the lead was last modified.
bot_id GUID The unique identifier of the bot that this lead was created from.
bot_version_id GUID The unique identifier of the bot version that this lead was created from.
account_id GUID The unique identifier of the account that this lead was created in.
contact_id GUID The unique identifier of the contact associated with the lead. If multiple leads are created from the same browser on the same computer then the contact_id's will remain the same.
status number The status of the lead. A status of 0 means that the lead is active. A status of 2 means that the lead has been deleted in ArtiBot
version number The version number of the lead. Whenever a lead is modified this number increases by one.
data Dictionary A dictionary of they name/value pairs that have been stored against the lead so far. When a question is answered or additional data is stored against the lead, it appears in this dictionary. The type is a dictionary mapping name to Answer.

answer

Name Type Description
input string This is what the visitor entered into the chat for this question.
type string This value indicates the type of question that was asked. The currently supported values are included below
display_value string This is what will be displayed for the value in the chat conversation. For example if this answer was in response to a Date Time question the display value might look like: "05/30/19, 4:56 PM" based on your account locale.
value object This is value actually stored against the lead. For example if this answer was in response to a Date Time question the value might look like: "2019-05-30T00:04:56.12".

Your answer type options:

 
        0: Statement
        1: Phone Number
        2: Email
        30: Date Time
        40: Number
        51: Currency Amount
        52: Length with Units
        56: Duration
        100: Anything
        101: Url
        200: Multiple Choice
        300: Video
        400: Appointment Scheduler
        500: Payment Collector
        600: Address
        700: Api Question
        701: Api Action

meta

The meta object holds metadata associated with the conversation: chat_start_page, ip_address, location, browser, and last_answered_field_name.

Name Type Description
chat_start_page object That web page from which this conversation started.
ip_address string The IP address of the lead.
location object The location object holds information about the lead’s location: country_abbreviation, country, state, city, latitude, longitude.
browser object The browser object holds information about the lead’s browser: user_agent, name, version, major, is_mobile.
last_answered_field_name string This field indicates the last question that was answered by the lead in the conversation.

location

The location object holds information about the lead’s location: country_abbreviation, country, state, city, latitude, longitude.

Name Type Description
country_abbreviation string An abbreviation of the lead's country.
country string The lead's country.
state string The lead's state.
city string The lead's city.
latitude string The lead's latitude.
longitude string The lead's longitude.

browser

The browser object holds information about the lead’s browser: user_agent, name, version, major, is_mobile.

Name Type Description
user_agent string The user agent of the lead’s browser.
name string The name of the lead’s browser.
version string The version of the lead’s browser.
major string The major of the lead’s browser.
is_mobile boolean Indicates if the lead is coming in through a mobile device.

What to return from your code

Your function can control almost any part of the conversation based upon what you return from your code. Here is an example showing all of the possible arguments as well as descriptions of what they do and their default values. 

{
    value: "custom value to store against the lead for this question"
    is_valid_input: true,
    branch_to_override: "Name of question to branch to",
    statements: [
        {
                statement: "Some custom statement",
                delay: 2
        },
        {
                statement: "Another custom statement",
                delay: 1
        },
        {
                statement: "A final statement",
                delay: 5
        }
    ],
    additional_data: [
        {
                name: "Custom key",
                value: "custom value",
                store_on_lead: true
        },
        {
                name: "Another custom key",
                value: new Date(),
                store_on_lead: true
        },
        {
                name: "Variable for use in chat",
                value: 999,
                store_on_lead: false
        }
    ]
}
Name Type Description
value object This field controls the value that will be stored against the lead as the answer associated with the name of this API question or action. This field is optional. If no value is provided, the answer will not be stored against the lead.
is_valid_input boolean This field indicates whether or not the given input should be considered valid. If is_valid_input is false and this is an API question, the question will be asked again. The value of is_valid_input has no effect if no question was asked. This field is optional.
branch_to_override string This field instructs ArtiBot to branch directly to the question with the given name. If provided this will force the conversation to go to that question regardless of other values returned. This field is optional.
statements Statement Providing statements causes custom statements to be output in the chat conversation.This field is optional. If no statements are provided, no additional statements will be output in the conversation flow.
additional_data AdditonalData Providing additional_data causes additional pieces of data to be stored against the lead or the chat. This field is optional.

statement

Name Type Description
statement string This is the text that will be output in the statement in the conversation. This field is required if a Statement is provided.
delay number This is the amount of delay before displaying the statement in the conversation. This field is optional. The default is 0.

AdditionalData

Name Type Description
name string This is the name of the data that will be stored against the lead or the chat. This field is required for each AdditionalData provided.
value number This is the value that will be stored against the lead or the chat associated with the given name. This field is optional. If no value is provided, the answer will not be stored against the lead.
store_on_lead boolean If true then the value will be stored against the lead. If false then the value will be stored against the chat. Data stored against the chat can be used in the conversation but is not stored on the lead. This field is optional. The default value is true.