Работа с СМС

Bitrix Framework использует СМС, чтобы уведомлять пользователей. Отправляет СМС модуль Служба сообщений. Он соединяет систему с разными СМС-провайдерами.

Как работает отправка СМС

  1. Код приложения создает СМС-событие с данными для подстановки.

  2. Система находит активный СМС-шаблон по имени события, сайту и языку.

  3. Данные подставляются в шаблон вместо специальных меток вида #CODE#.

  4. Готовое сообщение передается выбранному СМС-провайдеру.

  5. Провайдер доставляет СМС до абонента.

Метки в шаблонах — это специальные пометки в тексте, которые система заменяет реальными данными. Например, метка #USER_NAME# заменится на имя пользователя, а #ORDER_ID# — на номер заказа.

События и шаблоны сообщений

Чтобы отправить СМС, нужно создать тип события и связать с ним шаблон. Тип события определяет, когда отправлять сообщение, а шаблон — какой текст использовать. В шаблоне укажите метки, которые система заменит на реальные данные.

Создать тип события

Тип события — это идентификатор, который связывает код с шаблонами СМС.

Чтобы создать новый тип события, откройте страницу Настройки > Почтовые и СМС события > Типы событий и нажмите Добавить тип.

  • Тип события — укажите уникальное имя, например, ORDER_READY.

  • Вид события — выберите СМС-событие.

  • Название — напишите понятное название для каждого языка.

  • Описание — добавьте описание события, например, доступные метки.

Создать шаблон

Шаблон задает текст сообщения для системных уведомлений.

  • Название события — выберите тип события, который свяжет код и шаблон.

  • Активен — отметка, что система может использовать шаблон.

  • Сайты — сайт для которого действует шаблон.

  • Язык — конкретный язык, например, ru или en.

  • Телефон отправителя — номер, с которого система отправит СМС.

  • Телефон получателя — номер получателя сообщения.

  • Шаблон сообщения — текст сообщения с метками, которые заменяются реальными данными.

В доступных полях система показывает системные метки и те, которые вы указали в типе события. Их можно использовать для полей сообщения.

Класс \Bitrix\Main\Sms\Event

Класс \Bitrix\Main\Sms\Event управляет отправкой СМС: ищет подходящий шаблон, подставляет данные и передает сообщение модулю Служба сообщений messageservice.

Конструктор

__construct(string $eventName, array $fields = [])

  • $eventName — имя СМС-события, совпадает с полем EVENT_NAME в шаблоне.

  • $fields — массив данных для подстановки.

Пример:

$event = new \Bitrix\Main\Sms\Event('ORDER_READY', [
            'ORDER_ID' => 42,
            'USER_PHONE' => '89991234567',
        ]);

Методы

Найти шаблон

Метод setSite($siteId) задает сайт для поиска шаблона.

  • $siteId — идентификатор сайта.
$event->setSite('s1');

По умолчанию система использует текущий сайт.

Задать язык для выбора шаблона

Метод setLanguage($languageId) задает язык для выбора шаблона.

  • $languageId — идентификатор языка.
$event->setLanguage('ru'); // может быть 'ru', 'en', 'de' и так далее

По умолчанию система использует текущий язык.

Выбрать шаблон по идентификатору

Метод setTemplate($templateId) выбирает конкретный шаблон по ID.

  • $templateId — числовой идентификатор шаблона.
$event->setTemplate(105);

Если указать шаблон по ID, система не будет искать его по событию и языку.

Отправить СМС

Метод send($directly) отправляет СМС.

  • $directly — по умолчанию имеет значение false, то есть сообщение попадает в очередь. Если установить true , сообщение отправится без очереди.
$result = $event->send(false);

Метод возвращает объект \Bitrix\Main\Result. Получить список ошибок можно кодом:

if (!$result->isSuccess()) {
            foreach ($result->getErrorMessages() as $msg) {
                echo $msg;
            }
        }

