Взаимодействие встройки с полем ввода мессенджера

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

Отправить сообщение методы не могут: текст остается в поле ввода, пока пользователь не нажмет «Отправить». Собственный scope методам не нужен — они не обращаются к REST API.

Методы вызывают через пространство имен $b24.parent.message библиотеки B24JsSDK. Оно доступно с версии 1.1.0, примеры на этой странице даны для второй мажорной версии.

Условия работы методовУсловия работы методов

• приложение открыто внутри фрейма Битрикс24. Битрикс24 принимает сообщения только с адреса зарегистрированного приложения, остальные игнорирует
• SDK инициализирован через initializeB24Frame()
• встройка открыта в мессенджере, и в нем открыт чат. Подходят точки встраивания IM_TEXTAREA, IM_SIDEBAR и IM_CONTEXT_MENU. Чтобы зарегистрировать любую из них методом placement.bind, приложению нужны scope placement и im
• пользователь работает в веб-версии Битрикс24. В мобильном приложении обработчика этих методов нет — встройка IMMOBILE_CONTEXT_MENU ответа не получит

Из IM_NAVIGATION текущий чат не определяется, но обработчик на месте и отвечает. Ошибки не будет: im:getImTextareaContent вернет пустую строку, а im:setImTextareaContent ответит success: true, хотя текст в поле ввода не появится.

Если встройка открыта там, где мессенджер не загружен, обработчика нет вовсе: ответ не придет, и вызов завершится по таймауту isSafely.

Формат вызоваФормат вызова

$b24.parent.message.send(method, params)

Первым параметром идет имя метода, вторым — объект с его параметрами. Состав объекта разобран в разделах методов ниже.

Вызов возвращает промис. Битрикс24 отвечает объектом, и промис завершается этим объектом — и при успехе, и при ошибке обработчика. Исключением ошибка обработчика не приходит, а тип результата SDK не описывает, поэтому исход определяйте по набору полей в ответе.

Битрикс24 принимает сообщение, только когда имя метода известно, а requestId — непустая строка. Иначе сообщение отбрасывается молча: ответа не будет, а промис без isSafely останется незавершенным. Поэтому вызывайте методы с isSafely: true.

isSafely и safelyTime обрабатывает сам SDK: в Битрикс24 они не уходят и на работу метода не влияют — ими задается только поведение промиса, когда ответа нет.

Параллельные вызовы разбирать вручную не нужно: SDK помечает каждое сообщение своим служебным ключом и возвращает ответ в тот промис, который его ждет. Битрикс24 возвращает requestId без изменений — он нужен вам, чтобы узнать свой запрос в логах.

Из BX24.js эти методы не вызвать. Функция BX24.placement.call() отправляет сообщение без поля requestId, а такое сообщение Битрикс24 отбрасывает — работать с полем ввода мессенджера можно только через B24JsSDK.

Метод im:getImTextareaContentМетод im:getImTextareaContent

Метод im:getImTextareaContent возвращает текущий текст из поля ввода активного чата.

Параметры методаПараметры метода

Обязательные параметры отмечены *

Примеры кодаПримеры кода

Как использовать примеры в документации

Прочитать черновик пользователя и вывести его в консоль:

// Модуль ESM: await на верхнем уровне работает в сборщике или при type="module"
import { initializeB24Frame, Text } from '@bitrix24/b24jssdk'

const $b24 = await initializeB24Frame()

const responseGet = await $b24.parent.message.send(
    'im:getImTextareaContent',
    {
        requestId: Text.getUuidRfc4122(),
        isSafely: true,
        safelyTime: 1500
    }
)

if (typeof responseGet.text === 'string') {
    console.log(responseGet.text)
}

// UMD-сборка подключена тегом script, все доступно через переменную B24Js
const $b24 = await B24Js.initializeB24Frame()

const responseGet = await $b24.parent.message.send(
    'im:getImTextareaContent',
    {
        requestId: B24Js.Text.getUuidRfc4122(),
        isSafely: true,
        safelyTime: 1500
    }
)

if (typeof responseGet.text === 'string') {
    console.log(responseGet.text)
}

Обработка ответаОбработка ответа

{
    "requestId": "019323ac-8ace-725b-a3dc-6a7c333da066",
    "text": "Добрый день! Уточните, пожалуйста, номер заказа"
}

Ответы, в которых поля text нет, разобраны в разделе Обработка ошибок.

Возвращаемые данныеВозвращаемые данные

Метод im:setImTextareaContentМетод im:setImTextareaContent

Метод im:setImTextareaContent вставляет текст в поле ввода активного чата.

Параметры методаПараметры метода

Обязательные параметры отмечены *

Примеры кодаПримеры кода

Как использовать примеры в документации

Дописать текст в конец черновика с новой строки, не стирая набранное пользователем:

// Модуль ESM: await на верхнем уровне работает в сборщике или при type="module"
import { initializeB24Frame, Text } from '@bitrix24/b24jssdk'

const $b24 = await initializeB24Frame()

const responseSet = await $b24.parent.message.send(
    'im:setImTextareaContent',
    {
        requestId: Text.getUuidRfc4122(),
        text: 'Заказ №1024 отправлен, трек-номер придет в течение дня',
        withNewLine: true,
        replace: false,
        isSafely: true,
        safelyTime: 1500
    }
)

if (responseSet.success !== true) {
    console.log('Текст вставить не удалось', responseSet)
}

// UMD-сборка подключена тегом script, все доступно через переменную B24Js
const $b24 = await B24Js.initializeB24Frame()

const responseSet = await $b24.parent.message.send(
    'im:setImTextareaContent',
    {
        requestId: B24Js.Text.getUuidRfc4122(),
        text: 'Заказ №1024 отправлен, трек-номер придет в течение дня',
        withNewLine: true,
        replace: false,
        isSafely: true,
        safelyTime: 1500
    }
)

