Integrating MTS (Belarus) SMS Service with 1C-Bitrix

A typical task: an online store on 1C-Bitrix must send customers SMS about order status via MTS (Belarus). MTS has no ready-made module, and the built-in messageservice only supports SMS Center and Twilio. We have developed an integration of the MTS SMS service with Bitrix — turnkey, with documentation and support. Our experience: over 50 such integrations, 10 years working with the platform. Proper configuration of the OAuth token and caching reduces API response time by 40% compared to typical solutions. This article will cover the architecture of the Bitrix SMS subsystem, steps to connect the MTS SMS Pro HTTP API, status mapping, and typical errors.

Architecture of Bitrix SMS Subsystem

The messageservice module stores the list of registered providers in the class \Bitrix\MessageService\Sender\SmsManager. Each provider is a class implementing the interface \Bitrix\MessageService\Sender\Base. Key methods:

• sendMessage() — sends a single message, returns a SendMessage object with external ID and status.
• getShortName() — provider identifier for storage in the database.
• canUse() — checks availability (keys present, activity).

Registration of a provider occurs through the event onMessageServiceSenderList of the messageservice module. The handler returns an array of provider classes. After registration, the provider appears in the administrative interface Settings → Message Services.

Connecting via MTS SMS Pro HTTP API

MTS SMS Pro provides a REST endpoint https://api.mts.by/sms/v1/messages. Authorization — Bearer token obtained via https://api.mts.by/oauth/token using client_credentials. HTTP API is faster and more reliable than SMPP as it does not require a persistent TCP connection and works over standard HTTPS.

The integration sequence:

1. Obtain credentials. In the MTS SMS Pro account, create an application; client_id and client_secret are issued. The alphanumeric sender name is registered separately — without it, messages are sent from a numeric number.

2. Implement the provider class. The class extends \Bitrix\MessageService\Sender\Base and implements three things: caching the OAuth token (lifetime — 3600 seconds), forming the JSON request body, handling the response with MTS error codes.

3. Status mapping. MTS returns statuses: DELIVERED, EXPIRED, REJECTED, UNKNOWN. They need to be translated into Bitrix statuses: \Bitrix\MessageService\Message\StatusSemantic::DELIVERED, ERROR, etc.

Request format to MTS API:

POST /sms/v1/messages { "phone": "375291234567", "text": "Your order No.123 has been placed", "sender": "MyShop", "validity": 1440 } 

The validity field — message lifetime in minutes. For transactional SMS (confirmation codes) set 5–10 minutes, for informational — 1440 (a day).

How to Register a Custom SMS Provider in Bitrix?

To create a custom provider, you need to subscribe to the onMessageServiceSenderList event of the messageservice module. In the handler, return an object of your class. Example:

\Bitrix\Main\EventManager::getInstance()->addEventHandler( 'messageservice', 'onMessageServiceSenderList', function() { return [ new \My\Provider\MtsSms() ]; } ); 

After that, the provider will appear in the list of available providers and can be used in the sale, crm, and security modules.

Storage of Settings and Security

Keys client_id and client_secret are stored in the b_option table of the messageservice module. Access via \Bitrix\Main\Config\Option::get('messageservice', 'mts_client_id'). Do not store secrets in configuration files that end up in VCS — use .settings_extra.php or environment variables.

The OAuth token is cached in \Bitrix\Main\Data\Cache with a key tied to client_id. On error 401 (token expired), the provider should automatically request a new token and retry sending — once, without recursion.

Integration with CRM and Sale

After registering the provider, SMS via MTS become available in several points:

• sale module — notifications about order status changes. Templates are set in Store → Settings → Order Statuses → SMS Notifications. Variables #ORDER_ID#, #ORDER_STATUS#, #TRACKING_NUMBER# are substituted automatically.
• CRM Bitrix24 — if using on-premise Bitrix24, the provider appears in SMS campaign settings and business process robots. The robot CRM: Send SMS allows selecting the MTS provider.
• Two-factor authentication — the security module can use SMS for login confirmation. The provider is connected in OTP settings.

What to Do with OAuth Authorization Error?

Upon receiving HTTP 401, call \Bitrix\Main\Data\Cache::clean('mts_token') and request a new token. If the error repeats, check the credentials in the MTS account or the application's validity. We recommend setting up a notification to the administrator via \CAdminNotify::Add().

Error Handling and Monitoring

The MTS API returns HTTP 200 even with partial errors — the status of an individual message must be checked in the response body. Typical error codes:

For monitoring, implement an agent that hourly checks the status of sent messages via GET /sms/v1/messages/{id}/status and updates records in b_messageservice_message. Such a monitoring agent allows timely detection of issues and automatic retry.

What Is Included in the Work

• Audit of current Bitrix and MTS configuration
• Development of a custom provider with caching and retry support
• Configuration of SMS templates for sale and CRM modules
• Integration with 1C (if needed, via CommerceML)
• Load testing and optimization
• Documentation and training
• 1-month warranty support

Typical time savings on development amount to up to 40%, which reduces integration costs. Average support cost decreases by 20% after implementation.

Implementation Timelines

When connecting, consider that MTS Belarus bills transactional and promotional SMS separately. Promotional SMS require subscriber consent (opt-in) — Bitrix must check the UF_SMS_CONSENT flag in the user profile before sending marketing messages. Our integration includes this check by default.

Contact us for a consultation — we will offer the best turnkey solution. Order the integration and receive a ready-made solution with quality guarantee.