Integration of the MTS SMS (Belarus) SMS service with 1C-Bitrix

Integration of MTS SMS Service (Belarus) with 1C-Bitrix

MTS Belarus has no ready-made module for 1C-Bitrix. The MTS SMPP gateway (smpp.mts.by) works via the binary SMPP v3.4 protocol, while MTS SMS Pro HTTP API communicates via REST with OAuth 2.0 authorization. The standard messageservice module in Bitrix knows how to send SMS through providers, but out of the box only supports sms.ru, SMS-centre, and Twilio. For MTS Belarus, you need a custom provider.

Architecture of Bitrix SMS subsystem

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

• sendMessage() — send a single message, returns SendMessage with external ID and status.
• getShortName() — provider identifier for storage in the database.
• canUse() — check availability (presence of keys, activity).

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

Connection via MTS SMS Pro HTTP API

MTS SMS Pro provides a REST endpoint https://api.mts.by/sms/v1/messages. Authorization is a Bearer token obtained via https://api.mts.by/oauth/token using client_credentials.

Integration sequence:

1. Obtaining credentials. In the MTS SMS Pro personal account, an application is created and client_id and client_secret are issued. An alphanumeric sender name (sender name) is registered separately — without it, messages are sent from a numeric number.

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

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

Request format to MTS API:

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

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

Settings storage 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'). Don't store secrets in configuration files that go into VCS — use .settings_extra.php or environment variables.

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

Integration with CRM and Sale

After registering the SMS provider, MTS becomes available in several places:

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

Error handling and monitoring

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 checks the status of sent messages every hour via GET /sms/v1/messages/{id}/status and updates records in b_messageservice_message.

Implementation timeline

When connecting, keep in mind that MTS Belarus charges separately for transactional and promotional SMS. Promotional SMS requires subscriber consent (opt-in) — Bitrix should check the UF_SMS_CONSENT flag in the user profile before sending marketing messages.