This site is no longer updated.Go to new Conversational Cloud docs

Supported message types

text

A simple text response, each element is displayed in a separate message.


Parameters
  • text — response text.
  • tts — sets the answer text with markup for speech synthesis.
  • markup — sets the formatting method.

Syntax
{ 
  "type":"text", //message type 
  "text":"....", //response text
  "tts":"....",  //markup for speech synthesis
  “markup”:      //formatting
    "html|markdown|plain" 
}

In the text of the answer, you can use substitutions and functions under the a tag and in $reaction.answer. Inside {{}} brackets there can be any valid expression on JavaScript, you can use the same variables and functions as in the scripts.


How to use
  • Adding an answer to $response:
script:
    var reply = {
        "type":"text",
        "text":"answer",
    };
    $response.replies = $response.replies || [];
    $response.replies.push(reply);
  • Answer modification. In the example we use postProcess: if the bot's answer is repeated, replace it with the phrase "I’ve already said that".
init:
    bind("postProcess", function($context) {
        var currentAnswer = $context.response.replies.reduce(function(allAnswers, reply) {
            allAnswers += reply.type === "text" ? reply.text : "";  
            return allAnswers;
        },"");
        
        if ($context.session.lastAnswer === currentAnswer) {
            $context.response.replies = [
            {
                "type":"text",
                "text":"I’ve already said that"
            }
            ];
        }
        $context.session.lastAnswer = currentAnswer;
    });

theme: /
    state: 
        q!: How are you?
        a: I’m fine!
        a: And you?

audio

Using an audio recording in a bot response.


Parameters
  • audioUrl – link to the audio file.
  • audioName – name of the audio file.

Syntax
{
  "type":"audio",                 //message type
  "audioUrl":"http://..."         //link to the audio file.
  "audioName":"name of the file",        //name of the audio file
}
How to use
 script:
        $response.replies.push( {
            type: "audio",
            audioUrl: " https://...jpg",
            audioName: "voice"       //the field is optional
        } )

video

Using video in the bot's reply.


Parameters
  • videoUrl — video link.

Syntax
{
  "type":"video",                 //message type
  "videoUrl":"http://..."         //video link
}
How to use
 script:
        $response.replies.push( {
            type: "video",
            videoUrl: " https://...",
        } )

file

Using a file in a bot response


Parameters
  • fileUrl – link to the file.
  • fileName – name of the file.
  • mimeType – media type, a mandatory parameter.

Syntax
{
  "type":"file",                         //message type
  "fileUrl": "<https://fileUrl>",        // path to the file
  "fileName": "example.docx",            // name of the file
  "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
}

How to use
    q!: file
    a: send file
    script:
        $response.replies = $response.replies || [];
        $response.replies.push({
            type:"file",                         // type, can be audio and image
            fileUrl: "<https://fileUrl>",        // path to the file
            fileName: "example.docx",            // name of the file
            mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        });

buttons

The buttons response type displays a row of buttons in the chat


Parameters
  • text — button name.

Syntax
{ 
  "type":"buttons" //message type
  "buttons":[ 
    { 
      "text":"button", //button name
       other fields will be passed 
       directly into a messenger
    } 
  ] 
}

When adding multiple buttons to different rows, define each button under the buttons tag.

Nested data of the buttons tag should match the pattern: <json-node> -> <string>. In the left part, a valid JsonNode - a string or object that defines the text or the body of the button. In the right part - an optional string that defines the transition path when the button is pressed.

state: Buttons 
    q!: * start 
    a: Button: 
    buttons:
        "Button name" -> /NormalButtons/2    //after the arrow the path to a target state is specified

Buttons can also contain parameter substitution in the name and the specified transition path.

state: Buttons 
    q!: * start 
    a: Parameter substitution in buttons: 
    buttons: 
        "Button name" -> /NormalButtons/2 
        "parameter substitution in {{ 'name' }} as well as in transition path" -> {{ './3' }}

How to use
state: 
    a: Message text 
    buttons: 
        "Hello" -> ../Hello 
        {text:"Send contacts", request_contact: true} // 2 buttons will be located in a row 
    buttons: "Third button"

inlineButtons

Displays inline-buttons. When clicking, data or URLs (callback_data or URL, respectively) can be passed. Also, inline-buttons are displayed not under the dialogue, but inside it in the form of bot replies.


Parameters
  • text — button name.
  • url — link to go.

