Write Chatbot Scripting In BotStar

Introduction of Scripting

We keep saying BotStar is intuitive and easy to use, but the platform is actually very powerful. It comes with a built-in code editor that let programmers execute complex code from with in the context of the chat flow.

In BotStar Bot Builder, 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 required the JSON formats when using Scripting and JSON API. You can refer to the following JSON formats to render 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 network based on task 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 Bot Builder, then click on Open Code Editor button to edit for 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 includes 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 labelled 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. Và response cuối cùng của user cũng được list trong field này với 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
  • 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