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

Битрикс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.Маркет.