Skip to main content

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

PropertyTypeDescription
tagNameStringReaction name without spaces.

Parameter settings

PropertyTypeDescription
parametersArray of objectsThe parameters that can be passed to the reaction.
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>!
integerNumber3.14
boolBooleanfalse
stringArrayArray of strings["Hello", "world"]
nameValueListArray of objects with the name and value properties[{"name": "hello", "value": "world"}]
jsonObject{"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 Tovie Platform interface in English.

PropertyDescription
captionReaction display name. If not set, the reaction name (from the tagName property) will be used instead.
descriptionReaction description. It is displayed as an attention block in the reaction editing menu.
hintReaction hint. It is displayed as a hint when hovering over the reaction 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.

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 campaignsCreate 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
}