JavaScript API#

Several chatbot blocks run your JavaScript code. The code calculates, parses responses from third-party services, changes the contact's variables and tags, sends messages and decides where the scenario goes next. This section is a reference for whoever writes such code.

Where the code runs#

What this data contains is described on the "Built-in variables" page. The functions are the same in all blocks:

How the code runs#

1. The code runs as a whole on a separate server. The functions do not change the contact right away; they record what to do: which variables and tags to write, which messages to send, which block to go to.
2. The code finished without an error — the bot writes the contact's variables and tags and the bot's global variables, then, in the order of the calls, sends the messages and moves the contact to the block from goToBlock. After that the "Continue" connection fires, unless the code disabled it.
3. The code finished with an error — nothing is applied, not even what the code called before the error.

Within one run, the read functions already see what the code wrote earlier: after setContactVariable('bouquet', 'Roses'), a call to getContactVariable('bouquet') returns 'Roses', even though the variable has not been written to the contact yet.

The code starts anew on every pass through the block. Ordinary JavaScript variables (var) are not kept between runs — write whatever needs remembering to the contact's variables or to the bot's global variables.

Language#

The code runs as JavaScript of the ES5 standard. From newer standards, the following is missing:

• let and const — declare variables with var;
• arrow functions — write function (x) { return x * 2; };
• template literals in backticks — join strings with +;
• classes, destructuring, Promise, async/await, setTimeout;
• methods from newer standards: includes, startsWith, padStart, find, Object.assign, Array.from and the like. Use indexOf instead of includes and startsWith.

Everything from ES5 is there: JSON.parse and JSON.stringify, Math, Date, the string and array methods split, replace, trim, map, filter, forEach, reduce, indexOf, sort. The 'use strict' directive does no harm, but does not turn strict mode on.

The code cannot make network requests: fetch, XMLHttpRequest and require are not available. Use the "HTTP request" block for requests.

Dates#

Date counts time in the server's time zone, so use the UTC methods for calculations: getUTCHours(), getUTCDate(). Date does not parse a string like 2026-01-31 12:00:00 (this is what created_at looks like) — replace the space with T and add Z:

var created = new Date(created_at.replace(' ', 'T') + 'Z');
var days = Math.floor((new Date() - created) / 86400000);

Regular expressions#

Regular expressions run on the RE2 engine, and some JavaScript features do not work in it. Code with such a pattern stops with the error Invalid regular expression:

\w, \b and \d only understand Latin letters and digits: /\w+/ will not find a word written in Cyrillic or with accented letters such as «müller». For such letters, list them explicitly: /[a-zäöüß]+/i.

Limits#

Errors and debugging#

What happened during a run is shown in the "Execution log" in the block settings: the source code, the value of the last expression, the actions performed and the error text.

The value of the last expression is the main debugging tool. Add a variable name or an expression at the end of the code, and its value will appear in the log. Turn an object or an array into a string first, otherwise the log shows [object Object]:

var bouquet = { name: 'Roses', count: 7 };
JSON.stringify(bouquet);

console.log does not cause an error, but writes nothing to the log.

Where an error goes depends on the block:

In a syntax error message, the line number is one greater than in the editor: the error Line 4:5 Unexpected identifier means line four minus one — line three.

You can also raise an error on purpose — throw new Error('No price') stops the code, and nothing it did is saved. In the blocks that send the error text to the chat, the contact sees Error: No price.

Tip

Test the code in the bot preview — the "Test the bot" button in the builder. This way you see the error, not your customers.