How to create custom reactions for text campaigns

The content of text campaigns can be configured using the built-in editor. In your text campaigns, you can send built-in bot reactions, such as Text, Image, and Button group.

If the features of built-in bot reactions aren’t enough for you, you can create your own.

caution

This feature is available only for the Chat API channel.

This article is a step-by-step tutorial describing how to create a custom reaction that will send video recordings in your text campaign.

1. Connect the Chat API channel.
2. Configure the reaction settings in a separate JSON file.
3. Specify the path to the JSON file in chatbot.yaml.
4. Start your text campaign.

Step 1. Connect the Chat API channel

1. Select the necessary project.
2. From the sidebar, navigate to Channels.
3. Follow this instruction to connect the channel.

Step 2. Configure the reaction settings

1. Go to the source code editor.
2. In the src directory, add a subdirectory for reactions, such as blocks.
3. In the blocks directory, create a file called video.json.
4. Add a JSON object with the properties below into this file. Unless said otherwise, all properties are required.

Reaction settings

Property	Type	Description
tagName	String	Reaction name without spaces.

Parameter settings

Property	Type	Description
parameters	Array of objects	The parameters that can be passed to the reaction.
parameters[].name	String	Parameter name.
parameters[].type	String	Parameter type.
parameters[].required	Boolean	Indicates if the parameter is required.

Parameter types

Type	Description	Example value
string	String	Hello, world!
html	String with HTML markup	Hello, <b>world</b>!
integer	Number	3.14
bool	Boolean	false
stringArray	Array of strings	["Hello", "world"]
nameValueList	Array of objects with the name and value properties	[{"name": "hello", "value": "world"}]
json	Object	{"hello": "world"}

Reaction appearance settings

The properties below allow configuring how your reactions are displayed in the text campaign interface. 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.

Property	Description
caption	Reaction display name. If not set, the reaction name (from the tagName property) will be used instead.
description	Reaction description. It is displayed as an attention block in the reaction editing menu.
hint	Reaction hint. It is displayed as a hint when hovering over the reaction in the list of all reactions.
parameters[].localization	Parameter display name. If not set, the parameter name itself (from the name property) will be used instead.
parameters[].description	Parameter description. It is displayed as a hint when hovering on the parameter name.

Settings example

{
    "tagName": "Video",
    "caption": {
        "eng": "Video"
    },
    "description": {
        "eng": "Use this block to add a video to the bot message."
    },
    "hint": {
        "eng": "Add a video to the message"
    },
    "parameters": [
        {
            "name": "url",
            "type": "string",
            "required": true,
            "localization": {
                "eng": "Video URL"
            }
        },
        {
            "name": "buttonText",
            "type": "string",
            "required": true,
            "localization": {
                "eng": "The text of the button below the video"
            }
        },
        {
            "name": "buttonDeeplink",
            "type": "string",
            "required": true,
            "localization": {
                "eng": "Button deeplink"
            }
        },
        {
            "name": "buttonStartTime",
            "type": "integer",
            "required": true,
            "localization": {
                "eng": "Button appearance time (in seconds)"
            }
        },
        {
            "name": "previewUrl",
            "type": "string",
            "required": true,
            "localization": {
                "eng": "Preview URL"
            }
        }
    ]
}

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

1. In the chatbot.yaml configuration file, create a customBlocks section if it doesn’t exist yet.
2. In this section, specify the path to the JSON file relative to the project root directory.

customBlocks:
  - src/blocks/video.json

caution

Before you create the text campaign, be sure to save the changes made in the source code editor by clicking .

Step 4. Start your text campaign

1. Navigate to Text campaigns → Create text campaign.
2. Select the block you created in Other reactions and configure your text campaign.
3. Start your text campaign.

tip

When it starts, the Chat API channel will receive your message from the text campaign along with an object of customBlock type that includes all the reaction settings.

Response example:

{
    "token": "abcde12345",
    "clientId": "test",
    "questionId": "96bca0e9-9df5-4e03-a8a4-4eb4aba57da5",
    "data": {
        "replies": [
            {
                "type": "text",
                "text": "Some text",
                "state": "/Match",
                "lang": "eng"
            },
            {
                "type": "buttons",
                "buttons": [
                    {
                        "text": "Button name",
                        "transition": "/SomeState"
                    }
                ],
                "state": "/Match"
            },
            {
                "type": "customBlock",
                "blockName": "Video",
                "body": {
                    "url": "https://example.com",
                    "buttonText": "Button name",
                    "buttonDeeplink": "https://example.com",
                    "buttonStartTime": "23",
                    "previewUrl": "https://example.com"
                }
            }
        ],
        "answer": "Some text",
        "newSessionStarted": false,
        "debugData": [],
        "endSession": false
    },
    "timestamp": "2023-04-19T12:47:35.260",
    "blockForm": false
}