$conversationApi

The $conversationApi built-in service allows you to instantly send bot messages to the channel without waiting for the user’s request to be processed.

You can use the methods of this service, for example, to notify the user that a response is being prepared, while the bot is waiting for a response from the LLM, performing calculations, or receiving information from the CRM system.

Methods

Method	Description
sendTextToClient	Sends a text response. Accepts a string as an argument.
sendRepliesToClient	Sends replies with different types: for example, images and buttons. Takes replies, which is an array of objects, as an argument.

caution

The methods are not supported in phone bots.

How it works

The $conversationApi service is supported both in the script tag in the old ECMAScript 5 runtime and in the scriptEs6 tag in the ECMAScript 6 runtime. You need to use the service differently in these environments because they have different code execution features.

ECMAScript 5

In the ECMAScript 5 runtime, user request processing is always synchronous: the bot receives a request, transitions to the necessary state, and performs reactions from reaction tags, including code from script tags. To send a bot response to a channel, you can call the methods of the $reactions built-in service or add responses to $response. However, these responses are sent to the channel not instantly, but only after all reactions are completed.

state: 1
    script:
        $reactions.answer("First response");
        $reactions.answer("Second response");
        $http.get("https://httpbin.org/delay/5"); // HTTP request that lasts 5 seconds
        $response.replies.push({type: "text", text: "Third response"});
        # After a five-second delay, the bot will send all three responses to the channel at once.

Unlike sending responses via $reactions and $response, responses via $conversationApi are sent instantly, and the remaining reactions are performed after them.

state: 2
    script:
        $reactions.answer("First response");
        $conversationApi.sendTextToClient("Second response");
        $http.get("https://httpbin.org/delay/5"); // HTTP request that lasts 5 seconds
        $response.replies.push({type: "text", text: "Third response"});
        # Bot will instantly send the second response to the channel, and after a five-second delay, it will send the first and third responses.

ECMAScript 6

The Node.js platform is used to execute code in the Tovie Platform ECMAScript 6 runtime, so you can use asynchronous operations in it. However, asynchronous code in Tovie Platform has an important limitation: to use its result as a response via the built-in $reactions service, you must always wait for the result using the await keyword. This is because the $reactions methods are synchronous and only work during request processing.

state: 3
    scriptEs6:
        $reactions.answer("First response");
        await new Promise(resolve => setTimeout(resolve, 5000)); // 5-second timeout
        $reactions.answer("Second response");
        setTimeout(() => $reactions.answer("Third response"), 5000);
        # After a five-second delay, the bot will send the first and second responses to the channel.
        # The code on the last line will be executed in the next event loop iteration. The third response will not be sent to the channel.

The $conversationApi methods in the ECMAScript 6 runtime also send a response to the channel instantly, but in addition, they do it asynchronously and are not tied to the user request processing. So, you can call them via callback functions without waiting for the methods to be executed.

state: 4
    scriptEs6:
        $conversationApi.sendTextToClient("First response");
        await new Promise(resolve => setTimeout(resolve, 5000)); // 5-second timeout
        $reactions.answer("Second response");
        setTimeout(() => $conversationApi.sendTextToClient("Third response"), 5000);
        # The bot sends the first response instantly, the second one after five seconds, and the third one after five more seconds.
        # In this case, the bot is ready to process new requests from the user after the second response, without waiting for the third one.