if (responseSet.success !== true) {
    console.log('Текст вставить не удалось', responseSet)
}

Обработка ответаОбработка ответа

{
    "requestId": "019323ac-8ace-725b-a3dc-6a7c333da066",
    "success": true
}

Ответы, в которых поля success нет, разобраны в разделе Обработка ошибок.

Возвращаемые данныеВозвращаемые данные

Оба метода в одном сценарииОба метода в одном сценарии

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

Как использовать примеры в документации

import { initializeB24Frame, Text } from '@bitrix24/b24jssdk'

async function rewriteDraft(): Promise<void> {
    const $b24 = await initializeB24Frame()

    const responseGet = await $b24.parent.message.send(
        'im:getImTextareaContent',
        {
            requestId: Text.getUuidRfc4122(),
            isSafely: true,
            safelyTime: 1500
        }
    )

    // Ошибка и таймаут приходят без поля text
    if (typeof responseGet.text !== 'string') {
        console.log('Текст получить не удалось', responseGet)
        return
    }

    // Пустая строка означает, что поле пустое или чат не определен
    if (responseGet.text.length === 0) {
        return
    }

    const responseSet = await $b24.parent.message.send(
        'im:setImTextareaContent',
        {
            text: responseGet.text.toUpperCase(),
            requestId: Text.getUuidRfc4122(),
            replace: true,
            isSafely: true,
            safelyTime: 1500
        }
    )

    if (responseSet.success !== true) {
        console.log('Текст вставить не удалось', responseSet)
    }
}

document.addEventListener('DOMContentLoaded', () => {
    rewriteDraft().catch((error) => console.log('Не удалось запустить встройку', error))
})

// UMD-сборка подключена тегом script, все доступно через переменную B24Js
async function rewriteDraft() {
    const $b24 = await B24Js.initializeB24Frame()

    const responseGet = await $b24.parent.message.send(
        'im:getImTextareaContent',
        {
            requestId: B24Js.Text.getUuidRfc4122(),
            isSafely: true,
            safelyTime: 1500
        }
    )

    // Ошибка и таймаут приходят без поля text
    if (typeof responseGet.text !== 'string') {
        console.log('Текст получить не удалось', responseGet)
        return
    }

    // Пустая строка означает, что поле пустое или чат не определен
    if (responseGet.text.length === 0) {
        return
    }

    const responseSet = await $b24.parent.message.send(
        'im:setImTextareaContent',
        {
            text: responseGet.text.toUpperCase(),
            requestId: B24Js.Text.getUuidRfc4122(),
            replace: true,
            isSafely: true,
            safelyTime: 1500
        }
    )

    if (responseSet.success !== true) {
        console.log('Текст вставить не удалось', responseSet)
    }
}

document.addEventListener('DOMContentLoaded', () => {
    rewriteDraft().catch((error) => console.log('Не удалось запустить встройку', error))
})

Обработка ошибокОбработка ошибок

Кодов ошибок методы не возвращают. Исход вызова определяют по набору полей в ответе.

Сбой инициализации в этот перечень не входит: вне фрейма Битрикс24 промис initializeB24Frame() отклоняется ошибкой SdkError с кодом JSSDK_CLIENT_SIDE_WARNING еще до вызова методов. Как это обработать, описано на странице Установка и использование B24JsSDK.

Ошибка обработчикаОшибка обработчика

Битрикс24 принял вызов, но обработчик завершился исключением. Его текст приходит в поле message. Штатного сценария, который к этому приводит, нет: неопределенный чат к ошибке не ведет, такой случай разобран в разделе Условия работы методов.

{
    "requestId": "019323ac-8ace-725b-a3dc-6a7c333da066",
    "message": "Cannot read properties of undefined"
}

Ответа не былоОтвета не было

Битрикс24 не ответил за safelyTime. Так бывает, если сообщение отбросили из-за пустого requestId или встройка открыта там, где мессенджер не загружен. Поля requestId в таком объекте нет: его формирует не Битрикс24, а сам SDK по своему таймеру.

{
    "isSafely": true
}

Фрейм уничтоженФрейм уничтожен

Единственный случай, когда вызов приходит исключением: приложение уничтожило фрейм методом destroy(), не дождавшись ответа. SDK отклоняет все незавершенные вызовы ошибкой SdkError с кодом JSSDK_FRAME_DISPOSED. С этим сталкиваются встройки на Vue, React и Nuxt, если компонент размонтируется во время запроса — оборачивайте вызов в try/catch или вешайте catch() на промис.

Пример реализацииПример реализации

Скачайте пример встройки — он показывает оба метода в работе.

Как устроен примерКак устроен пример

1. SDK подключается в браузере через UMD-скрипт @bitrix24/b24jssdk.
2. При загрузке страницы вызывается B24Js.initializeB24Frame().
3. Кнопка Get text отправляет im:getImTextareaContent и показывает поле text из ответа.
4. Кнопка Set text отправляет im:setImTextareaContent и вставляет текст в поле ввода чата.
5. Флаги withNewLine и replace берутся из чекбоксов в форме.
6. Результаты запросов выводятся в блок #log и в console.

Продолжите изучениеПродолжите изучение

• Установка и использование B24JsSDK
• Виджеты в мессенджере: обзор точек встраивания
• Виджет над полем ввода IM_TEXTAREA
• Виджет для сайдбара IM_SIDEBAR
• Пункт контекстного меню сообщения IM_CONTEXT_MENU
• Зарегистрировать обработчик виджета placement.bind
• Взаимодействие с UI: обзор методов