Работа с СМС

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

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

Код приложения создает СМС-событие с данными для подстановки.
Система находит активный СМС-шаблон по имени события, сайту и языку.
Данные подставляются в шаблон вместо специальных меток вида #CODE#.
Готовое сообщение передается выбранному СМС-провайдеру.
Провайдер доставляет СМС до абонента.

Метки в шаблонах — это специальные пометки в тексте, которые система заменяет реальными данными. Например, метка #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, чтобы использовать методы.

\Bitrix\Main\Loader::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 — и верните его объект из обработчика события onGetSmsSenders. Пример для файла /local/php_interface/init.php регистрирует тестового провайдера. Он записывает данные сообщения в журнал и возвращает фиктивный статус DELIVERED, не отправляя СМС. Для отправки через внешний сервис замените логику метода sendMessage() на вызов API провайдера.

if (\Bitrix\Main\Loader::includeModule('messageservice'))
{
    class LocalSmsSender extends \Bitrix\MessageService\Sender\Base
    {
        public const ID = 'local_sms';

        public function getId()
        {
            return self::ID;
        }

        public function getName()
        {
            return 'Тестовый СМС-провайдер';
        }

        public function getShortName()
        {
            return $this->getName();
        }

        public function canUse()
        {
            return true;
        }

        public function getFromList()
        {
            return [['id' => 'test', 'name' => 'test']];
        }

        public function sendMessage(array $messageFields)
        {
            AddMessage2Log($messageFields);

            $result = new \Bitrix\MessageService\Sender\Result\SendMessage();
            $result->setStatus(\Bitrix\MessageService\MessageStatus::DELIVERED);
            $result->setExternalId(uniqid());

            return $result;
        }
    }

    \Bitrix\Main\EventManager::getInstance()->addEventHandler(
        'messageservice',
        'onGetSmsSenders',
        static function ()
        {
            return [new LocalSmsSender()];
        }
    );
}

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

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

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

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

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

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

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

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

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

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

// Отправить через очередь
$result = $message->send();

Чтобы отправить сообщение без очереди, замените вызов send() на 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->getStatusCode();       // Код статуса от провайдера
    $statusText = $status->getStatusText();      // Текстовое описание статуса
}
else
{
    // Произошла ошибка
    $errors = $status->getErrorMessages();       // Массив ошибок
}

В проверенной версии модуля при несуществующем ID сообщения или провайдере без поддержки получения статусов метод выбрасывает PHP-ошибку из-за обращения к отсутствующему классу Bitrix\Main\Result\MessageStatus. В этих случаях ветка else из примера не выполняется.

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

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

// 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 возникает, когда метод SmsManager::sendMessage() успешно добавил сообщение в очередь. Оно не подтверждает доставку СМС. Например, можно записать в журнал ID сообщения или обновить данные в CRM.

use Bitrix\Main\EventManager;
use Bitrix\Main\Event;

// Логируем добавление СМС в очередь
EventManager::getInstance()->addEventHandler(
    'messageservice',
    'OnMessageSuccessfullySent',
    function (Event $event)
    {
        $messageId = $event->getParameter('ID');

        // Запишем ID сообщения, добавленного в очередь
        AddMessage2Log("СМС добавлено в очередь. ID: {$messageId}", 'messageservice');
    }
);

Была ли статья полезна?

Работа с почтой

Пользователи

Работа с СМС

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

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

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

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

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

КонструкторКонструктор

МетодыМетоды

Найти шаблонНайти шаблон

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

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

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

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

ПримерыПримеры

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

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

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

Событие onBeforeSendSmsСобытие onBeforeSendSms

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

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

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

Класс SmsManagerКласс SmsManager

ПровайдерыПровайдеры

МетодыМетоды

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

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

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

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

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

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

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

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

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

СобытияСобытия

Была ли статья полезна?

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

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

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

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

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

Конструктор

Методы

Найти шаблон

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

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

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

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

Примеры

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

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

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

Событие onBeforeSendSms

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

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

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

Класс SmsManager

Провайдеры

Методы

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

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

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

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

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

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

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

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

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

События