СМС шлюз, підключення SMS через API

Навігація

Ви можете безкоштовно підключитися до нашого смс-шлюзу, активація послуги не потрібна. СМС-шлюз дозволяє автоматизувати розсилку sms повідомлень і вбудувати сервіс в будь-який проект.

JSON API (рекомендований метод)

Спілкування з сервісом здійснюється за допомогою відправки HTTP-запитів, методом POST, на задану адресу використовуючи текстовий формат обміну даними «JSON».

Для автентифікації запиту використовується «OAuth 2». При даному типі автентифікації необхідно використовувати token, який можно отримати в особистому кабінеті у розділі «Профіль». Після чего відповідно увімкнути даний токен у заголовок запиту, наприклад як: 'Authorization: Bearer your_token'.

Увага!

Обмеження частоти запитів к сервісу, повино бути не більше 9 запитів в секунду від одного клієнта.

Відправка повідомлення

Адреса служби:

https://im.smsclub.mobi/sms/send

Відправка повідомлення відбувається за допомогою задання нижчеописаних параметрів.

src_addr – Альфа-им'я, від якого йде відправка;
phone – Масив номерів, можно выдправляти до 100 номерів за запит;
message – Текст повідомлення;
integration_id – Не обов'язкове поле. Заповнювати при використанні реферальної системи;

Приклад відправки повідомлення в «JSON» форматі:

{
    "phone" : ["380989361131"],
    "message" : "test text",
    "src_addr" : "VashZakaz"
}

Після успішної відправки повідомлення система поверне масив «info» в якому ключ це id повідомлення у нашій системі, за яким можно отримати статус, а значенням буде номер телефону на який відправлено повідомлення. У прикладі нижче «106» - id sms, 380989361131 — номер отримувача.

Приклад відповіді у «JSON» форматі:

{
 "success_request": {
    "info": {
        "106": "380989361131"
    }
 }
}

Отримання статусу повідомлення

Адреса служби:

https://im.smsclub.mobi/sms/status

Для отримання статусу повідомлення необхідно передати єдиний параметр:

id_sms – Масив з ID повідомлень по яким необхідно отримати статус, ліміт не більше 100;

Прикоад в «JSON» форматі:

{
    "id_sms": ["106"]
}

Після успішного запиту система поверне масив «info», в якому ключ буде id повідомлення, а значенням його статус.

{
 "success_request": {
    "info": {
        "106": "ENROUTE"
        }
    }
}

Статуси:

200 – Запит успішно оброблений.

Можливі статусі повідомлень:

ENROUTE – повідомлення відправлено;
DELIVRD – повідомлення доставлено;
EXPIRED – закінчився термін життя, повідомлення не доставлено;
UNDELIV – неможливо доставити повідомлення;
REJECTD – повідомлення відхилено системою (чорний список або інші фільтри).

400 – Помилка валідаціх вхідних параметрів.
401 – Помилка автентифікації користувача.
429 – Занадто багато запитів на одиницю часу. За замовчуванням необхідно виконувати не більше ніж 9 запитів за 1 секунду.
500х – Сервіс тимчасово недоступний.

Отримання списку альфа-імен

Адреса служби:

https://im.smsclub.mobi/sms/originator

Для отримання списку доступних альфа-імен, необхідно провести запит на вище вказанний URL без тіла запиту використовуючи лише авторизовану інформацію користувача.

Після успішного запиту система поверне список активних альфа-імен:

Приклад відповіді:

{
 "success_request": {
    "info": [
        "test1",
        "test2"
        ]
    }
}

Отримання балансу користувача

Адреса служби:

https://im.smsclub.mobi/sms/balance

Для отримання балансу,необхідно провести запит на вище вказаний URL без тіла запиту, використовуючи лише авторизовану інформацію користувача.

Після успішного запиту система поверне баланс користувача, масив «info» де:

money - баланс
currency - валюта акаунта

Приклад відповіді:

{
 "success_request": {
    "info": {
        "money": "8111.1700",
        "currency": "UAH"
        }
    }
}

SMPP-шлюз

Даний шлюз відповідає всім параметрам протоколу SMPP v3.4. Для тестування нашого шлюзу необхідно зв'язатися з адміністрацією.

HTTP-шлюз

