Skip to main content

How to create custom action tags

JAICP has a number of built-in action tags, which cover some of the actions frequently performed in bot scripts. For example, they can make the bot send an HTTP request or transfer the dialog to an agent.

If the features of built-in action tags aren’t enough for you, you can create your own. With custom tags, you can implement any kind of bot business logic and reuse it in different parts of your script.

This article is a step-by-step tutorial describing how to develop a simple tag which:

  1. Accepts two numbers and reply format as its parameters.
  2. Makes the bot reply with the sum value in the specified format.

To develop the tag:

  1. Write a script for your tag.
  2. Configure the tag settings in a separate JSON file.
  3. Specify the path to the JSON file in chatbot.yaml.
  4. Use the tag in your script.

Step 1. Write the tag script

  1. Sign in to JAICP and select the necessary project.
  2. From the sidebar, navigate to Editor → Code.
  3. In the src directory, add a subdirectory for action tags, such as blocks.
  4. In the blocks directory, add a SumTwoNumbers subdirectory containing a file called
  5. Write the script for your tag and save it.
theme: /Blocks

state: SumTwoNumbers
# 1
$temp.numberOne = $;
$temp.numberTwo = $;
$temp.answerFormat = $;
# 2
$temp.result = parseFloat($temp.numberOne) + parseFloat($temp.numberTwo);
# 3
if: !isNaN($temp.result)
# 4
if: $temp.answerFormat === "number"
a: {{$temp.result}}
elseif: $temp.answerFormat === "full"
a: {{$temp.numberOne}} + {{$temp.numberTwo}} = {{$temp.result}}
# 5
if: $
go!: {{$}}
# 6
elseif: $
go!: {{$}}
a: I don’t know how to calculate {{$temp.numberOne}} + {{$temp.numberTwo}}.

Let’s go over the script code:

  1. In the state from which the tag script begins, the values of tag parameters can be extracted via the $ object. The values of numberOne, numberTwo, and answerFormat are copied over to $temp for more convenient access.

  2. All parameter values have a string type. Before using them for calculations, numberOne and numberTwo need to be converted to numbers. This is done using the parseFloat built-in function. The numbers are then added to one another, and the sum is stored in $temp.result.

  3. Next, there is a check for a corner case that the parameters couldn’t be converted to numbers, which makes the sum have the value of NaN. If the value is not NaN, the bot replies with the sum value in the specified format.

  4. If answerFormat is set to "number", the bot replies with the sum only, for example: “7”. If answerFormat is set to "full", the bot replies with the full expression, for example: “3 + 4 = 7”.

  5. The best way to design custom tags is to include a way to specify the state in the main script where the bot should return after the action. The SumTwoNumbers tag supports two additional parameters: okState and errorState. If the bot successfully calculated the sum and the okState parameter is defined, the script goes to that state.

  6. If the bot failed to calculate the sum and errorState is defined, the script goes to that state. If neither okState nor errorState is defined, the bot reports an error instead.

Step 2. Configure the tag settings

To use the above script as a action tag, you need to describe it in a special JSON settings file.

  1. In the same SumTwoNumbers directory, create another file called block.json.
  2. Add a JSON object with the properties below into this file. Unless said otherwise, all properties are required.

Tag settings

tagNameStringAction tag name.
startStateStringThe state from which the tag script will start executing.
scenarioFileStringThe path to the script file, relative to the src directory.

Parameter settings

parametersArray of objectsThe parameters that can be passed to the tag.
parameters[].nameStringParameter name.
parameters[].typeStringParameter type.
parameters[].requiredBooleanIndicates if the parameter is required.

Parameter types

TypeDescriptionExample value
stringStringHello, world!
htmlString with HTML markupHello, <b>world</b>!
stringArrayArray of strings["Hello", "world"]
nameValueListArray of objects with the name and value properties[{"name": "hello", "value": "world"}]
jsonObject{"hello": "world"}
statePath to a state/Start

Regardless of the declared type, the values of all parameters are stored in $ as strings. To make the action tag script work with them properly, use type conversions:

  • bool parameters can be cast to Boolean values using the Boolean constructor.
  • integer parameters can be cast to numbers using either parseInt or parseFloat.
  • stringArray, nameValueList, and json parameters can be cast to objects using JSON.parse.

List of valid parameter values

