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.

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.

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

Step 1. Connect the Chat API channel

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

Step 2. Configure the reaction settings

Go to the source code editor.
In the src directory, add a subdirectory for reactions, such as blocks.
In the blocks directory, create a file called video.json.
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

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

customBlocks:
  - src/blocks/video.json

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

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

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
}