Code your chatbot using Scripting

Introduction of Scripting

BotStar is an intuitive platform and it is easy to use. However, you can empower your bot with some technical skills. BotStar chatbot comes with a built-in code editor that lets programmers execute complex code within the context of the chat flow.

In BotStar, programming script can be used in two places:


The difference between a Scripting Block and Run Script Action is that Scripting Block will render a message based on the value returned by your script while Run Script Action executes the code silently before moving on to the next block.

BotStar requires the JSON formats when using Scripting and JSON API. You can refer to the following JSON formats to render a message or execute an action. For more information about the JSON format, please read our documentation.

Scripting in BotStar is synchronous. Your bot will pause until it finishes executing the script. Please refrain from doing heavy networks based on tasks to avoid long idle time.

Note: You can create more than one message from a scripting block.

How to use Scripting

Go to Bot Builder, you can easily find the Scripting Block in the Advanced Blocks.

Drag and drop Scripting Block into the Canvas, then click on Open Code Editor button to edit this block.

Example Scripting block Write your own NodeJS code within the provided function. This function provides you with two parameters: event and done.

event

event is a parameter object that is prepopulated with the following data:

bot: Data of bot attributes that system generated and the attributes you defined for your bot

  • System attributes include id.

  • The attributes that you define for your bot will be listed in the customAttributes field in the following format:

    {
    [Bot Attribute Name]: Value of the attribute
    }

user: End-user information is provided by the system and other attributes you defined for users.

  • System attributes include id, first_name (First name), last_name (Last name), language (Language), tags (the tags that you labeled your users).

  • The attributes that you defined for your users will be listed in the customAttributes field in the following format:

    {
    [User Attribute Name]: Value of the attribute
    }

conversation: The conversation information between your bot and the end-user includes: user responses and variables that you defined:

  • User responses will be listed in the userResponses field in the following format. The last response from users will be also listed in this field with key latest_response:

    {
    [Block Id]: User response of block
    }
  • Variables will be listed in the variables field in the following format:

    {
    [Variable Name]: Value of variable
    }
  • block: contains the information of id (block ID) and name from the current scripting block.

The sample format as shown below:

{
bot: {
id: "s334afb62-3453-4472-9e81-8fb30a552923",
customAttributes: {
address: "5th Street, NY",
companyName: "ABC Group"
}
},
user: {
id: "1234567890",
first_name: "Charlie",
last_name: "Martin",
language: "vi",
tags: ["potential", "guided"],
customAttributes: {
address: "01 9th Street, NY",
birthday: "1975-04-30"
}
},
conversation: {
userResponses: {
"s334afb62-3453-4472-9e81-8fb30a552345": "Banana",
"s334afb62-3453-4472-9e81-8fb30a598323": "01 9th Street, NY"
},
variables: {
products: ["Banana", "Apple"],
cost: 12,
currency: "USD"
}
},
block: {
id: 's334afb62-3453-4472-9e81-8fb30a552346',
name: "Send to Google Drive"
}
}

done

done is a callback function and is required to be called at the very end of your script. It will render messages to the end-user or perform actions after the script is executed. This function requires a JSON format parameter consisting of two fields: messages and actions.

  • messages: An array of BotStar JSON Block Formats which will be rendered to the end-user after the script is executed. And Run Script Action does not support this feature.
  • actions: An array of BotStar JSON Action Formats which will be performed after the script is executed.

The sample format as shown below:

{
"messages": [
{
"text": "Hi baby"
},
{
"text": "How are you today?",
"buttons": [
{
"title": "Great"
},
{
"title": "Not Good :("
}
]
}
],
"actions": [
{
"type": "set_variable",
"data": {
"age": 18,
"cost": 20,
"currency": "USD"
}
}
]
}

NodeJS Support

Scripting supports default modules provided by Node.js.

You can also use the following packages inside your script:

  • request - Simplified HTTP client
  • axios - Promise based HTTP client for the browser and node.js
  • cheerio - Fast, flexible & lean implementation of core jQuery designed specifically for the server
  • lodash - A modern JavaScript utility library delivering modularity, performance & extras
  • moment.js - Parse, validate, manipulate, and display dates and times in JavaScript
  • async - A utility module which provides straight-forward, powerful functions for working with asynchronous JavaScript

To enable and use these modules in your script, just use https module in this script:

const request = require('request'); // Use request module in this script

If you need other packages within your custom script, please let us know at the BotStar Community.

Example

To enable Scripting Block, you can use the following sample code for your block

const request = require('request');
const options = {
method: 'GET',
url: 'https://api.github.com/users/octocat',
headers: {
'User-Agent': 'Awesome-Octocat-App'
}
};
request(options, (error, response, body) => {
if (!error && response.statusCode == 200) {
const info = JSON.parse(body);
// Generate text message
const message = { text: info.name };
// Scripting callback function, more details: https://docs.botstar.com/docs/en/scripting/#done
done({
messages: [
message
],
actions: []
});
}
});

Go to Bot Builder and set up a Scripting Block as the picture below:

The code above uses the https library to send a get request to

https://api.github.com/users/octocat

After receiving the code, data will be processed to decode and return "The Octocat" (name)

Example scripting render

If you have any concerns, please feel free to leave a comment below or contact us through support@botstar.com. For more details on how we have helped our customers grow their business, you can view our use cases, blogs or join our BotStar community to learn and share new things 😊


Did you find it helpful?   Yes   No