Integration of the A1 SMS (Belarus) SMS service with Bitrix24

Integration of A1 SMS (Belarus) with Bitrix24

Belarusian companies using Bitrix24 encounter a persistent problem: the CRM lives in Bitrix24, while SMS notifications are sent through the A1 SMS personal account. A manager copies a phone number from a deal card, switches to the A1 SMS interface, pastes the number, types the message, and sends. Delivery status remains in the A1 account—the CRM knows nothing about it. With 50+ messages per day, this becomes an assembly line of manual work. Integration removes the context switching: SMS messages are sent directly from the CRM card, delivery statuses return automatically, and robots automate typical scenarios.

A1 SMS Specifics for the Belarusian Market

A1 (formerly Velcom) is Belarus's largest telecommunications operator. The A1 SMS service operates via HTTP API and SMPP protocol. For Bitrix24 integration, HTTP API is preferred—it's simpler to implement and doesn't require persistent connections.

Key features of the A1 SMS API:

• Authorization — via login and password provided when subscribing to the SMS distribution service. Credentials are transmitted with each request.
• Phone number format — international: +375XXXXXXXXX (12 characters). The A1 API does not accept numbers in the 80XXXXXXXXX format—the handler must normalize Bitrix24 numbers before sending.
• Sender name (Sender ID) — up to 11 Latin characters. Registered via a formal request to A1 with legal documentation. Approval takes 3 to 10 business days. Without a registered name, SMS messages are sent with a numeric number.
• Encoding — Cyrillic is transmitted in UTF-8. One SMS in Cyrillic = 70 characters; in Latin = 160 characters. When exceeded, the message splits into segments (67 / 153 characters respectively).

Registering a Provider Through messageservice

Bitrix24 connects external SMS providers via the messageservice module. Registering A1 SMS:

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

HANDLER — the URL of a handler on your server that receives requests from Bitrix24 and translates them to the A1 SMS API.

Handler logic:

1. Receives POST from Bitrix24 with fields: message_to (phone), message_body (text), message_id (message ID in Bitrix24).
2. Normalizes the phone number: removes hyphens, spaces, converts 80XX → +375XX.
3. Forms a request to the A1 SMS API with authorization data, recipient number, text, and Sender ID.
4. Receives from A1 the message identifier (msg_id) and status code.
5. Saves the mapping message_id (Bitrix24) → msg_id (A1) for delivery tracking.
6. Returns confirmation to Bitrix24.

After registration, the A1 SMS provider appears in the list of available options when sending SMS from a contact or deal card, in CRM robots, and in CRM marketing.

Processing Delivery Statuses

The A1 SMS API supports two mechanisms for obtaining delivery statuses:

• Callback (DLR) — A1 sends an HTTP request to the specified URL when the status changes. Configured when activating the service.
• Polling — the handler itself requests the status by msg_id via the API method.

Main statuses:

Without callback processing, all SMS in the CRM remain stuck in "Sent" status, even if the subscriber is outside coverage for days.

Recommended scheme: callback as the primary channel, polling at 60-second intervals as backup—for cases when the callback doesn't arrive (timeout, network error).

Automation via CRM Robots

Typical scenarios for the Belarusian market:

Sales funnel:

• New lead → SMS "Hello, {NAME}. Your request has been received, a manager will call within 15 minutes"
• Deal at stage "Awaiting payment" → SMS with payment link via ERIP (using #DEAL_UF_ERIP_LINK#)
• Deal closed successfully → SMS with thanks

Service notifications:

• Appointment booking (smart process) → SMS reminder one day before and one hour before
• Missed call → SMS "We noticed your call, we'll call back soon"

In the robot text, CRM fields are available: #CONTACT_NAME#, #DEAL_TITLE#, #DEAL_OPPORTUNITY#, custom fields via #DEAL_UF_XXX#.

Marketing and Transactional SMS

Separation is critical for working with A1:

Marketing SMS via A1 require confirmation of subscriber consent. A1 may request evidence if complaints arise. In Bitrix24, consent is recorded in a custom contact field—the robot checks this before sending.

Normalization of Belarusian Phone Numbers

The contact database in Bitrix24 contains numbers in various formats: +375291234567, 80291234567, 375 29 123-45-67, 29 1234567. The handler brings all numbers to the format +375XXXXXXXXX before sending to the A1 API. For numbers without a country code, +375 is added. Numbers that don't match the Belarusian format (don't start with +375 or 80) are marked as invalid—SMS are not sent to them.

Before mass distribution, we recommend running the database through normalization and cleaning invalid numbers—this reduces costs and lowers the error rate.

Implementation Timeline

What We Configure

• Registration of A1 SMS as a provider via messageservice.sender.add
• Handler for requests from Bitrix24 → A1 SMS API
• Normalization of Belarusian phone numbers (80XX → +375XX)
• Callback handler for delivery statuses (DLR)
• Sender ID — assistance with application preparation for A1
• CRM robots for transactional SMS by funnel stages
• Mass distributions via CRM marketing with consent verification
• SMS templates with CRM field substitution
• Testing: sending from card, robot triggering, callback receipt, mass distribution to test segment