Syntax
{ 
  "type":"inlineButtons" //message type
  "buttons":[
    {
    "text":"button",     //button name
    "url":"http://example.com" //link to go
    } 
  ] 
}

buttons and inlineButtons cannot be applied to a single response (tag a) simultaneously. Instead, a few responses can be added to a single state and different types of buttons can be applied to each response


How to use
state: 
    a: Message text
    inlineButtons: 
        {text:"browse", url:"http://example.com"}
        {text:"buy", url:"http://example.com"} // 2 buttons will be located in a row

image

Image output.


Parameters
  • imageUrl — link to the image.
  • text — image description.

Syntax
{
  "type":"image",          //message type
  "imageUrl":"http://..."  //image url
  "text":"description",       //image description
}

How to use
script: 
    $response.replies.push( { 
        type: "image", 
        imageUrl: " https://...jpg",
        text: "image description" //optional field
    } )

raw

Passes specific channel methods.


Parameters
  • body — response body that will be transmitted to the chat system. The required parameters identifying the user in the chat will be automatically substituted.

Also optional parameters specific to each channel. For example, the method field for the telegram: "sendMessage|sendPhoto|editMessageText".


Syntax
{ 
  "type":"raw",           //message type
  "body":{ ... },         //response body
  "method":"sendMessage"  //optional parameter
}

How to use
function editText(messageId, text) {
    var $response = $jsapi.context().response;
    var reply = {
        type: "raw",
        body: {
            text: text,
            message_id: messageId,
            reply_markup: {
                "resize_keyboard": false,
            }
        },
        method: "editMessageText"
    };

switch

Switches the dialogue from the bot to the operator.


Parameters

Optional parameters:

  • firstMessage — the message that will be displayed in the operator chat. By default: the last phrase of the client.
  • closeChatPhrases — an array of strings, passing a list of commands. Using them, the client will be able to close the chat and return to the dialogue with the bot.
  • appendCloseChatButton - to control the display of the operator chat button. Accepts true/false: if true - when the operator answers, the button will be displayed, if false - not displayed. The title of the button will be taken from the specified array of lines closeChatPhrases.
  • ignoreOffline — perform a transfer to the operator, ignoring the lack of available operators. By default false.
  • oneTimeMessage — send the text of the firstMessage to the operator without performing the transfer. Designed to transmit data to the operator without entering a dialogue. By default false.
  • destination — a group of operators to which you want to redirect customers.
  • lastMessage — message that will be passed to the user after they end the conversation with closeChatPhrases.
  • attributes — prechat fields. Gets JSON as pairs {"key":"value"}. The parameters will be passed to the operator as additional information about the client.
  • hiddenAttributes — prechat fields that will not be passed to the operator. The format is similar to attributes.
  • phoneNumber — the phone number to which you want to redirect the call. Only for the telephone channel. Please, note that the number format depends on the telephony provider.
  • headers — when transferred to an operator, you can set SIP headers for the telephone channel, which will be transmitted in the invite message to the specified number. This feature is usually used for transfer of client information to AON.
  • transferChannel — specify in the field botId for transfer of call via SIP trunk, which belongs to this channel. This will apply the parameters of the connected SIP trunk.
  • continueCall — if true, the caller will be returned to the dialogue with the bot after talking with the operator, and also if the operator is not available.
  • continueRecording — if true, the conversation continues to be recorded, including the conversation with the operator and when the caller returns to the dialogue with the bot again. The call recording will be available in the dialog logs.
  • sendMessagesToOperator — if true, message history will be sent to the operator.
  • sendMessageHistoryAmount — the number of last messages that will be sent to the operator.

Syntax
{
  "type":"switch",          //message type
  "firstMessage":"..." ,    //optional parameters
  "closeChatPhrases": [".."], 
  "ignoreOffline":true|false, 
  "oneTimeMessage": true|false 
}

How to use
 $response.replies.push({
    type:"switch",
    closeChatPhrases: ["/close", "return to the conversation"],
    firstMessage: $client.history,  // last client message
});
$response.replies.push({
    type:"switch",
    phoneNumber:*****,                     // for the telephone channel
    closeChatPhrases: ["/close", "return to the conversation"],
    firstMessage: $client.history,         // last client message
    destination: catchAll.operatorGroup,   // operator group
});
$response.replies.push({
    type:"switch",
    closeChatPhrases: ["/closeLiveChat", "Close chat"],
    firstMessage: $client.history,
    lastMessage: "See you later!",
    attributes: {
                 "Name": "John",
                 "Surname": "Doe"
    }
});
$response.replies.push({
  type:"switch",
  sendMessagesToOperator: true,     //send message history to the operator
  sendMessageHistoryAmount: 20
})

To transfer the history of the client's conversations with the bot when transferring to an operator you can use preProcessand postProcess:

// saving client chat history
 init:
    $jsapi.bind({
        type: "preProcess",
        name: "savingVisitorChatHistory",
        path: "/",
        handler: function($context) {
            // initialize chat history
            $context.client.chatHistory = $context.client.chatHistory || [];
            var chatHistory = $context.client.chatHistory;
            if ($context.request.query) {
                // add chat history to array
                chatHistory.push({type: "CLIENT", text:$context.request.query});
            }
            // leave last 10 messages in the chat history
            chatHistory.splice(0, chatHistory.length - 10);
        }
    });
// saving bot chat history
    $jsapi.bind({
        type: "postProcess",
        name: "savingBotChatHistory",
        path: "/",
        handler: function($context) {
            // initialize chat history
            $context.client.chatHistory = $context.client.chatHistory || [];
            var chatHistory = $context.client.chatHistory;
            if ($context.response.replies) {
                // add bot's messages to array
                $context.response.replies
                        .filter(function(val) { return val.type === "text"; })
                        .forEach(function(val) { chatHistory.push({ type:"BOT", text: val.text }); });
            }
            // leave last 10 messages in the chat history
            chatHistory.splice(0, chatHistory.length - 10);
        }
 });

Transfer of client's conversations history with the bot to the operator's channel Salesforce:

init:
    $jsapi.bind({
        type: "preProcess",
        name: "savingVisitorChatHistory",
        path: "/",
        handler: function($context) {
            $context.client.chatHistory = $context.client.chatHistory || [];
            var chatHistory = $context.client.chatHistory;
            if ($context.request.query) {
                chatHistory.push({type:"CLIENT", text:$context.request.query});
            }
            // if the client sent a file/image/audio, add a link to them
            if ($context.request.event === 'fileEvent' || $context.request.event === 'imageEvent'
                        || $context.request.event === 'audioEvent') {
                chatHistory.push({type:"CLIENT", text:$context.request.data.eventData.url});
            }
            chatHistory.splice(0, chatHistory.length - 10);
        }
});
    $jsapi.bind({
        type: "postProcess",
        name: "savingBotChatHistory",
        path: "/",
        handler: function($context) {
            $context.client.chatHistory = $context.client.chatHistory || [];
            var chatHistory = $context.client.chatHistory;
            if ($context.response.replies) {
                // add bot's messages to array
                $context.response.replies
                    .filter(function(val) { return val.type === "text"; })
                    .forEach(function(val) { chatHistory.push({ type:"BOT", text: val.text }); });
            }
             if ($context.response.replies) {
                // add bot's images to array
                $context.response.replies
                    .filter(function(val) { return val.type === "image"; })
                    .forEach(function(val) { chatHistory.push({ type:"BOT", text: val.imageUrl }); });
            }
            if ($context.response.replies) {
                // add bot's audio messages to array
                $context.response.replies
                    .filter(function(val) { return val.type === "audio"; })
                    .forEach(function(val) { chatHistory.push({ type:"BOT", text: val.audioUrl }); });
            }
            chatHistory.splice(0, chatHistory.length - 10);
        }
});

location

The output of coordinates.


Parameters
  • lat — latitude.
  • lan — longitude.

Syntax
{
  "type": "location",    //message type
  "lat": 59.934280,      //latitude
  "lon": 30.335099       //longtitude
}

timeout

Sets the transition to the state if there is no response from the user.


Parameters
  • interval — waiting time for reaction in seconds, number.
  • targetState - state in which the bot transfers after the timeout expires.

Syntax
{
  "type":"timeout",
  "interval":10,
  "targetState":"/timeout"
}

How to use
state: time
    q!: timeout
    a: Countdown has started when you said: {{$parseTree.text}}
    a: Input something and it will be reset
    script:
        $reactions.timeout({interval: '30 seconds', targetState: '/timeout'});

state: timeout
    a: Your time is up. Thank you for the conversation! See you later.

dtmf

DTMF message (numbers / characters in tone mode) is sent. Only for calls.


Parameters

Optional parameters:

  • timeout — interval of waiting for input in milliseconds, number.
  • max — the maximum number of digits that is expected from the caller.

Syntax
$response.replies.push({type:"dtmf"});

How to use
patterns:
  $Digits = $regexp<\d+>

theme: /
    state: Main
        q!: * start
        a: Input 4 numbers in a tone mode
        script:
            $response.replies.push({
                type: 'dtmf',
                max: 4,
                timeout: 15000
            });

        state: Digits
            q: $Digits
            a: you typed {{$parseTree.text}}!
            a: Thank you! Have a good day!
            script:
                $response.replies.push({
                    type: 'hangup'
                });
  
    state: NoDigits
        q!: *
        event: noDtmfAnswerEvent
        a: You typed nothing!
        go!: /Main

hangup

Abort the call. Only for calls.


Syntax
$response.replies.push({type:"hangup"});

How to use
 script: 
        $reactions.answer("Have a nice day!")
        $response.replies = $response.replies || [];
        $response.replies.push({type:"hangup"});

htmlResponse

The htmlResponse response type is used to output the visual component for the skills created using the Interactive Canvas.


Parameters
  • updatedState – up-to-date state of the web application. Accepts a JSON object.
  • suppressMic – control device microphone. Accepts true/false; if set to true, the microphone will be muted after the visualization is displayed. An optional parameter.
  • url – web application URL.

Learn more about parameters


Syntax
{
  "type":"htmlResponse",               //message type
  "updatedState": "some",
  "suppressMic":true|false,           //optional parameter
  "url": "appUrl"                     //optional parameter
}

How to use
    script:
        var videolink = getLink("lovecraft_loading.mp4");
        var poster = getLink("main_menu.gif");
        $response.replies = $response.replies || []
        $response.replies.push({
                "type":"htmlResponse",
                "updatedState": {
                    "command": "UPDATE_STATE",
                    "video": videolink,
                    "poster": poster,
                    "buttons": [{
                        title: "Skip"
                    }]
                }
            });

crmIntegration

The crmIntegration response type is used with the Bitrix24 CRM.


Parameters
  • channelType – for the Bitrix24 CRM, specify "BITRIX".
  • task – specify the event type for the CRM, possible values:
    • LEAD_CREATION – create a lead;
    • DEAL_CREATION – create a deal;
    • DEAL_UPDATE – update a deal.
  • parameters – additional parameters for processing. A parameter is specified in the "fields[parameter_name]": "value" format.

Learn more about parameters for leads and deals

If the event is a success, event: CRM_SUCCESS_EVENT is returned to the script, otherwise event: CRM_FAILED_EVENT


How to use

Deal update script:

state: Update deal
    q!: update deal
    script:
        var reply = {type:"crmIntegration"};
        reply.channelType = "BITRIX";
        reply.task = "DEAL_UPDATE";
        reply.parameters = {
                "fields[TITLE]": "Updated deal name"
        };
        $response.replies = $response.replies || [];
        $response.replies.push(reply);

    state: CRM_SUCCESS_EVENT
        event: CRM_SUCCESS_EVENT
        script:
            $reactions.transition("/next_step");

    state: CRM_FAILED_EVENT
        event: CRM_FAILED_EVENT
        script:
            $reactions.transition("/problem_resolution");

carousel

List of items to select one of them. You can use plain text or text with an image in your bot reply.


Parameters
Parameter Type Required Description
text string yes General description
content string yes Answer content
title string yes Title
description string no Description
image string no Link to image
url string no Link to source
btnText string yes Button text

Syntax
{
  "type": "carousel",                 //answer type
  "text": "Carousel description"      //required parameter
  "content": [
      {
        "title": "Title",
        "description": "Description",
        "image": "imageUrl",
        "url": "appUrl",
        "btnText": "Button text"
      }
    ]
}

How to use

In this example, the bot displays a text message with an image. The Open button appears below the description The most modern stadium in Russia. When clicking on the button, the user redirects to the web page specified in the url parameter.

script:
  var reply = {
    "type": "carousel",
    "text": "Description",
    "content": [
      {
        "title": "Saint Petersburg Stadium",
        "description": "The most modern stadium in Russia",
        "image": "https://example.png",
        "url": "https://example.com/",
        "btnText": "Open"
      }
    ]
  }
  $response.replies.push(reply);