Botscript

Overview

BotScript is a safe, lightweight scripting language designed for chatbot logic execution. It is inspired by Python, with familiar syntax and a curated set of features to ensure safety and simplicity.

If you're comfortable with Python or JavaScript, you'll find BotScript intuitive. You can experiment with it in BotStudio by selecting the ? icon > BotScript Documentation, and testing scripts via the Script Evaluator.

Core Concepts

What You Can Do with BotScript:

• Use built-in functions
• Assign and manipulate variables
• Embed variables in chatbot responses using string interpolation

Data Types

BotScript supports a subset of Python types:

• Primitives: bool, int, float, str
• Collections: list, dict, set, tuple, slice
• Special Objects: Named Entity Recognition (NER) objects

Data Structures

Lists

• Creation: ['apple', 'banana', 'orange']
• Zero-indexed access: fruits[0] → 'apple'

Dictionaries (Objects)

• Creation: {'TicketId': 'TICK09786', 'authors': ['Peter', 'Sara']}
• Access: api_response['TicketId']

Sets

• Creation: {1, 2, 2, 3} → {1, 2, 3} (duplicates removed)

Strings

• Newline: 'Hello\nWorld'
• Concatenation: 'Email: ' + email

Entities (NER Functions)

• first(x) – First occurrence
• latest(x) – Latest occurrence
• ner_all(x) – All occurrences
• ner_clear(x) – Clear all
• ner_pop(x) – Remove and return latest
• ner_exists(x) – Check existence

Date & Time Functions

datetime_now(tz)

Returns an object with:

• year, month, day, hour, minute, second
• weekday, yearday, timestamp, timezone, epochs

Example: datetime_now('Europe/Copenhagen')['year'] → 2025

datetime_from_isostring(s)

Example: datetime_from_isostring('2024-12-31T23:59:00')

datetime_from_timestamp(ts, tz)

Example: datetime_from_timestamp(1704067200, 1)

Operators

• Boolean: and, or, not
• Arithmetic: +, -, *, /, //, %
• String/List/Tuple: + for concatenation
• Comparison: ==, !=, <, <=, >, >=, in, not in
• Conditional Expression: x if y else z

Built-in Functions with Descriptions and Examples

General Utilities

• join(sep, list) – Joins elements of a list into a string separated by sep.
  • Example: join(', ', [1, 2, 3]) → '1, 2, 3'
• sum(list) – Calculates the sum of all numeric elements.
  • Example: sum([1, 2, 3]) → 6
• len(obj) – Returns the number of elements in a list, tuple, set, or dict.
  • Example: len([10, 20, 30]) → 3
• str(x) – Converts a value to a string.
  • Example: str(42) → '42'
• int(x) – Converts a value to an integer.
  • Example: int('7') → 7
• float(x) – Converts a value to a float.
  • Example: float('3.14') → 3.14
• bool(x) – Converts a value to boolean.
  • Example: bool('true') → True
• list(x) – Converts to a list.
  • Example: list((1, 2)) → [1, 2]
• dict(x) – Converts a list of key-value pairs to a dictionary.
  • Example: dict([(1, 'a'), (2, 'b')]) → {1: 'a', 2: 'b'}
• set(x) – Converts a sequence to a set (unique values).
  • Example: set([1, 1, 2]) → {1, 2}
• tuple(x) – Converts a list to a tuple.
  • Example: tuple([1, 2]) → (1, 2)

String Operations

• lower(s) – Converts a string to lowercase.
  • Example: lower('HELLO') → 'hello'
• upper(s) – Converts a string to uppercase.
  • Example: upper('hello') → 'HELLO'
• replace(s, old, new) – Replaces all occurrences of old with new in string s.
  • Example: replace('bot', 'o', 'a') → 'bat'
• split(s) – Splits string s by whitespace.
  • Example: split('one two') → ['one', 'two']
• split_by(s, sep) – Splits string s by the delimiter sep.
  • Example: split_by('a,b,c', ',') → ['a', 'b', 'c']
• startswith(s, prefix) – Checks if string s starts with prefix.
  • Example: startswith('chatbot', 'chat') → True
• endswith(s, suffix) – Checks if string s ends with suffix.
  • Example: endswith('chatbot', 'bot') → True
• mask_email(s) – Obfuscates email addresses.
  • Example: mask_email('user@example.com') → 'u***@*******m'

Collection Functions

• keys(d) – Returns a list of keys in dictionary d.
  • Example: keys({'a': 1, 'b': 2}) → ['a', 'b']
• values(d) – Returns a list of values in dictionary d.
  • Example: values({'a': 1, 'b': 2}) → [1, 2]
• items(d) – Returns a list of key-value pairs (tuples) from dictionary d.
  • Example: items({'a': 1}) → [('a', 1)]
• dict_update(a, b) – Updates dictionary a with entries from b.
  • Example: dict_update({'x': 1}, {'y': 2}) → {'x': 1, 'y': 2}
• map(x, expr, collection) – Applies expr to each item x in collection.
  • Example: map(x, x * 2, [1, 2, 3]) → [2, 4, 6]
• foldl(x, acc, expr, init, collection) – Accumulates a value by applying expr for each x with accumulator acc.
  • Example: foldl(x, acc, acc + x, 0, [1, 2, 3]) → 6
• remove_if(x, cond, collection) – Removes items where cond is true.
  • Example: remove_if(x, x > 2, [1, 2, 3, 4]) → [1, 2]
• zip(a, b) – Combines two sequences into a list of tuples.
  • Example: zip([1, 2], ['a', 'b']) → [(1, 'a'), (2, 'b')]

Utility Checks

• exists(var) – Checks whether the variable var is defined.
  • Example: exists(my_var) → True if my_var exists
• raises_error(code) – Returns True if the expression code would raise an error.
  • Example: raises_error('1/0') → True
• any(xs) – Returns True if any boolean in the list xs is True.
  • Example: any([False, True]) → True
• all(xs) – Returns True if all values in list xs are True.
  • Example: all([True, True]) → True
• re_findall(pattern, input, flags) – Returns a list of all matches for regex pattern in input.
  • Example: re_findall('\d+', 'A1 B23') → ['1', '23']

Constants

• Math: math.e, math.pi, math.nan, math.inf
• Regex: re.IGNORECASE, re.I, re.MULTILINE, re.M, re.DOTALL

Using Variables in Text

When inserting variables into chatbot responses, use interpolation:

'Hello, ' + name

Avoid just writing name, as it may print the literal word 'name'.

For any missing functionality, you can request new features via the support channel.