Спілкування з сервісом здійснюється за допомогою відправки HTTP-запитів на задану адресу сервісу по протоколу HTTP методами GET/POST, перевірка типу контенту та валідність кодування не здійснюється.

Кожний запит може складатися з повідомлень, що відправляються, і (або) запитів для отримання статусів.

Відправка повідомлень

Адреса служби:

https://gate.smsclub.mobi/token/

Відправлення повідомлень здійснюється за допомогою завдання нижчеописаних параметрів. Параметри для обох методів однакові:

username – логін облікового запису користувача;
token – токен облікового запису користувача (можливо знайти в профілі);
from – альфа-ім'я, від якого йде відправка (11 англійських символів, цифри, пробіли);
to – список адресатів, розділені «;», після останнього номера адресата символ «;» не ставиться;
text – повідомлення в кодуванні Windows-1251;
lifetime – установка терміну життя СМС, який вказується в хвилинах.

Важливо! Обмеження:

для друкованих символів (ASCII 0x01-0x7E) максимальна довжина повідомлення: 1071 символ;
для символів, що виходять за рамки даного діапазону максимальна довжина повідомлення: 469.

Отримання відповіді

На отриманий запит сервіс повертає або україномовний текст помилки, або текст такого вигляду:

=IDS START=
000002
000003
=IDS END=

=IDS START=, =IDS END= - між даними константами розміщений список ID повідомлень/частин повідомлень, кожний ID з нового рядка (розділяється тегом <br/>).

Список формується в порядку, відповідно до списку адресатів. Для повідомлення, що складається з декількох частин, список ID формується в порядку відправки частин повідомлення одному адресату, далі - список ID в порядку відправки частин повідомлення другого адресату і т. д.

Запит статусів повідомлень

Метод GET, POST: https://gate.smsclub.mobi/http/state.php

Статуси повідомлень містять інформацію про поточний стан повідомлення, регулярно оновлюються і можуть бути запитані користувачем у будь-який час. Запит статусів здійснюється за допомогою нижчеописаних параметрів. Параметри для обох методів однакові:

username – логін облікового запису користувача;
token – токен облікового запису користувача;
smscid – список ID, розділених «;», після останнього ID символ «;» не ставиться.

На отриманий запит сервіс повертає або україномовний текст помилки, або текст такого вигляду:

=IDS START=
ID_1: STATE
ID_2: STATE
…
ID_N: STATE
=IDS END=

=IDS START=, =IDS END= - між даними константами заключений список запитуваних ID повідомлень/частин повідомлень і відповідний їм статус (після символу «:»); кожен ID з нового рядка (розділяється тегом <br/>).

Коди статусів повідомлень

Дані коди використовуються при поверненні статусів повідомлень:

ENROUTE – повідомлення прийнято;
DELIVRD – повідомлення доставлено;
EXPIRED – закінчився термін зберігання повідомлення;
UNDELIV – повідомлення не може бути доставлено;
REJECTD - відхилено.

Приклад GET-запиту відправки повідомлення:

https://gate.smsclub.mobi/token/?username=user&token=user_token&from=SMS CLUB&to=0675126767&text=Hello from SMS CLUB

Приклад GET-запиту на отримання звіту про доставку:

https://gate.smsclub.mobi/token/state.php?username=user&token=user_token&smscid=000000

Перевірка балансу онлайн

Даний метод дозволяє перевірити поточний баланс і величину кредиту користувача.

Приклад GET-запиту перевірки балансу:

https://gate.smsclub.mobi/token/getbalance.php?username=user&token=user_token

Приклад коду перевірки балансу:

<?php
    $ch = curl_init();
    $login = '380501234567';
    $token = '123456';
    $url = "https://gate.smsclub.mobi/token/getbalance.php?username=$login&token=$token";
    //можно и через POST
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_URL,$url);
    $result = curl_exec($ch);
    echo $result;
?>

XML-шлюз

Спілкування з сервісом здійснюється за допомогою відправки XML запитів в кодуванні UTF-8 на задану адресу сервісу по протоколу HTTP методом POST, у змінній xmlrequest перевірка типу контенту та валідність кодування не здійснюється.

Кожний запит може складатися з повідомлень, що відправляються, і (або) запитів для отримання статусів.

