Перейти к основному содержимому

$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. Для этого:

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

Пример в 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​

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