Интеграция с SMS

Как разработать интеграцию Битрикс24 с SMS-провайдером?

Отправка SMS включена во многие сценарии внутри Битрикс24. Можно вручную отправить сообщение из карточки CRM, автоматически из робота CRM и действия бизнес-процесса, или использовать механизм рассылок CRM-маркетинга.

В качестве канала доставки сообщений клиентам необязательно служит SMS. Отправить сообщение можно в любой канал, умеющий идентифицировать получателя по номеру телефона.

Зайдем в кабинет разработчика и создадим новое приложение, как мы это делали в предыдущем уроке.

Нажмем кнопку «Добавить приложение». Выберем, как и ранее, основной регион для будущей публикации решения. В карточке приложения нажмем на кнопку «Создать» и укажем тип «Использовать REST API». Убедимся, что скоуп "Сервис сообщений" добавлен в список разделов.

Скачайте пример, прикрепленный к уроку, и загрузите его на свой сервер так же, как мы это делали на уроках, посвященным локальным интеграциям.

Вставьте в карточке версии пути к выгруженному на сервер приложению, как мы это делали ранее. Скопируйте значения из полей client_id, client_secret и вставьте их в соответствующие константы в файле settings.php.

Доступность из внешней сети

Очень важно, чтобы адрес выгруженного на сервер примера был доступен из внешней сети. Никаких localhost, никаких самоподписанных SSL-сертификатов и так далее. Проверяйте доступность вашего URL какими-то сторонними сервисами, не уповайте, пожалуйста, на то, что именно в вашем браузере этот адрес успешно открывается. Убедитесь, что ваш веб-сервер разрешает показ во фреймах

Посмотрим код примера, и начнем с install.php. Здесь вызывается уже известный нам из предыдущих уроков метод installApp, который сохранит полученные токены авторизации в файл для дальнейшего использования.

И здесь же мы сразу воспользуемся этими токенами для выполнения метода messageservice.sender.add. В нашем примере используются только четыре параметра:

CODE, условный символьный код нашего провайдера, который должен отличать его от остальных, потенциально установленных в Битрикс24
TYPE, тип провайдера, который должен быть установлен в значение SMS, чтобы Битрикс24 понимал, в каких сценариях этот првайдер будет доступен.
HANDLER, Ссылка на обработчик, в который будет приходить POST-запрос от Битрикс24 с данными о сообщении, которое необходимо отправить.
NAME, название провайдера, которое увидят пользователи в интерфейсе Битрикс24.

Вернемся в кабинет разработчика

Текущая страница позволит установить приложение на наш Битрикс24 и протестировать его до публикации в Битрикс24.Маркет.

Укажем адрес своего Битрикс24, на котором мы являемся администратором и нажмем Установить.

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

Битрикс24 автоматически откроет приложение после завершения установки, поскольку у нашего приложения есть пользовательский интерфейс.

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

Проверим, как зарегистрировался наш провайдер.

Перейдем в контакты CRM и откроем любой контакт, у которого указан телефонный номер. Нажмем кнопку SMS/WhatsApp.

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

Теперь вернемся к нашему коду и посмотрим, что Битрикс24 отправил в наш обработчик. Это массив очень простой структуры.

Мы видим здесь, какой именно инструмент Битрикс24 использовался для отправки, видим привязку сообщения к конкретному клиенту CRM и ряд других параметров. Но самые важные значения, которые нам нужны для отправки, это номер телефона получателя, текст сообщения и внутренний идентификатор сообщения в Битрикс24.

Эти данные можно использовать для вызовов API SMS-провайдера, чтобы действительно отправить сообщение из приложения. Собственно, код в handler.php как раз получает эти значения из массива REQUEST. Далее нужно разместить код, который непосредственно взаимодействует с конкретным SMS-сервисом или другим провайдером сообщений.

Обратите внимание на переменную $message_id. Если провайдер, который вы интегрируете с Битрикс24 в рамках приложения, умеет информировать о статусе доставке сообщения, то $message_id поможет нам в дальнейшем вызвать REST-метод messageservice.message.status.update для обновления статуса сообщения в интерфейсе Битрикс24.

Мы можем открыть настройки роботов CRM в сделках и убедиться, что наш провайдер также доступен в инструментах автоматизации Битрикс24. Добавим робота «Отправка SMS» и увидим наш провайдер в списке.

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

REST API Битрикс24

Доступность из внешней сети

Материалы уроку: