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

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

Standard SMS providers (SMS.ru, SMSC) don't work with Belarusian numbers or work with limitations: no alphanumeric sender ID, high cost, delivery issues. A1 (formerly Velcom) — major Belarus operator — provides SMS gateway for businesses with Belarusian sender and guaranteed delivery across MTS, A1, life:) networks. For Bitrix integration you need to write handler linking A1 SMS API with messageservice module (for B24) or main.mail (for boxed Bitrix).

A1 SMS API

A1 provides HTTP API for SMS sending. Documentation issued with contract. Main endpoints:

• POST /api/sms/send — send one or multiple messages
• GET /api/sms/status/{messageId} — delivery status
• GET /api/sms/balance — account balance

Authorization — Basic Auth or bearer token in header (depends on API version, clarify in contract). Request body format — JSON:

{
  "phone": "375291234567",
  "text": "Your order #1234 confirmed",
  "sender": "MyShop"
}

Sender ID — alphabetic sender name, registered with A1 on contract signing. Without registration SMS come with numeric number.

Integration with boxed Bitrix

In boxed Bitrix SMS is sent via messageservice module (if installed) or directly via event handler. Main scenario — SMS on order events.

Option 1: OnSaleStatusOrder event handler

EventManager::getInstance()->addEventHandler(
    'sale',
    'OnSaleStatusOrder',
    ['A1SmsHandler', 'onStatusChange']
);

class A1SmsHandler
{
    public static function onStatusChange($orderId, $status)
    {
        if ($status !== 'F') return; // F = completed

        $order = \Bitrix\Sale\Order::load($orderId);
        $phone = $order->getPropertyCollection()
            ->getPhone()->getValue();

        self::sendSms($phone, "Order #{$orderId} completed");
    }

    private static function sendSms(string $phone, string $text): void
    {
        $ch = curl_init('https://a1sms.by/api/sms/send');
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_HTTPHEADER => [
                'Content-Type: application/json',
                'Authorization: Bearer ' . A1_SMS_TOKEN,
            ],
            CURLOPT_POSTFIELDS => json_encode([
                'phone' => $phone,
                'text' => $text,
                'sender' => 'MyShop',
            ]),
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 10,
        ]);
        $response = curl_exec($ch);
        curl_close($ch);

        // Log response
    }
}

Option 2: sms.manager module

If project uses sms.manager module (from Marketplace or custom) — write provider adapter implementing send interface. Provider registers in module settings, then A1 SMS available as one send channel.

Integration with Bitrix24

In B24 SMS provider connects via REST API:

1. Register provider: messageservice.sender.add with params CODE=a1sms, TYPE=SMS, HANDLER=https://your-site.by/a1sms-handler.php
2. Handler (a1sms-handler.php) — receives request from B24 (number, text), forwards to A1 SMS API, returns status
3. Callback for statuses — A1 sends DLR (Delivery Report) to specified URL. Handler calls messageservice.sender.update to update status in B24

After registration A1 SMS appears in provider list: in contact card, in CRM robots, in CRM marketing broadcasts.

Encoding and transliteration

SMS in Cyrillic — 70 characters per message (UCS-2). In Latin — 160 characters (GSM 7-bit). For budget savings long notifications better send in Latin or fit text in 70 characters.

A1 API accepts text in UTF-8, conversion to GSM/UCS-2 — on gateway side. But special chars (quotes «», em dash —) may convert incorrectly. Before sending — replace with ASCII equivalents.

Error handling

A1 SMS API returns error codes:

For retry in boxed Bitrix — agent CAgent selecting unsent SMS from SmsQueue HL block and retrying. For B24 — retry at handler level.

What we implement

• Register A1 SMS account and get API access
• Develop handler for SMS sending via A1 API
• Connect to messageservice module (B24) or event handlers (boxed)
• Setup callback for delivery status receiving
• Error handling and retry logic
• Log all sent SMS (HL block or table)

Timeline

Main organizational point — contract with A1 and sender ID registration. Technical part takes a week, but operator coordination — 3 to 10 business days. Start contract in parallel with development.