In the parameters[].userInterfaceField property, you can specify a list of valid values for a parameter. In this case:

  • If you specify a value not from the list in the script, the bot deployment error will occur. You cannot specify a JavaScript expression as a value for such parameter.
  • In the J‑Graph visual editor, only values from this list can be selected for the parameter.
parameters[].userInterfaceFieldObjectSettings for the parameter valid values. Optional property.
parameters[].userInterfaceField.typeStringAlways specify the "select" value.
parameters[].userInterfaceField.options[]Array of objectsValid parameter values.
parameters[].userInterfaceField.options[].valueStringParameter value. Always pass the value as a string.
How to convert a value to a string
  1. Enclose the value in double quotation marks (").
  2. If the value contains double quotation marks, escape them with the \ character.


Initial valueString
["example1", "example2"]"[\"example1\", \"example2\"]"

J‑Graph appearance settings

In the J‑Graph visual editor, action tags correspond to action blocks. The properties below allow configuring how they are displayed in J‑Graph. All of these properties are optional.

As their value, all properties accept an object with the eng key. Its value is used for displaying the JAICP interface in English.

captionAction display name. If not set, the action tag name (from the tagName property) will be used instead.
descriptionAction description. It is displayed as an attention block in the action editing menu.
hintAction hint. It is displayed as a hint when hovering over the action in the list of all reactions.
parameters[].localizationParameter display name. If not set, the parameter name itself (from the name property) will be used instead.
parameters[].descriptionParameter description. It is displayed as a hint when hovering on the parameter name.
parameters[].userInterfaceField.options[].localizationThe parameter value name in the valid values list. If no name is specified, the parameter value (value) is used.

Settings example

This is an example JSON file for the number addition script developed on step 1:

"tagName": "SumTwoNumbers",
"startState": "/Blocks/SumTwoNumbers",
"scenarioFile": "blocks/SumTwoNumbers/",
"caption": {
"eng": "Sum two numbers"
"description": {
"eng": "Use this block to calculate the sum of two numbers and send a reply with the result."
"hint": {
"eng": "Calculate the sum of two numbers and send a reply with the result"
"parameters": [
"name": "numberOne",
"type": "integer",
"required": true,
"localization": {
"eng": "First number"
"name": "numberTwo",
"type": "integer",
"required": true,
"localization": {
"eng": "Second number"
"name": "answerFormat",
"type": "string",
"required": true,
"localization": {
"eng": "Answer format"
"userInterfaceField": {
"type": "select",
"options": [
"value": "number",
"localization": {
"eng": "Number only"
"value": "full",
"localization": {
"eng": "Full expression"
"name": "okState",
"type": "state",
"required": false,
"localization": {
"eng": "Next state on success"
"description": {
"eng": "The bot will go to this state if it successfully calculates the sum."
"name": "errorState",
"type": "state",
"required": false,
"localization": {
"eng": "Next state on error"
"description": {
"eng": "The bot will go to this state if it fails to calculate the sum."

Step 3. Specify the JSON file path in chatbot.yaml

  1. In the chatbot.yaml configuration file, create a customTags section if it doesn’t exist yet.
  2. In this section, specify the path to the JSON file relative to the project root directory.
- src/blocks/SumTwoNumbers/block.json
If you want to use the tag as a J‑Graph action, be sure to save the changes made in the source code editor by clicking .

Step 4. Use the tag in your script

In the code editor

  1. Go to the necessary bot script file, such as

  2. Create a new state for your action tag and specify its parameters, for example:

    state: SumTwoNumbers
    q!: * @duckling.number::numberOne (plus/$regex<\+>) @duckling.number::numberTwo [equals] *
    numberOne = {{$parseTree._numberOne}}
    numberTwo = {{$parseTree._numberTwo}}
    answerFormat = number
    okState = /AnythingElse

    state: AnythingElse
    a: Should I calculate anything else for you?
    • The state is triggered by requests like two plus three. Two numbers are extracted from the request using the @duckling.number entity and passed to the tag.
    • SumTwoNumbers is the action tag name. It corresponds to the tagName value parameter in the JSON settings file.
    • numberOne, numberTwo, answerFormat, and okState are the action tag parameters as defined in the JSON file. Their values can be different every time the tag is used.

In the J‑Graph visual editor

  1. From the sidebar, navigate to Editor → J‑Graph.
  2. Create a new state on the canvas.
  3. In the state editing menu, select All reactions.
  4. Select the new Sum two numbers action from the reactions list.
  5. Fill out the action parameters and save the block.
“Sum two numbers” in the actions list
Action configuration