Получить список сообщений

Метод createMessageList() получает список сообщений на основе шаблонов.

$result = $event->createMessageList();
        
        if ($result->isSuccess()) {
            $messages = $result->getData();
        }

Метод возвращает объект \Bitrix\Main\Result. Поле data содержит массив объектов \Bitrix\Main\Sms\Message.

Примеры

Отправить СМС через очередь

Сообщение отправится через систему очередей после завершения текущего запроса.

use Bitrix\Main\Sms\Event;
        
        // Создаем событие с данными для подстановки в шаблон
        $event = new Event('USER_CONFIRM_PHONE', [
            'CODE' => '123456',    // Подставится вместо #CODE# в шаблоне
            'USER_ID' => 42,       // Подставится вместо #USER_ID# в шаблоне
        ]);
        
        // Настраиваем и отправляем сообщение
        $result = $event
            ->setSite('s1')        // Указываем сайт для поиска шаблона
            ->setLanguage('ru')    // Указываем язык шаблона
            ->send(false);         // false — отправка через очередь
        
        // Проверяем результат отправки
        if (!$result->isSuccess()) {
            foreach ($result->getErrorMessages() as $msg) {
                echo $msg;
            }
        }

Отправить сообщение без очереди

Сообщение отправится сразу, без помещения в очередь.

// Создаем и отправляем событие в одной строке
        $result = (new Event('PASSWORD_RESTORE', $fields)) // $fields — массив данных для шаблона
            ->setSite('s1')    // Указываем сайт
            ->send(true);      // true — немедленная отправка без очереди

Отправить сообщение по ID шаблона

Пример использует конкретный шаблон по ID. Система не ищет шаблон по имени события.

// Используем конкретный шаблон, минуя поиск по имени события
        $result = (new Event('IGNORED_EVENT', $fields)) // Имя события игнорируется
            ->setSite('s1')
            ->setTemplate(105) // Используем шаблон с ID 105
            ->send();          // Отправляем сообщение

Событие onBeforeSendSms

Перед отправкой сообщения система вызывает событие main:onBeforeSendSms. Обработчик получает объект сообщения. Он может проверить данные или изменить текст. Если обработчик вернет ошибку, система не отправит сообщение.

use Bitrix\Main\EventManager;
        use Bitrix\Main\EventResult;
        
        // Регистрируем обработчик для проверки СМС перед отправкой
        EventManager::getInstance()->addEventHandler(
            'main',
            'onBeforeSendSms',
            function(\Bitrix\Main\Event $event) {
                // Получаем объект сообщения
                $msg = $event->getParameter('message');
                
                // Проверяем формат номера телефона
                if (!preg_match('/^\+?[1-9]\d{7,14}$/', $msg->getTo())) {
                    // Если номер невалидный — отменяем отправку
                    return new EventResult(EventResult::ERROR);
                }
                
                // Если все проверки пройдены, сообщение будет отправлено
            }
        );

Модуль Служба сообщений

Чтобы отправить СМС, система использует внешних провайдеров — специальные сервисы, которые доставляют сообщения до абонентов. Модуль Служба сообщений messageservice управляет подключением к провайдерам и настройками отправки.

Установить модуль

Чтобы установить модуль Служба сообщений, откройте страницу Настройки > Настройки продукта > Модули в административном разделе. В списке найдите модуль и нажмите кнопку Установить.

Настроить модуль

Настроить модуль можно на странице Настройки > Настройки продукта > Настройки модулей > Служба сообщений.

  • Сколько дней хранить сообщения — задает срок хранения истории СМС. Система автоматически удаляет старые сообщения.

  • Сколько сообщений отправлять за один хит — ограничивает количество СМС за один запрос. Это предотвращает перегрузку сервера.

  • Службы отправки SMS — отображает список доступных СМС-провайдеров. Для подключения сервиса кликните по его названию и заполните форму.

  • Дневные лимиты отправки SMS — ограничивает количество СМС в сутки.

