Інтеграція 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 з посиланням на оплату через ERIP (підстановка #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, масова розсилка на тестовий сегмент