Відправлення повідомлень (поодиноких та масових)

Адреса служби:
https://gate.smsclub.mobi/xml/

Відправлення повідомлень здійснюється за допомогою нижчеописаної XML-структури. Всі дані, що знаходяться в тегах, обрамляються в тег <![CDATA[]]>:

<?xml version='1.0' encoding='utf-8'?>
<request_sendsms>
      <username><![CDATA[username]]></username>
      <password><![CDATA[password]]></password>
      <from><![CDATA[XML]]></from>
      <to><![CDATA[380501111111;380502222222]]></to>
      <text><![CDATA[Пример русского ЮТФ-8 текста]]></text>
</request_sendsms>

username – логін облікового запису користувача;
password – пароль облікового запису користувача;
from – альфа-ім'я, від якого йде відправка (11 англійських символів, цифри, пробіли);
to – список адресатів, розділені «;», після останнього адресата символ «;» не ставиться;
text – тег повідомлення в кодуванні UTF-8;
lifetime – установка терміну життя СМС, який вказується у хвилинах.

Важливо! Обмеження:

для друкованих символів (ASCII 0x01-0x7E) максимальна довжина повідомлення — 1071 символ;
для символів, що виходять за рамки даного діапазону, максимальна довжина повідомлення — 469;
в XML структурі, що відправляється на сервер www.gate.smsclub.mobi, мають бути відсутні пробіли та ентер між тегами!!!

На отриманий запит сервіс повертає XML-структуру такого вигляду:

<?xml version="1.0" encoding="utf-8"?>
<response>
       <status>STATUS</status>
       <text>RESULT_TEXT</text>
       <ids>
       <mess>ID_1</mess>
       <mess>ID_2</mess>
         …
       <mess>ID_N</mess>
       </ids>
</response>

status – OK (Операція завершена успішно) / ERROR (Сталася помилка);
text – текстове повідомлення про результат операції;
У випадку вдалої операції, повідомлення типу: Повідомлень: N (M частин).
У випадку помилки - суть помилки. Приклад: не знайдено відповідність пари логін\пароль.
ids – секція, яка містить список ID повідомлень, присвоєних SMSC;
Список формується в порядку, відповідно до списку адресатів. Для повідомлення, що складається з декількох частин, список ID формується в порядку відправки частин повідомлення одному адресату, далі - список ID в порядку відправки частин повідомлення другому адресату і т. д.
mess – містить ID повідомлення/частини повідомлення.

Відправка персоналізованих повідомлень (поодиноких та масових)

Адреса служби:
https://gate.smsclub.mobi/xml/individual.php

Відправка персоналізованих повідомлень — це відправка СМС з індивідуальним текстом на кожен номер абонента, що здійснюється за допомогою нижчеописаної XML-структури. Всі дані, що знаходяться в тегах, обрамляються в тег <![CDATA[]]>. Кожне окреме СМС - це кортеж з даними в тегах <to> і <text>:

<?xml version='1.0' encoding='utf-8'?>
<request_sendsms>
      <username><![CDATA[username]]></username>
      <password><![CDATA[password]]></password>
      <from><![CDATA[XML]]></from>
      <to><![CDATA[380675126767]]></to>
      <text><![CDATA[Пример русского текста ЮТФ-8]]></text>
      ...
      <to><![CDATA[380997777662]]></to>
      <text><![CDATA[Example of text in UTF-8]]></text>
</request_sendsms>

username – логін облікового запису користувача;
password – пароль облікового запису користувача;
from – альфа-ім'я, від якого йде відправка (11 англійських символів, цифри, пробіли);
to – номер адресата;
text – тег повідомлення в кодуванні UTF-8.

Важливо! Обмеження:

для друкованих символів (ASCII 0x01-0x7E) максимальна довжина повідомлення — 1071 символ;
для символів, що виходять за рамки даного діапазону максимальна довжина повідомлення — 469;
в XML структурі, що відправляється на сервер www.gate.smsclub.mobi, мають бути відсутні пробіли та ентер між тегами!!!

На отриманий запит сервіс повертає XML-структуру такого вигляду:

<?xml version="1.0" encoding="utf-8"?>
<response>
       <status>STATUS</status>
       <text>RESULT_TEXT</text>
       <ids>
       <mess>ID_1</mess>
       <mess>ID_2</mess>
         …
       <mess>ID_N</mess>
       </ids>