Класс SmsManager

Класс \Bitrix\MessageService\Sender\SmsManager предоставляет единый интерфейс для работы с СМС-провайдерами. Он автоматически определяет доступные сервисы отправки и управляет процессом отправки сообщений.

Провайдеры

Каждый сервис отправки СМС — это класс в пространстве имен \Bitrix\MessageService\Sender\Sms\. Класс содержит константы для идентификации провайдера.

\Bitrix\MessageService\Sender\Sms\SmsRu::ID      // идентификатор SMS.RU
        \Bitrix\MessageService\Sender\Sms\EdnaRu::ID     // идентификатор Edna

Полный список провайдеров можно получить методом getSenders(). Система включает только те провайдеры, которые поддерживаются текущей конфигурацией.

Методы

Подключите модуль messageservice, чтобы использовать методы.

CModule::IncludeModule('messageservice');
  • getSenders — получает список всех доступных провайдеров.
$senders = \Bitrix\MessageService\Sender\SmsManager::getSenders();
  • getDefaultSender — получает провайдера по умолчанию для региона.
$defaultSender = \Bitrix\MessageService\Sender\SmsManager::getDefaultSender();
  • getUsableSender — получает первого доступного провайдера.
$usableSender = \Bitrix\MessageService\Sender\SmsManager::getUsableSender();
  • getSenderById — получает информацию о провайдере по идентификатору ID.
$sender = \Bitrix\MessageService\Sender\SmsManager::getSenderById(
            \Bitrix\MessageService\Sender\Sms\SmsRu::ID
        );

Зарегистрировать провайдера

Чтобы добавить провайдера:

  • создайте класс провайдера — наследник \Bitrix\MessageService\Sender\Base,

  • зарегистрируйте класс через событие.

$eventManager = \Bitrix\Main\EventManager::getInstance(); 
        $eventManager->registerEventHandler(
            'messageservice',
            'onGetSmsSenders',
            'messageservice',
            'Bitrix\MessageService\Sender\Sms\Dummy',
            'onGetSmsSenders'
        );

Отправка сообщений

Класс SmsManager предоставляет несколько способов отправки СМС. Вы можете отправлять сообщения напрямую, работать с объектами сообщений для тонкой настройки или создавать сообщения на основе шаблонов.

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

Метод sendMessage() отправляет сообщение через указанного провайдера. Сообщение добавляется в очередь отправки.

\Bitrix\MessageService\Sender\SmsManager::sendMessage([
            'SENDER_ID' => \Bitrix\MessageService\Sender\Sms\Ednaru::ID, // Идентификатор провайдера
            'AUTHOR_ID' => $authorId, // Пользователь — отправитель сообщения
            'MESSAGE_TO' => $phoneNumber, // Номер получателя в международном формате
            'MESSAGE_FROM' => $chanelId, // Канал отправителя
            'MESSAGE_BODY' => 'Здравствуйте, ваш заказ уже в пути.', // Текст сообщения
        ]);

Отправить сообщение с расширенной настройкой

Метод createMessage() дает больше контроля над отправкой СМС. Используйте его, чтобы задать дополнительные параметры или заголовки.

С помощью метода можно:

  • настроить дополнительные параметры через MESSAGE_HEADERS,

  • выбрать момент отправки — через очередь или сразу,

  • проверить данные перед отправкой.

$message = \Bitrix\MessageService\Sender\SmsManager::createMessage([
            'SENDER_ID' => \Bitrix\MessageService\Sender\Sms\Ednaru::ID,
            'MESSAGE_TO' => $phoneNumber,
            'MESSAGE_FROM' => $chanelId,
            'MESSAGE_BODY' => $text,
            'MESSAGE_HEADERS' => [
                'module_id' => 'crm', // Привязка к модулю, например, CRM
                'bindings' => [ // Связи с CRM-объектами
                    [
                        'OWNER_TYPE_ID' => 1, // Тип объекта, например, лид
                        'OWNER_ID' => 57, // Идентификатор объекта
                    ],
                ],
            ],
        ]);
        
        // Отправить через очередь
        $result = $message->send();
        
        // Отправить немедленно
        $result = $message->sendDirectly();

