$conversationApi

Встроенный сервис $conversationApi позволяет мгновенно отправлять сообщения бота в канал, не дожидаясь окончания обработки запроса пользователя.

Вы можете использовать методы этого сервиса, например, чтобы предупредить пользователя о подготовке ответа, пока бот ожидает ответ от LLM-модели, производит вычисления или получает информацию из CRM-системы.

Методы

Метод	Что делает
sendTextToClient	Отправляет текстовый ответ. В качестве аргумента принимает строку.
sendRepliesToClient	Отправляет ответы с различными типами: например, изображения и кнопки. В качестве аргумента принимает массив объектов replies.

предупреждение

Методы не поддерживаются в ботах для звонков, в голосовых ассистентах и в текстовом канале Webim (Custom Channel API).

Принцип работы

Сервис $conversationApi поддерживается как в классической среде исполнения JavaScript (ECMAScript 5) в теге script, так и в среде исполнения ECMAScript 6 в теге scriptEs6. Однако из-за особенностей того, как в них исполняется код, использовать этот сервис нужно по-разному.

ECMAScript 5

В среде исполнения ECMAScript 5 обработка запроса пользователя всегда является синхронной: бот получает запрос, переходит в нужный стейт и выполняет реакции из тегов реакций, в том числе код из тегов script. Чтобы отправить ответ бота в канал, можно вызывать методы встроенного сервиса $reactions или добавлять ответы в $response. Однако эти ответы отправляются в канал не мгновенно, а только после того, как все реакции будут выполнены.

state: 1
    script:
        $reactions.answer("Первый ответ");
        $reactions.answer("Второй ответ");
        $http.get("https://httpbin.org/delay/5"); // HTTP-запрос длительностью 5 секунд
        $response.replies.push({type: "text", text: "Третий ответ"});
        # После задержки в пять секунд бот отправит в канал сразу три ответа.

В отличие от отправки ответов через $reactions и $response, отправка через $conversationApi происходит мгновенно, а оставшиеся реакции выполняются уже после нее.

state: 2
    script:
        $reactions.answer("Первый ответ");
        $conversationApi.sendTextToClient("Второй ответ");
        $http.get("https://httpbin.org/delay/5"); // HTTP-запрос длительностью 5 секунд
        $response.replies.push({type: "text", text: "Третий ответ"});
        # Бот сразу отправит в канал второй ответ, а после задержки в пять секунд дошлет первый и третий.

ECMAScript 6

В среде исполнения ECMAScript 6 для запуска кода в JAICP используется платформа Node.js, поэтому вы можете использовать в нем асинхронные операции. Однако у асинхронного кода в JAICP есть важное ограничение: чтобы использовать его результат для ответа пользователю через встроенный сервис $reactions, его всегда нужно дожидаться при помощи ключевого слова await. Это связано с тем, что методы $reactions являются синхронными и работают только во время обработки запроса.

state: 3
    scriptEs6:
        $reactions.answer("Первый ответ");
        await new Promise(resolve => setTimeout(resolve, 5000)); // Таймаут длительностью 5 секунд
        $reactions.answer("Второй ответ");
        setTimeout(() => $reactions.answer("Третий ответ"), 5000);
        # После задержки в пять секунд бот отправит в канал первый и второй ответ.
        # Код на последней строке будет выполнен на следующей итерации цикла событий. Третий ответ уже не будет отправлен в канал.

Методы сервиса $conversationApi в среде исполнения ECMAScript 6 так же отправляют ответ в канал мгновенно, но кроме того, они делают это асинхронно и не привязаны к обработке запроса пользователя. Поэтому вы можете вызывать их из функций обратного вызова, не дожидаясь, пока они будут вызваны.

state: 4
    scriptEs6:
        $conversationApi.sendTextToClient("Первый ответ");
        await new Promise(resolve => setTimeout(resolve, 5000)); // Таймаут длительностью 5 секунд
        $reactions.answer("Второй ответ");
        setTimeout(() => $conversationApi.sendTextToClient("Третий ответ"), 5000);
        # Бот сразу отправит в канал первый ответ, через пять секунд второй, а еще через пять секунд третий.
        # При этом бот готов обрабатывать новые сообщения от пользователя уже после второго ответа, не дожидаясь третьего.

Использование в сценарии

В следующем фрагменте сценария бот отвечает на вопрос пользователя о востребованных профессиях с помощью ChatGPT. Для этого:

• В теге script вызывается встроенный метод $gpt.createChatCompletion.
• В теге scriptEs6 бот обращается напрямую к OpenAI API. Для этого к боту подключается специализированный npm-пакет.

Пока модель генерирует ответ, бот предупреждает пользователя о том, что нужно немного подождать, а затем, когда ответ готов, выводит список востребованных профессий в канал.

Пример в ECMAScript 5

state: InDemandJobs
    q!: Какие профессии будут востребованы через 5 лет
    script:
        $conversationApi.sendTextToClient("Хороший вопрос! Дай мне минутку подумать…");
        $conversationApi.sendRepliesToClient([{type: "image", imageUrl: "https://example.com/philosopher.png", text: "Думаю…"}]);
        var userMessage = $request.query;
        var response = $gpt.createChatCompletion([{
            role: "user",
            content: userMessage
        }]);
        $reactions.answer(response.choices[0].message.content);
        # Бот сразу отправит в канал первое текстовое сообщение и изображение, а затем выведет ответ от ChatGPT.

Пример в ECMAScript 6

main.sc

require: openai.js
    name = openai
    type = scriptEs6

theme: /

    state: InDemandJobs
        q!: Какие профессии будут востребованы через 5 лет
        scriptEs6:
            $reactions.answer("Хороший вопрос! Дай мне минутку подумать…");
            $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);
            });
            # Бот сразу отправит в канал текстовое сообщение и изображение, а затем выведет ответ от ChatGPT.

    state: ResponseWaiting
        q!: Почему ты молчишь
        a: Я еще думаю…
        # Если пользователь задаст вопрос во время ожидания ответа от ChatGPT, бот сможет сразу на него ответить.

openai.js

import OpenAI from 'openai';

const openai = new OpenAI({
    apiKey: '<ваш-токен-OpenAI>',
});

async function gptChatCompletion(messages) {
    const completion = await openai.chat.completions.create({
        messages: messages,
        model: 'gpt-3.5-turbo',
    });
    return completion;
}

export default {
    gptChatCompletion
};

package.json

{
    "dependencies": {
        "openai": "^4.8.0"
    }
}

подсказка

Мы также подготовили более сложный пример бота-переводчика c использованием методов $conversationApi в ECMAScript 6. Вы можете просмотреть его исходный код на GitHub, а оттуда же сразу создать проект в JAICP.