Bot Documentation

Chatitive bots are written in JavaScript and are easy to create. The basic format of a bot is as follows:

var bot = {
  keywords: {
    start: function(message, subscriber) {
      say(”Welcome to our example bot.  Reply STOP to unsubscribe”);
    },

    keyword1: function(message, subscriber) {
      // Code to handle keyword1
    },

    keyword2: function(message, subscriber) {
      // Code to handle keyword2
    }

    keyword3: function(message, subscriber) {
      // Code to handle keyword3
    }

    // Add as many keywords as necessary here

  },

  aliases: {
    "keywordA": "keyword1" // KeywordA will be handled by the handler for keyword1
    "keywordB": "keyword1" // KeywordB will also be handled by the handler for keyword1.
  },

  defaultKeyword: function(message, subscriber) {
    // The defaultKeyword handler will be called when no other keyword is matched.

    /*
     * The return value of `defaultKeyword` has special meaning:
     *
     * Return `true` to send this user to the support inbox.
     * Return `false` to leave that state unchanged.
     */
    return true;
  }
};

Note about execution time

Bots need to finish executing in under 60 seconds, or the bot will be killed. This includes time spent running code as well as making AJAX calls.

Keywords

Keywords are the entry point to your bot's functionality, and define how your bot interacts with customers.

Reserved keywords

The following keywords have special meaning. See the compliance documentation for more information:

Two objects are passed into all keyword handlers: message and subscriber

Message object

The message object has several properties:

Subscriber object

The subscriber object has several properties and methods.

Properties

Methods

Channel object

The channel object has the following properties and methods:

Properties

Methods

Campaign object

The campaign object exposes properties and methods for campaigns.

Properties

Methods

Tag object

The tag object has the following properties and methods:

Properties

Bot methods and properties

Chatitive uses Google's V8 JavaScript engine to provide standard JavaScript functionality to bots. Besides the standard JavaScript methods, the following additional methods are provided when authoring bots.

Methods

say("Welcome to the Sample Bot.");

get({
  url: "http://fortunecookieapi.com/v1/fortunes",
  data: {limit: 1, skip: offset},
  success: function(result) {
    var fortunes = result.responseJSON;
    if (fortunes !== null && fortunes.length > 0) {
      say(fortunes[0].message);
    } else {
      // our response didn't actually contain a fortune!
      say("We are having trouble reading your fortune right now.");
    }
  },
  error: function() {
    say("We are having trouble reading your fortune right now.");
  }
});

post({
  url: "http://example.com/message-callback",
  data: {foo: 123, bar: "yes please", isGreat: true}, // JavaScript object will get serialized
  headers: {
    // Basic authentication using Aladdin / "open sesame"
    Authorization: "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
  }
});

put({
  url: "http://example.com/message-callback",
  data: {foo: 123, bar: "yes please", isGreat: true}, // JavaScript object will get serialized
  headers: {
    // Basic authentication using Aladdin / "open sesame"
    Authorization: "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
  }
});

Session

The Session object can be used to track information about a subscriber across messages. It can be used to store information like the last purchase date or maintain information about a conversation the bot is having with a subscriber.

The intended difference between Session and Subscriber properties is that subscriber properties describe attributes about the particular customer (name, preferences, settings in an external system), but Session attributes provide information about a Subscriber's messaging interactions.

The session is exposed through a global session variable. Consider the following example where a subscriber's last purchase date is used to generate a coupon code for a frequent purchaser.

// Invoked when the subscriber makes a purchase
session["lastPurchaseDate"] = new Date().toISOString();

// On a subsequent purchase
if (new Date(session["lastPurchaseDate"]).month === new Date().month) {
  say('Thanks for being such a great customer! Next time, respond with GOODCUSTOMER for a 10% discount');
}

Subscriber properties can also be set and retrieved through the Chatitive API. For debugging purposes, you the Session can be accessed like a hash e.g. say(session)

Debugging Bot Javascript using toJSON

Bot objects (Campaign, Channel, Message, Session, Subscriber and Tag ) are all ES6 classes and can be treated as such for debugging. For example, inside a bot function, you could use:

say(message); // or say(JSON.stringify(message));

to print out a simplified JSON serialization of the message object.

Global functions

Incoming Voice Call Handling

By adding a global function called handleVoiceRequest, you can control how voice calls to your transport numbers are handled. The function accepts a context object as a parameter, and should return TwiML. The context object provides the caller's phone number, as well as their country, state and city if that data is available.

The context object's fields are named as follows:

Example

function handleVoiceRequest(context) {
  const caller = context.from_city ? ` caller from ${context.from_city}` : '';
  return
    '<?xml version="1.0" encoding="UTF-8"?>' +
    `<Response><Say voice="female">Hello${caller}! Please text us for help</Say><Hangup/></Response>`;
}

To disable voice requests completely, have handleVoiceRequest return the constant VOICE_REQUEST_REJECT.

Disable Voice Requests

function handleVoiceRequest(context) {
  return VOICE_REQUEST_REJECT;
}

Keyword extractor

If you need to override the default method of extracting keywords, you can provide your own keyword extractor by implementing a function called extractMessageKeywords. This function accepts a string parameter containing the entire body of the received message, and should return a prioritized array of keywords. The system will first look for a matching workflow automation, trying each of the returned keywords until a match is found. If no match is found, it will look for a matching bot keyword handler, iterating through all the returned keywords until a matching handler is found. Should a keyword handler not be found, the default keyword handler will be called as usual.

Should you wish to use the default keyword extractor for a particular message, your extractor can return an empty array.

NOTE: Your keyword extractor MUST return compliance keywords (start, stop, help, unsubscribe) unmodified, otherwise the system will prevent you from deploying your bot.

Example

function extractMessageKeywords(message) {
  // Remove all punctuation, then return all the words in the message in an array
  return message.replace(/[,.?!;:]/, '').split(/\s+/);
}