Interaction of the Widget with the Messenger Input Field

An application widget in the messenger works with the input field of the active chat through two methods. The application calls them from its own frame, while Bitrix24 itself changes the input field. The application needs no access to the messenger interface.

The methods cannot send a message: the text stays in the input field until the user clicks Send. The methods require no scope of their own — they do not call the REST API.

The methods are called through the $b24.parent.message namespace of the B24JsSDK library. The namespace is available since version 1.1.0, and the examples on this page are given for the second major version.

Conditions for the Methods to WorkConditions for the Methods to Work

• the application is opened inside the Bitrix24 frame. Bitrix24 accepts messages only from the address of a registered application and ignores the rest
• the SDK is initialized via initializeB24Frame()
• the widget is opened in the messenger, and a chat is opened in it. The suitable placements are IM_TEXTAREA, IM_SIDEBAR, and IM_CONTEXT_MENU. To register any of them with the placement.bind method, the application needs the placement and im scopes
• the user works in the web version of Bitrix24. The mobile application has no handler for these methods — the IMMOBILE_CONTEXT_MENU widget receives no response

In IM_NAVIGATION, the current chat is not determined, but the handler is in place and responds. There is no error: im:getImTextareaContent returns an empty string, and im:setImTextareaContent responds with success: true, even though the text does not appear in the input field.

If the widget is opened where the messenger is not loaded, there is no handler at all: no response arrives, and the call ends by the isSafely timeout.

Call FormatCall Format

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

The first parameter is the name of the method, the second one is an object with its parameters. The composition of the object is covered in the method sections below.

The call returns a promise. Bitrix24 responds with an object, and the promise resolves with that object — both on success and on a handler error. A handler error does not arrive as an exception, and the SDK does not describe the type of the result, so determine the outcome by the set of fields in the response.

Bitrix24 accepts a message only when the name of the method is known and requestId is a non-empty string. Otherwise the message is discarded silently: no response arrives, and a promise without isSafely stays unresolved. Therefore, call the methods with isSafely: true.

isSafely and safelyTime are handled by the SDK itself: they are not sent to Bitrix24 and do not affect the work of the method — they only define the behavior of the promise when there is no response.

Parallel calls do not have to be sorted out manually: the SDK marks every message with its own service key and returns the response to the promise that waits for it. Bitrix24 returns requestId unchanged — you need it to recognize your request in the logs.

These methods cannot be called from BX24.js. The BX24.placement.call() function sends a message without the requestId field, and Bitrix24 discards such a message — the messenger input field can only be worked with through B24JsSDK.

Method im:getImTextareaContentMethod im:getImTextareaContent

The method im:getImTextareaContent returns the current text from the input field of the active chat.

Method ParametersMethod Parameters

Required parameters are marked with *

Code ExamplesCode Examples

How to Use Examples in Documentation

Read the draft of the user and output it to the console:

// ESM module: top-level await works in a bundler or with 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)
        }
        

// The UMD build is included with a script tag, everything is available through the B24Js variable
        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)
        }
        

Response HandlingResponse Handling

{
            "requestId": "019323ac-8ace-725b-a3dc-6a7c333da066",
            "text": "Good afternoon! Could you please confirm the order number"
        }
        

The responses that have no text field are covered in the Error Handling section.

Returned DataReturned Data

Method im:setImTextareaContentMethod im:setImTextareaContent

The method im:setImTextareaContent inserts text into the input field of the active chat.

Method ParametersMethod Parameters

Required parameters are marked with *

Code ExamplesCode Examples

How to Use Examples in Documentation

Append text to the end of the draft on a new line, without erasing what the user has typed:

// ESM module: top-level await works in a bundler or with 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: 'Order #1024 has been shipped, the tracking number will arrive during the day',
                withNewLine: true,
                replace: false,
                isSafely: true,
                safelyTime: 1500
            }
        )
        
        if (responseSet.success !== true) {
            console.log('Failed to insert the text', responseSet)
        }
        

