How to Create a Support Channel via Bitrix24 Network Open Channel

Using a Bitrix24 Network Open Channel, you can organize support for application users. After executing the scenario, the user will receive a welcome message in their messenger from the Open Channel support.

The scenario links two Bitrix24 instances:

• Support Bitrix24 — the "Bitrix24 Network" channel is connected here and the Open Channel is configured. This is where the connector code is retrieved.
• User Bitrix24 — the application is installed here, which performs both REST calls and sends the welcome message to the user.

The scenario consists of two steps.

1. Connect the Open Channel using the imopenlines.network.join method.
2. Send a welcome message to the user using the imopenlines.network.message.add method.

Both methods use the same connector code. The network bot identifier from step 1 is not required to send the message.

Scope: imopenlines

Who can execute the methods: any user

Prepare the Application and Open ChannelPrepare the Application and Open Channel

Prepare the ApplicationPrepare the Application

In the user's Bitrix24, prepare a local application without a user interface.

1. Prepare a handler address accessible from the internet, for example https://example.com/handler
2. Create a local application with an installation handler and enable the "Uses API only" option.
3. In the "Initial installation path" field, specify the handler address and grant the application the imopenlines permission.
4. In the handler, retrieve the authorization data auth and initialize the SDK.

Configure the Open ChannelConfigure the Open Channel

Perform the following actions in the support Bitrix24.

1. Open the "Contact Center" section and connect the "Bitrix24 Network" communication channel.
2. Specify a name and a short description, and add an avatar — users will be able to recognize the support channel by these details.
3. Create a new support Open Channel or select an existing one.
4. Save the settings and copy the value of the "Code" field on the connector page.

Prepare the ValuesPrepare the Values

• connectorCode — the connector code from the "Code" field. This is a 32-character string.
• userId — the user identifier from auth[user_id] in the application installation data.
• message — non-empty welcome text.

The CODE parameter contains only the connector code. In the examples below, the SDK client substitutes the OAuth token. In a direct REST request without the SDK, the token is passed as a separate parameter auth or access_token, rather than within the method parameters.

Initialize the SDKInitialize the SDK

Prepare the initialization functions following the event data processing example. In the installation handler, create an SDK client from the authorization data auth.

How to Use Examples in Documentation

const $b24 = makeClient(auth)
        

$b24 = makeServiceBuilder($request);
        

from b24pysdk.errors import BitrixAPIError
        
        client, token = make_client(auth)
        

The PHP client initialization example specifies the scope imbot,im,task. For the support scenario, replace it with imopenlines.

1. Connect an Open Channel1. Connect an Open Channel

Pass the connector code into the CODE parameter of the imopenlines.network.join method. In the examples, replace the demonstration value connectorCode with your own code. If the line is already connected, the method will return the identifier of the existing network bot.

const connectorCode = 'a588e1a88baaf301b9d0b0b33b1eefc2'
        
        try {
            const response = await $b24.actions.v2.call.make({
                method: 'imopenlines.network.join',
                params: { CODE: connectorCode },
                requestId: 'network-join',
            })
        
            if (!response.isSuccess) {
                throw new Error(response.getErrorMessages().join('; '))
            }
        } catch (error) {
            // API, transport or SDK error
            console.error(error)
        }
        

$connectorCode = 'a588e1a88baaf301b9d0b0b33b1eefc2';
        
        try {
            $response = $b24->core->call('imopenlines.network.join', [
                'CODE' => $connectorCode,
            ]);
        } catch (Throwable $e) {
            echo $e->getMessage();
        }
        

connector_code = "a588e1a88baaf301b9d0b0b33b1eefc2"
        
        try:
            response = client.imopenlines.network.join(
                code=connector_code,
            ).response
        except BitrixAPIError as error:
            print(f"Open line connection error: {error}")
        

Successful response:

{
            "result": 123
        }
        

The result value is the identifier of the network bot that represents the Open Channel in Bitrix24 chats.

2. Send a Welcome Message2. Send a Welcome Message

Pass the same connector code, the User ID, and the text to the imopenlines.network.message.add method. The method does not work with session authorization: in the application handler, use the OAuth token from the event body.

const connectorCode = 'a588e1a88baaf301b9d0b0b33b1eefc2'
        const userId = Number(auth.user_id)
        const message = 'Thanks for installing! If you have any questions, write to this chat. Have a nice day! :)'
        
        try {
            const response = await $b24.actions.v2.call.make({
                method: 'imopenlines.network.message.add',
                params: {
                    CODE: connectorCode,
                    MESSAGE: message,
                    USER_ID: userId,
                },
                requestId: 'network-message',
            })
        
            if (!response.isSuccess) {
                throw new Error(response.getErrorMessages().join('; '))
            }
        } catch (error) {
            // API, transport or SDK error
            console.error(error)
        }
        

$connectorCode = 'a588e1a88baaf301b9d0b0b33b1eefc2';
        $userId = (int)$request->request->all('auth')['user_id'];
        $message = 'Thanks for installing! If you have any questions, write to this chat. Have a nice day! :)';
        
        try {
            $response = $b24->core->call('imopenlines.network.message.add', [
                'CODE' => $connectorCode,
                'MESSAGE' => $message,
                'USER_ID' => $userId,
            ]);
        } catch (Throwable $e) {
            echo $e->getMessage();
        }
        

connector_code = "a588e1a88baaf301b9d0b0b33b1eefc2"
        user_id = int(auth["user_id"])
        message = "Thanks for installing! If you have any questions, write to this chat. Have a nice day! :)"
        
        try:
            response = client.imopenlines.network.message.add(
                code=connector_code,
                message=message,
                user_id=user_id,
            ).response
        except BitrixAPIError as error:
            print(f"Message sending error: {error}")
        

Successful response:

{
            "result": true
        }
        

Verify the ResultVerify the Result

1. In the response of the imopenlines.network.join method, the result field must contain the network bot ID.
2. In the response of the imopenlines.network.message.add method, the result field must contain the value true.
3. The User whose identifier was passed must see the welcome message from the line in the messenger.

Errors and DiagnosticsErrors and Diagnostics

If the Open Channel failed to connect or the message was not sent, determine which method returned an error and find its code in the API response or the SDK message.

Errors for Both MethodsErrors for Both Methods

Open Channel Fails to ConnectOpen Channel Fails to Connect

Check the error code of the imopenlines.network.join method.

After fixing, call the imopenlines.network.join method again.

Welcome Message Fails to SendWelcome Message Fails to Send

Check the error code of the imopenlines.network.message.add method.

Continue LearningContinue Learning

• Connect an external Open Channel to the portal using imopenlines.network.join
• Send a message to a User on behalf of an Open Channel using imopenlines.network.message.add
• Open Channels: Overview of Methods and Events