Как создать канал поддержки через открытую линию Битрикс24 Network

С помощью открытой линии Битрикс24 Network можно организовать поддержку пользователей приложения. После выполнения сценария пользователь получит в мессенджере приветственное сообщение от имени открытой линии поддержки.

Сценарий связывает два Битрикс24:

• Битрикс24 поддержки — в нем подключен канал «Битрикс24 Network» и настроена открытая линия. Отсюда берется код коннектора
• Битрикс24 пользователя — в нем установлено приложение, которое выполняет оба REST-вызова и отправляет приветствие пользователю

Сценарий состоит из двух шагов.

1. Подключить открытую линию методом imopenlines.network.join
2. Отправить пользователю приветствие методом imopenlines.network.message.add

Оба метода используют один код коннектора. Идентификатор network-бота из шага 1 для отправки сообщения не требуется.

Scope: imopenlines

Кто может выполнить методы: любой пользователь

Подготовьте приложение и открытую линиюПодготовьте приложение и открытую линию

Подготовьте приложениеПодготовьте приложение

В Битрикс24 пользователя подготовьте локальное приложение без интерфейса.

1. Подготовьте адрес обработчика, доступный из интернета, например https://example.com/handler
2. Создайте локальное приложение с обработчиком установки и включите опцию «Использует только API»
3. В поле «Путь для первоначальной установки» укажите адрес обработчика и предоставьте приложению право imopenlines
4. В обработчике получите данные авторизации auth и инициализируйте SDK

Настройте открытую линиюНастройте открытую линию

Следующие действия выполните в Битрикс24 поддержки.

1. Откройте раздел «Контакт-центр» и подключите канал коммуникации «Битрикс24 Network»
2. Укажите название и краткое описание, добавьте аватар — по ним пользователи смогут узнать канал поддержки
3. Создайте новую открытую линию поддержки или выберите существующую
4. Сохраните настройки и скопируйте значение поля «Код» на странице коннектора

Подготовьте значенияПодготовьте значения

• connectorCode — код коннектора из поля «Код». Это строка из 32 символов
• userId — идентификатор пользователя из auth[user_id] в данных установки приложения
• message — непустой текст приветствия

Параметр CODE содержит только код коннектора. В примерах ниже OAuth-токен подставляет клиент SDK. При прямом REST-запросе без SDK токен передается отдельным параметром auth или access_token, а не внутри параметров метода.

Инициализируйте SDKИнициализируйте SDK

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

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

const $b24 = makeClient(auth)
        

$b24 = makeServiceBuilder($request);
        

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

В примере инициализации PHP-клиента указан scope imbot,im,task. Для сценария поддержки замените его на imopenlines.

1. Подключите открытую линию1. Подключите открытую линию

Передайте код коннектора в параметр CODE метода imopenlines.network.join. В примерах замените демонстрационное значение connectorCode своим кодом. Если линия уже подключена, метод вернет идентификатор существующего network-бота.

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, транспорта или SDK
            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"Ошибка подключения открытой линии: {error}")
        

Успешный ответ:

{
            "result": 123
        }
        

Значение result — идентификатор network-бота, который представляет открытую линию в чатах Битрикс24.

2. Отправьте приветственное сообщение2. Отправьте приветственное сообщение

Передайте тот же код коннектора, ID пользователя и текст в метод imopenlines.network.message.add. Метод не работает с сессионной авторизацией: в обработчике приложения используйте OAuth-токен из тела события.

const connectorCode = 'a588e1a88baaf301b9d0b0b33b1eefc2'
        const userId = Number(auth.user_id)
        const message = 'Спасибо за установку! Если будут вопросы — пишите в этот чат. Хорошего дня! :)'
        
        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, транспорта или SDK
            console.error(error)
        }
        

$connectorCode = 'a588e1a88baaf301b9d0b0b33b1eefc2';
        $userId = (int)$request->request->all('auth')['user_id'];
        $message = 'Спасибо за установку! Если будут вопросы — пишите в этот чат. Хорошего дня! :)';
        
        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 = "Спасибо за установку! Если будут вопросы — пишите в этот чат. Хорошего дня! :)"
        
        try:
            response = client.imopenlines.network.message.add(
                code=connector_code,
                message=message,
                user_id=user_id,
            ).response
        except BitrixAPIError as error:
            print(f"Ошибка отправки сообщения: {error}")
        

Успешный ответ:

{
            "result": true
        }
        

Проверим результатПроверим результат

1. В ответе метода imopenlines.network.join в поле result должен быть ID network-бота
2. В ответе метода imopenlines.network.message.add в поле result должно быть значение true
3. Пользователь, идентификатор которого передали, должен увидеть в мессенджере приветственное сообщение от имени линии

Ошибки и диагностикаОшибки и диагностика

Если открытая линия не подключилась или сообщение не отправилось, определите, какой метод вернул ошибку, и найдите ее код в ответе API или сообщении SDK.

Ошибки обоих методовОшибки обоих методов

Открытая линия не подключаетсяОткрытая линия не подключается

Проверьте код ошибки метода imopenlines.network.join.

После исправления повторно вызовите метод imopenlines.network.join.

Приветственное сообщение не отправляетсяПриветственное сообщение не отправляется

Проверьте код ошибки метода imopenlines.network.message.add.

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

• Подключить внешнюю открытую линию к порталу imopenlines.network.join
• Отправить сообщение пользователю от имени открытой линии imopenlines.network.message.add
• Открытые линии: обзор методов и событий