Интеграция SMS-сервиса A1 SMS (Беларусь) с Битрикс24

Интеграция SMS-сервиса A1 SMS (Беларусь) с Битрикс24

Белорусские компании на Б24 регулярно сталкиваются с одной и той же проблемой: CRM живёт в Битрикс24, а SMS-рассылки — в личном кабинете A1. Менеджер копирует номер из карточки сделки, переключается в интерфейс A1 SMS, вставляет номер, набирает текст, отправляет. Статус доставки остаётся в кабинете A1 — CRM о нём не знает. При 50+ сообщениях в день это превращается в конвейер ручного труда. Интеграция убирает переключение: SMS отправляются из карточки CRM, статусы возвращаются обратно, роботы автоматизируют типовые сценарии.

Специфика A1 SMS для белорусского рынка

A1 (бывший Velcom) — крупнейший оператор Беларуси. SMS-сервис A1 работает через HTTP API и SMPP-протокол. Для интеграции с Б24 используется HTTP API — он проще в реализации и не требует постоянного соединения.

Ключевые особенности A1 SMS API:

• Авторизация — по логину и паролю, выданным при подключении услуги «SMS-рассылка» в A1. Учётные данные передаются в каждом запросе.
• Формат номеров — международный: +375XXXXXXXXX (12 символов). A1 API не принимает номера в формате 80XXXXXXXXX — обработчик должен нормализовать номера из Б24 перед отправкой.
• Имя отправителя (Sender ID) — буквенное имя до 11 символов. Регистрируется через заявку в A1 с предоставлением юридических документов. Срок согласования — от 3 до 10 рабочих дней. Без зарегистрированного имени SMS уходят с числовым номером.
• Кодировка — кириллица передаётся в UTF-8. Одно SMS кириллицей — 70 символов, латиницей — 160 символов. При превышении сообщение разбивается на сегменты (67 / 153 символа соответственно).

Регистрация провайдера через messageservice

Битрикс24 подключает внешние SMS-провайдеры через модуль messageservice. Регистрация A1 SMS:

messageservice.sender.add({
  CODE: "a1sms_by",
  TYPE: "SMS",
  HANDLER: "https://your-domain.com/handler/a1sms.php"
})

HANDLER — URL обработчика на вашем сервере, который принимает запросы от Б24 и транслирует их в A1 SMS API.

Логика обработчика:

1. Принимает POST от Б24 с полями: message_to (номер), message_body (текст), message_id (ID сообщения в Б24).
2. Нормализует номер: убирает дефисы, пробелы, приводит 80XX → +375XX.
3. Формирует запрос к A1 SMS API с авторизационными данными, номером получателя, текстом и Sender ID.
4. Получает от A1 идентификатор сообщения (msg_id) и код статуса.
5. Сохраняет маппинг message_id (Б24) → msg_id (A1) для отслеживания доставки.
6. Возвращает Б24 подтверждение приёма.

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

Обработка статусов доставки

A1 SMS API поддерживает два механизма получения статусов:

• Callback (DLR) — A1 отправляет HTTP-запрос на указанный URL при изменении статуса. Настраивается при подключении услуги.
• Polling — обработчик сам запрашивает статус по msg_id через метод API.

Основные статусы:

Без обработки callback все SMS в CRM зависают в статусе «Отправлено», даже если абонент вне зоны покрытия уже третий день.

Рекомендуемая схема: callback как основной канал, polling с интервалом 60 секунд как резервный — для случаев, когда callback не дошёл (таймаут, сетевая ошибка).

Автоматизация через роботы CRM

Типовые сценарии для белорусского рынка:

Воронка продаж:

• Новый лид → SMS «Добрый день, {ИМЯ}. Ваша заявка принята, менеджер перезвонит в течение 15 минут»
• Сделка на стадии «Ожидает оплату» → SMS со ссылкой на оплату через ЕРИП (подстановка #DEAL_UF_ERIP_LINK#)
• Сделка закрыта успешно → SMS с благодарностью

Сервисные уведомления:

• Запись на приём (смарт-процесс) → SMS-напоминание за день и за час
• Пропущенный звонок → SMS «Мы заметили ваш звонок, перезвоним в ближайшее время»

В тексте робота доступны поля CRM: #CONTACT_NAME#, #DEAL_TITLE#, #DEAL_OPPORTUNITY#, пользовательские поля через #DEAL_UF_XXX#.

Маркетинговые и транзакционные SMS

Разделение критично для работы с A1:

Маркетинговые SMS через A1 требуют подтверждения наличия согласий абонентов. A1 может запросить доказательства при жалобах. В Б24 согласие фиксируется в пользовательском поле контакта — робот проверяет его перед отправкой.

Нормализация белорусских номеров

База контактов в Б24 содержит номера в разных форматах: +375291234567, 80291234567, 375 29 123-45-67, 29 1234567. Обработчик приводит все к формату +375XXXXXXXXX перед отправкой в A1 API. Для номеров без кода страны добавляется +375. Номера, не соответствующие белорусскому формату (не начинаются с +375 или 80), помечаются как невалидные — SMS на них не отправляются.

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

Сроки внедрения

Что настраиваем

• Регистрация A1 SMS как провайдера через messageservice.sender.add
• Обработчик запросов Б24 → A1 SMS API
• Нормализация белорусских номеров (80XX → +375XX)
• Callback-обработчик для статусов доставки (DLR)
• Sender ID — помощь с подготовкой заявки в A1
• Роботы CRM для транзакционных SMS по стадиям воронки
• Массовые рассылки через CRM-маркетинг с проверкой согласий
• Шаблоны SMS с подстановкой полей CRM
• Тестирование: отправка из карточки, срабатывание робота, получение callback, массовая рассылка на тестовый сегмент