</response>

status – OK (Операція завершена успішно) / ERROR (Сталася помилка);
text – текстове повідомлення про результат операції;
У випадку вдалої операції, повідомлення типу: Повідомлень: N (M частин).
У випадку помилки - суть помилки. Приклад: не знайдено відповідність пари логін\пароль.
ids – секція, яка містить список ID повідомлень, присвоєних SMSC;
Список формується в порядку, відповідно до списку адресатів. Для повідомлення, що складається з декількох частин, список ID формується в порядку відправки частин повідомлення одному адресату, далі - список ID в порядку відправки частин повідомлення другому адресату і т. д.
mess – містить ID повідомлення/частини повідомлення.

Запит статусів повідомлень

Адреса служби:
https://gate.smsclub.mobi/xml/state.php

Статуси повідомлень містять інформацію про поточний стан повідомлення, регулярно оновлюються і можуть бути запитані користувачем у будь-який час. Запит статусів здійснюється за допомогою нижчеописаної XML-структури. Всі дані, що знаходяться в тегах, обрамляються в тег :

<?xml version="1.0" encoding="utf-8"?>
<request_getstate>
            <username><![CDATA[user]]></username>
            <password><![CDATA[pass]]></password>
            <smscid><![CDATA[000000;000001;000002;000003]]></smscid>
</request_getstate>

username – логін облікового запису користувача;
password – пароль облікового запису користувача;
smscid – список ID, розділених «;», після останнього ID символ «;» не ставиться.

У відповідь на запит сервіс повертає XML-структуру, що містить статуси для запитаних повідомлень або відповідні коди помилок такого вигляду:

    <?xml version="1.0" encoding="utf-8"?>
        <response>
        <status>OK</status>
        <text></text>
        <entries>
                 <entry>
                         <smscid>ID_1</smscid>
                         <state>STATE</state>
                 </entry>
                 <entry>
                         <smscid>ID_2</smscid>
                         <state>STATE</state>
                 </entry>
                 …
                <entry>
                        <smscid>ID_N</smscid>
                        <state>неверно указан id</state>
                </entry>
         </entries>
</response>

status – OK (Операція завершена успішно) / ERROR (Сталася помилка);
text – текстове повідомлення про результат операції;
У випадку вдалої операції, тег не містить ніякої інформації.
У випадку помилки - суть помилки. Приклад: не знайдено відповідність пари логін\пароль.
entries – секція, яка містить список запитуваних ID повідомлень, присвоєних SMS, і відповідних їм статусів;
У разі виникнення помилки дана секція може бути відсутня.
entry – секція, яка містить ID і статус одного повідомлення;
smscid – запитуваний ID повідомлення;
state – відповідний йому статус.

Коди статусів повідомлень

Дані коди використовуються при поверненні статусів повідомлень:

ENROUTE – повідомлення прийнято;
DELIVRD – повідомлення доставлено;
EXPIRED – закінчився термін зберігання повідомлення;
UNDELIV – повідомлення не може бути доставлено;
REJECTD - відхилено.

Приклад коду відправки XML-запиту

Даний код протестований і гарантує позитивний результат. Використання інших методів - не тестувалося.

PHP-версія:

    <?php
      $xml = "
      <?xml version='1.0' encoding='utf-8'?>
      <request_sendsms>
            <username><![CDATA[username]]></username>
            <password><![CDATA[password]]></password>
            <from><![CDATA[XML]]></from>
            <to><![CDATA[380675126767]]></to>
            <text><![CDATA[Пример русского ЮТФ-8 текста]]></text>
      </request_sendsms>";
      $ch = curl_init();
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_POST, true);
      curl_setopt($ch, CURLOPT_POSTFIELDS, array("xmlrequest" => $xml));
      curl_setopt($ch, CURLOPT_URL, 'https://gate.smsclub.mobi/xml/');
      $result = curl_exec($ch);
      echo $result;
    ?>

Завантажити приклади

Тут Ви можете скачати приклади скриптів для роботи з обраним шлюзом:

Метод	HTTP	XML	JSON
Поодинока
Масова
Індивідуальна
Баланс
Звіти