// The UMD build is included with a script tag, everything is available through the B24Js variable
        const $b24 = await B24Js.initializeB24Frame()
        
        const responseSet = await $b24.parent.message.send(
            'im:setImTextareaContent',
            {
                requestId: B24Js.Text.getUuidRfc4122(),
                text: 'Order #1024 has been shipped, the tracking number will arrive during the day',
                withNewLine: true,
                replace: false,
                isSafely: true,
                safelyTime: 1500
            }
        )
        
        if (responseSet.success !== true) {
            console.log('Failed to insert the text', responseSet)
        }
        

Response HandlingResponse Handling

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

The responses that have no success field are covered in the Error Handling section.

Returned DataReturned Data

Both Methods in One ScenarioBoth Methods in One Scenario

The application takes the typed text, processes it on its own side, and returns the result to the input field. The example rewrites the draft of the user in uppercase.

How to Use Examples in Documentation

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
                }
            )
        
            // An error and a timeout arrive without the text field
            if (typeof responseGet.text !== 'string') {
                console.log('Failed to retrieve the text', responseGet)
                return
            }
        
            // An empty string means that the field is empty or the chat is not determined
            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('Failed to insert the text', responseSet)
            }
        }
        
        document.addEventListener('DOMContentLoaded', () => {
            rewriteDraft().catch((error) => console.log('Failed to start the widget', error))
        })
        

// The UMD build is included with a script tag, everything is available through the B24Js variable
        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
                }
            )
        
            // An error and a timeout arrive without the text field
            if (typeof responseGet.text !== 'string') {
                console.log('Failed to retrieve the text', responseGet)
                return
            }
        
            // An empty string means that the field is empty or the chat is not determined
            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('Failed to insert the text', responseSet)
            }
        }
        
        document.addEventListener('DOMContentLoaded', () => {
            rewriteDraft().catch((error) => console.log('Failed to start the widget', error))
        })
        

Error HandlingError Handling

The methods return no error codes. The outcome of a call is determined by the set of fields in the response.

An initialization failure is not on this list: outside the Bitrix24 frame, the initializeB24Frame() promise is rejected with an SdkError error with the code JSSDK_CLIENT_SIDE_WARNING before the methods are called at all. How to handle this is described on the Installation and Usage of B24JsSDK page.

Handler ErrorHandler Error

Bitrix24 has accepted the call, but the handler has ended with an exception. Its text arrives in the message field. There is no standard scenario that leads to this: an undetermined chat does not cause an error, and that case is covered in the Conditions for the Methods to Work section.

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

No Response ArrivedNo Response Arrived

Bitrix24 has not responded within safelyTime. This happens when the message was discarded because of an empty requestId, or when the widget is opened where the messenger is not loaded. Such an object has no requestId field: it is formed by the SDK on its own timer, not by Bitrix24.

{
            "isSafely": true
        }
        

The Frame Was DestroyedThe Frame Was Destroyed

This is the only case when a call arrives as an exception: the application destroyed the frame with the destroy() method without waiting for a response. The SDK rejects all pending calls with an SdkError error with the code JSSDK_FRAME_DISPOSED. Widgets built with Vue, React, and Nuxt run into this when a component is unmounted during a request — wrap the call in try/catch or attach a catch() to the promise.

Implementation ExampleImplementation Example

Download the example widget — it shows both methods at work.

How the Example WorksHow the Example Works

1. The SDK is connected in the browser via the UMD script @bitrix24/b24jssdk.
2. Upon page load, B24Js.initializeB24Frame() is called.
3. The Get text button sends im:getImTextareaContent and displays the text field from the response.
4. The Set text button sends im:setImTextareaContent and inserts text into the chat input field.
5. The flags withNewLine and replace are taken from checkboxes in the form.
6. The results of the requests are displayed in the #log block and in the console.

Continue LearningContinue Learning

• Installing and Using B24JsSDK
• Widgets in Messenger: Overview of Embedding Points
• Widget Above the IM_TEXTAREA Input Field
• Widget for the IM_SIDEBAR
• IM_CONTEXT_MENU Message Context Menu Item
• Register a Widget Handler placement.bind
• Interaction with UI: Overview of Methods