Integration of SMS service MTS SMS (Belarus) with Bitrix24

Integration of MTS SMS (Belarus) with Bitrix24

A typical situation in a Belarusian company: the sales department works in Bitrix24, but SMS notifications to clients are sent via the MTS Communicator personal account. A manager manually transfers a phone number from the CRM to the MTS interface, types the text, and hits "Send". Delivery status remains in the MTS account—the CRM doesn't see it. As the business scales, manual work becomes a bottleneck. Integration links Bitrix24 and MTS SMS into a single chain: sending from the CRM card, automatic robots by funnel stages, delivery status returned.

MTS SMS API: Connection Specifics

MTS Belarus provides an SMS gateway through the MTS Communicator platform. API access opens after signing a contract for SMS distribution. Technical details:

• Protocol — HTTP/HTTPS API (REST). MTS also supports SMPP, but for Bitrix24 integration, HTTP API is preferable—easier to deploy a handler, no need for a daemon with persistent connection.
• Authorization — via token (API key), issued in the MTS Communicator account after service activation.
• Phone number format — international: +375XXXXXXXXX. MTS API strictly validates the format—numbers without country code or in 80XX format are rejected with an error.
• Rate limits — the number of requests per second is set at connection. Typical value — 10–30 SMS/sec. For mass distributions via CRM marketing, this limit must be considered.

Registering a Sender Name (Sender ID)

MTS Belarus requires mandatory registration of an alphabetic sender name. Without a registered Sender ID, SMS will not be sent—the API returns an error.

Registration process:

1. Prepare a statement on organizational letterhead with the desired name (up to 11 Latin characters).
2. Copy of the organization's registration certificate.
3. Submission via MTS manager or personal account.
4. Approval — 5 to 14 business days. MTS checks that the name doesn't conflict with registered trademarks of third parties.
5. Activation — the name appears in the list of available options in the account.

Multiple Sender IDs can be registered: one for transactional SMS (e.g., company name), another for marketing distributions. The handler specifies the required Sender ID depending on message type.

Registering a Provider in Bitrix24

Connection via the messageservice module:

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

The handler (HANDLER) acts as a layer between Bitrix24 and the MTS SMS API:

1. Receives POST from Bitrix24: message_to, message_body, message_id.
2. Normalizes the phone number to +375XXXXXXXXX format.
3. Formulates a request to the MTS API: endpoint, API key, recipient number, text, Sender ID.
4. Gets a response: message_id from MTS, status of being added to the queue.
5. Saves the link message_id (Bitrix24) ↔ message_id (MTS).
6. Confirms receipt to Bitrix24.

After registration, MTS SMS is available: in manual sending from contact/deal card, in CRM robots, in business processes, in CRM marketing.

Delivery Statuses: Callback and Polling

MTS Communicator supports DLR (Delivery Report) — status notifications via callback URL.

MTS statuses:

Callback is configured in the MTS Communicator account—the URL of the handler on your server is specified. MTS sends POST with message_id and status on each change.

Additionally, we implement polling via the MTS API status check method—request by message_id every 60 seconds for messages that didn't receive a callback within 5 minutes. This is insurance against callback loss due to network failures.

Automation via CRM Robots

Typical scenarios for the Belarusian market:

Sales funnel:

• New lead → SMS "{NAME}, your request has been received. A manager will contact you within 15 minutes"
• Deal at stage "Invoice issued" → SMS with payment link via ERIP
• Deal closed → SMS with thanks and review link

Service:

• Smart process "Appointment" → reminder one day before visit
• Missed call → automatic SMS "We noticed your call"

The robot text uses CRM fields: #CONTACT_NAME#, #DEAL_TITLE#, #DEAL_OPPORTUNITY#, custom fields #DEAL_UF_XXX#.

Transactional and Marketing SMS

MTS Belarus may request confirmation of subscriber consent for marketing distributions. In Bitrix24, we record consent in a custom contact field (UF_CRM_SMS_CONSENT), and the robot checks the value before sending.

Phone Number Normalization

The handler normalizes all numbers from the Bitrix24 database to +375XXXXXXXXX format:

• 80291234567 → +375291234567
• 375 29 123-45-67 → +375291234567
• 29 1234567 → +375291234567
• Numbers not matching Belarusian format are marked as invalid

Before mass distribution, we recommend running the database through normalization and removing invalid records.

Implementation Timeline

What We Configure

• Registration of MTS SMS as a provider via messageservice.sender.add
• Handler for requests from Bitrix24 → MTS SMS API
• Assistance with Sender ID registration in MTS Belarus
• Normalization of Belarusian phone numbers
• Callback handler for delivery statuses (DLR)
• Polling as a backup mechanism for status tracking
• CRM robots for transactional SMS by funnel stages
• Mass distributions via CRM marketing with consent verification
• SMS templates with CRM field substitution
• Testing: manual sending, robots, callback, mass distribution to test segment