Skip to main content

$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​

MethodDescription
sendTextToClientSends a text response. Accepts a string as an argument.
sendRepliesToClientSends 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, voice assistants, and the Webim (Custom Channel API) text channel.

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 JAICP ECMAScript 6 runtime, so you can use asynchronous operations in it. However, asynchronous code in JAICP 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.

How to use​

In the following script fragment, the bot answers the user’s question about in-demand professions using ChatGPT. To do so:

While the model is generating the answer, the bot notifies the user that they need to wait a bit, and then, when the answer is ready, sends the list of in-demand professions to the channel.

Example in ECMAScript 5​

state: InDemandJobs
    q!: What professions will be in demand in 5 years
    script:
        $conversationApi.sendTextToClient("Good question! Give me a minute…");
        $conversationApi.sendRepliesToClient([{type: "image", imageUrl: "https://example.com/philosopher.png", text: "Let me think…"}]);
        var userMessage = $request.query;
        var response = $gpt.createChatCompletion([{
            role: "user",
            content: userMessage
        }]);
        $reactions.answer(response.choices[0].message.content);
        # The bot will instantly send the first text message and image to the channel, and then output a response from ChatGPT.

Example in ECMAScript 6​

require: openai.js
    name = openai
    type = scriptEs6

theme: /

    state: InDemandJobs
        q!: What professions will be in demand in 5 years
        scriptEs6:
            $reactions.answer("Good question! Let me think…");
            $response.replies.push({type: "image", imageUrl: "https://example.com/philosopher.png"});
            const userMessage = $request.query;
            openai.gptChatCompletion([{
                role: "user",
                content: userMessage
            }]).then(response => {
                $conversationApi.sendTextToClient(response.choices[0].message.content);
            });
            # The bot will instantly send the first text message and image to the channel, and then output a response from ChatGPT.

    state: ResponseWaiting
        q!: No answer yet?
        a: Just one more minute…
        # If a user asks a question while the bot is waiting a response from ChatGPT, the bot will be able to answer instantly.
tip
We have also prepared a more complex example with a translator bot using the $conversationApi methods in ECMAScript 6. You can view the source code on GitHub, and you can create a project in JAICP directly from there.