Отправить сообщение без очереди

Метод sendMessageDirectly() отправляет сообщение немедленно, без помещения в очередь. Используйте этот метод для срочных сообщений.

$result = \Bitrix\MessageService\Sender\SmsManager::sendMessageDirectly([
            'SENDER_ID' => \Bitrix\MessageService\Sender\Sms\SmsRu::ID,
            'MESSAGE_TO' => '+79161234567',
            'MESSAGE_BODY' => 'Срочное сообщение',
        ]);

Создать сообщение по шаблону

Метод createMessageListByTemplate() создает список сообщений на основе СМС-шаблонов. Система автоматически находит шаблоны по имени события и подставляет переданные данные.

// Данные для подстановки в шаблон. Могут быть разными для каждого получателя
        $templateData = [
            'CODE' => $confirmationCode,    // Данные для подстановки в плейсхолдер #CODE#
            'USER_ID' => $userId,           // Данные для подстановки в плейсхолдер #USER_ID#
            'SENDER_ID' => \Bitrix\MessageService\Sender\Sms\SmsRu::ID, // Опциональный провайдер
            'DEFAULT_FROM' => 'MyCompany'   // Опциональный отправитель
        ];
        
        // Создаем сообщения на основе шаблона 'USER_CONFIRM_PHONE'
        $messages = \Bitrix\MessageService\Sender\SmsManager::createMessageListByTemplate(
            'USER_CONFIRM_PHONE', // имя события, указанное в шаблоне
            $templateData
        );
        
        // Отправляем все созданные сообщения
        foreach ($messages as $message) {
            $message->send();
        }

Проверить статус сообщения

Метод getMessageStatus() позволяет получить текущий статус отправленного сообщения. Статус помогает отслеживать доставку и обрабатывать ошибки.

// Получаем статус сообщения по его ID
        $status = \Bitrix\MessageService\Sender\SmsManager::getMessageStatus($messageId);
        
        if ($status->isSuccess()) {
            // Сообщение успешно обработано
            $statusCode = $status->getExternalStatus();  // Код статуса от провайдера
            $statusText = $status->getStatusText();      // Текстовое описание статуса
        } else {
            // Произошла ошибка
            $errors = $status->getErrorMessages();       // Массив ошибок
        }

Автоматическая нормализация номеров

Система автоматически приводит номера телефонов к международному формату.

// 1. Вход: 89161234567 → Выход: +79161234567
        // 2. Вход: +7 (916) 123-45-67 → Выход: +79161234567

Обработка ошибок

Методы отправки возвращают объект Bitrix\Main\Result. Используйте этот объект для проверки результата операции. Если отправка не удалась, получите список ошибок.

$result = \Bitrix\MessageService\Sender\SmsManager::sendMessage($messageFields);
        if (!$result->isSuccess()) {
            foreach ($result->getErrorMessages() as $error) {
                // Обработка ошибки
            }
        }

События

Событие OnMessageSuccessfullySent позволяет выполнить код после успешной отправки СМС. Например, можно залогировать отправку или обновить данные в CRM.

use Bitrix\Main\EventManager;
        use Bitrix\Main\Event;
        
        // Логируем отправку СМС
        EventManager::getInstance()->addEventHandler(
            'messageservice',
            'OnMessageSuccessfullySent',
            function(Event $event) {
                $messageId = $event->getParameter('ID');
                
                // Запишем успешную отправку сообщения
                AddMessage2Log("СМС отправлено. ID: {$messageId}", 'messageservice');
            }
        );
Предыдущая
Работа с почтой
Следующая
Пользователи