Универсальный механизм отправки сообщений

Битрикс24 умеет отправлять SMS не только из бизнес-процессов и роботов CRM, но и из карточки CRM (которая доступна везде, включая бесплатный тариф без бизнес-процессов). Для решения этой задачи есть соответствующий специальный REST для служб сообщений. В первую очередь его используют для интеграции с SMS, но вообще это универсальный механизм и в дальнейшем его можно использовать для отправки сообщений в произвольные источники.

Авторам интеграций с SMS-провайдерами рекомендуется перевести свои приложения на новый REST, чтобы у пользователей не было проблем с установкой на бесплатном тарифе. И, несмотря на прозрачность вызовов существующих провайдеров для бизнес-процессов и роботов CRM, лучше работать с методами REST для службы сообщений. Тем более, что только эти методы позволят не только отправлять SMS, но и сообщать Битрикс24 о статусе отправленных сообщений. Этот статус пользователи видят прямо в карточке CRM (а в будущем увидят и в отчетах инструментов CRM-маркетинга).

Рассмотрим практический пример того, как можно быстро сделать интеграцию с SMS-провайдером.

Скачать архив примера:

  Для начала

Чтобы стать технологическим партнером 1С-Битрикс, достаточно заполнить анкету: указать общую информацию, а также данные для дальнейшей авторизации в партнерском кабинете.

Обратите внимание на поле Код партнера - это префикс, который будет подставляться в дальнейшем в символьный код, идентифицирующий ваши решения в нашем каталоге. Если взять в качестве примера решение по интеграции со Stripe (https://www.bitrix24.ru/apps/?app=integrations24ru.stripe), то integrations24ru является как раз этим кодом партнера (разработчика решения), а код stripe является кодом конкретного решения, который вы укажите в дальнейшем при заполнении формы регистрации решения.

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

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

Заполните доступные разделы системы (1) для данного примера значением "Сервис сообщений". Битрикс24 в этом случае будет сам вызывать наш провайдер из нужных точек в интерфейсе: из бизнес-процессов, из роботов CRM, из карточки CRM и так далее. Ознакомьтесь с правилами публикации (2). Это необходимо для понимая требований, которые накладываются на тиражные решения.

В отличие от локальных приложений, тиражные решения состоят из версий. Каждая версия в дальнейшем подается на модерацию. (При модерации версии проверяется и карточка приложения). На этапе разработки и тестирования модерация не нужна, вы сами занимаетесь разработкой и доведением своего решения до полнофункционального состояния, включая тестовые установки на своих Битрикс24, и только потом подаете решение на модерацию.

После добавления версии приложения необходимо заполнить название (1) код приложения (2), категории (3), описание приложения (4), ценовую политику (5) и протестировать (6):

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

  Общая логика приложения

Приложение регистрирует в конкретном Битрикс24 некий обработчик. Когда пользователь (или автоматический процесс) на стороне Битрикс24 хочет отправить SMS, он дергает этот обработчик и передает в него текст и номер телефона получателя. Обработчик (зная параметры вызова API SMS-оператора) отправляет SMS. Вот такая простая схема:

В нашем примере, скрипт install.php запросит у пользователя параметры для подключения API SMS-оператора и сохраняет их на своей стороне в привязке к конкретному Битрикс24. В таблице БД, например. Этот же скрипт регистрирует так называемый "провайдер сообщений" в Битрикс24, обращаясь к соответствующему методу REST. Фактически, это и будет регистрацией обработчика, который реализуется в примере в файле handler.php по адресу https://mydomain.ru/sms/handler.php. Если регистрация прошла успешно, install.php должен завершить установку.

В дальнейшем приложение ожидает, когда Битрикс24 обратиться к нему:

Обращение произойдет, если пользователь, допустим, решит отправить SMS из карточки CRM. В этом случае, handler.php получит целую кучу данных в массиве $_REQUEST:

requestArray
(
    [module_id] => crm
    [bindings] => Array
        (
            [0] => Array
                (
                    [OWNER_TYPE_ID] => 1
                    [OWNER_ID] => 5783
                )

        )

    [properties] => Array
        (
            [phone_number] => +9172012345
            [message_text] => тест
        )

    [type] => SMS
    [code] => fastsms
    [message_id] => e35864edce3eaad987d32f8955c1177b
    [message_to] => +9172012345
    [message_body] => тест
    [ts] => 1513177809
    [auth] => Array
        (
            [access_token] => x4o81wfl4g57qur2u8sjrlcha76zn0tj
            [expires_in] => 3600
            [scope] => messageservice
            [domain] => restapi.bitrix24.ru
            [server_endpoint] => https://oauth.bitrix.info/rest/
            [status] => F
            [client_endpoint] => https://restapi.bitrix24.ru/rest/
            [member_id] => da45a03b265edd8787f8a258d793cc5d
            [user_id] => 1
            [application_token] => 127acc1c34feccc4da8fbf5020856f12
        )

)

Нас интересует:

• адресат message_to,
• текст сообщения message_body,
• внутренний идентификатор сообщения message_id, который потребуется для того, чтобы в дальнейшем отдельно сообщать в Битрикс24 о статусе доставки,
• параметры авторизации в массиве auth для работы с REST Битрикс24.

Обработчик, получив данные о сообщении, должен:

1. обратиться к API SMS провайдера, чтобы отправить сообщение,
2. запомнить id-сообщения и привязку к конкретному Битрикс24 где-то у себя в некой очереди.

Можно и не запоминать, но тогда приложение не сможет во всей полноте реализовать хорошие пользовательские сценарии. Так как статус доставки SMS-сообщения становится известным только через некоторое время (иногда это могут быть часы), мы не сможем прямо из handler.php тут же сообщить в Битрикс24 о результате доставки. Приложению придется делать это отдельно, и для этого в архиве примера есть файл statuses.php. Подразумевается, что какой-то менеджер заданий обращается к этому файлу с некой периодичностью и этот скрипт «смотрит» на очередь отправленных SMS и по каждому из них пытается узнать статус доставки, обращаясь к API SMS-провайдера:

О результатах он сообщает в Битрикс24, и удаляет из очереди обработанные сообщения.

  Отладка

Для тестирования приложения, необходимо открыть Тестировать в версии приложения или Протестировать в приложении :

После нажатия "Установить" откроется указанный Битрикс24 на странице установки приложения, установите приложение .

Нажмите “Save”, приложение будет считаться установленным (о техническом завершении - ниже), и Битрикс24 автоматически откроет уже основной интерфейс приложения index.php. В архиве примера этот интерфейс не сильно отличается от интерфейса установки и должен «подхватывать» сохраненные параметры авторизации SMS-провайдера. Но, поскольку это просто «заготовка» для приложения, а не работающая интеграция с конкретным провайдером, то мы увидим просто форму для ввода ключа.

  Волшебный код

Начнем с install.php. Когда Битрикс24 показывает во фрейме скрипт приложения (это касается как скрипта установки, так и основного скрипта приложения), то он передает в массив $_REQUEST все необходимые для OAuth 2.0 параметры авторизации. Следовательно, мы их можем схватить и сохранить на стороне приложения для дальнейшего использования. Именно это и происходит в коде при формировании hidden-полей:

<form id="sms-settings">
    <input type="hidden" name="save" value="Y">
    <input type="hidden" name="access_token" value="<?=$_REQUEST['AUTH_ID'];?>">
    <input type="hidden" name="refresh_token" value="<?=$_REQUEST['REFRESH_ID'];?>">
    <input type="hidden" name="domain" value="<?=$_REQUEST['DOMAIN'];?>">
    <input type="hidden" name="member_id" value="<?=$_REQUEST['member_id'];?>">
    <div class="form-group">
        <label for="sms_token">API-key FastSMS</label>
        <input type="text" class="form-control" name="sms_token" id="sms_token" placeholder="FastSMS API token">
    </div>
    <button type="submit" class="btn btn-primary btn-lg btn-save">Save</button>
</form>

Далее, мы делаем обработчик onsubmit, который позволит перехватить нажатие на кнопку "Save".

$('#sms-settings').submit(function(e){

    e.preventDefault();
    // 1. сохраняем данные авторизации на стороне приложения, чтобы в
    // дальнейшем использовать их для отправки смс


    // 2. прописываем обработчик для провайдера
    var params = {
        CODE: 'fastsms',
        TYPE: 'SMS',
        HANDLER: 'https://mydomain.ru/sms/handler.php',
        NAME: 'Provider FastSms',
        DESCRIPTION: 'Description sms provider'
    };

    BX24.callMethod(
        'messageservice.sender.add',
        params,
        function(result)
        {
            if(result.error())
            {
                alert("Error: " + result.error());
            }
            else
            {
                // Обработчик для провайдера прописан успешно

                // 3. заканчиваем процедуру установки на стороне Битрикс24
                BX24.installFinish();
            }
        }
    );
});

В этом обработчике можно прописать свой механизм сохранения нужных параметров. А далее зарегистрируйте тот самый обработчик, обращаясь для этого к методу messageservice.sender.add. Если регистрация прошла успешно, мы вызываем метод installFinish, который сообщает Битрикс24 об успешном завершении установки.

В index.php все то же самое, та же форма настроек, та же обработка события onsubmit, в которой вам придется писать свой код сохранения настроек и параметров авторизации. Но тут уже нет никакого installFinish, потому что приложение уже установлено:

$('#sms-settings').submit(function(e){

    e.preventDefault();
    // сохраняем данные авторизации на стороне приложения, чтобы в
    // дальнейшем использовать их для отправки смс


});

Код в handler.php. В примере просто сохраняется то, что нам передает Битрикс24 в лог:

CRest::setLog($_REQUEST, 'handler');
print_r($_REQUEST);

Но вы можете здесь обращаться к API провайдера SMS, инициируя отправку SMS теми средствами, которые вам предоставит оператор. Пример содержимого массива $_REQUEST есть выше.

Самое сложое находится в файле statuses.php. Подразумевается, что этот файл будет вызываться с некой периодичностью и он должен уметь обращаться к некой очереди, которую вы должны сделать самостоятельно. И получая из этой очереди информацию об отправленных SMS-сообщениях, он должен дергать API SMS-провайдера, получать от него статус доставки и передавать его обратно в Битрикс24. Для этого придется в очереди запоминать как ID-сообщения, который присылает Битрикс24, так и соответствующий ему ID-сообщения на стороне SMS-оператора. Посмотрим на код:

require_once(__DIR__ . '/crest.php');

/**
 * message_id полученный в handler.php
 */
$messageId = '520108d3dabbe6e98586549f467cab8d';

/**
 * sms status: delivered, undelivered, failed
 */
$status = 'delivered';

$result = CRest::call(
	'messageservice.message.status.update',
	[
		'CODE' => 'fastsms',
		'message_id' => $messageId,
		'status' => $status,
	]
);


echo "<pre>"; print_r($result); echo "</pre>";

if (isset($result['error'])) {
   // что-то пошло не так, анализируем ошибку и реагируем на нее
}

Представим, что на каждом шаге цикла обработки очереди мы получили из очереди $messageId , потом вытащили оттуда же название домена Битрикс24 и токены, которые передадим в getSettingData/setSettingData переопределив методы для работы с несколькими Битрикс24. Домен и access_token нам нужны, чтобы обратиться к REST Битрикс24. Это простой HTTP-запрос, в котором указывается домен Битрикс, название нужного метода (в нашем случае это метод messageservice.message.status.update для обновления статуса доставки), параметры метода и токен авторизации access_token.

Для автоматического продления токенов необходимо заполнить константы: C_REST_CLIENT_ID (1) и C_REST_CLIENT_SECRET (2). Значения для этих констант Такая пара ключей действует на всех Битрикс24, на которых потом будет устанавливаться ваше приложение. вам нужно взять из карточки приложения:

Используйте функцию CRest::call(). Она получает название нужного метода REST, параметры для этого метода и токены авторизации из методов getSettingData/setSettingData.

Используйте стандартную заготовку в виде архива примера, адаптируйте к реальному оператору SMS и публикуйте решения в каталоге Битрикс24.Маркет.