Реєстрація

Модуль Message

Створення, відправка, та інші функції для роботи з одиночними повідомленнями (не розсилками).

API methods

Отримання звіту про статус доставки SMS повідомлення
https://api.mobizon.ua/service/Message/GetSMSStatus

Отримання списку SMS повідомлень
https://api.mobizon.ua/service/Message/List

Відправка одиночного SMS повідомлення
https://api.mobizon.ua/service/Message/SendSmsMessage

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

https://api.mobizon.ua/service/Message/GetSMSStatus

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

Незалежно від типу вхідного параметра, результат, що повертається, завжди представлений у вигляді масиву.

Якщо передавати неіснуючі ідентифікатори повідомлень або ті, які не належать користувачеві, то результат не буде містити інформації про ці повідомлення.

Параметри запиту

ПараметрТипОпис
idsarray stringІдентифікатор (и) повідомлення (ь).
Масив або рядок ідентифікаторів, розділених комами.
Максимальна кількість ідентифікаторів в одному запиті – 100.

Відповідь сервера

ПолеТипОпис
idintegerІдентифікатор повідомлення.
statusstringСтатус повідомлення.
Див. таблицю Список можливих статусів повідомлень.
segNumintegerКількість сегментів в даному повідомленні.
startSendTsstringЧас початку відправки повідомлення.
Формат: РРРР-ММ-ДД ГГ-ХХ-СС.
Якщо повідомлення ще не відправлено, значення поля буде NULL.
statusUpdateTsstringЧас останнього оновлення статусу повідомлення.
Формат: РРРР-ММ-ДД ГГ-ХХ-СС.
Якщо повідомлення ще не відправлено, значення поля буде NULL.

Коди відповідей API

КодОпис
0Звіт про статус доставки успішно отримано.
2Якщо не вказано жодного ідентифікатора повідомлень.
12Якщо вказано більше 100 ідентифікаторів повідомлень.

Examples

curl -X POST \
  'https://api.mobizon.ua/service/message/getSMSStatus?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'ids%5B0%5D=123&ids%5B1%5D=556&ids%5B2%5D=988'
var data = "ids%5B0%5D=123&ids%5B1%5D=556&ids%5B2%5D=988";

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});

xhr.open("POST", "https://api.mobizon.ua/service/message/getSMSStatus?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK");
xhr.setRequestHeader("content-type", "application/x-www-form-urlencoded");
xhr.setRequestHeader("cache-control", "no-cache");

xhr.send(data);
<?php
use Mobizon\MobizonApi;

$api = new MobizonApi('KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK', 'api.mobizon.ua');

// Вызов АПИ метода
if ($api->call(
    'message',
    'getSMSStatus',
    array(
        //ідентифікатори повідомлень
        'ids' => array(
            '123',
            '556',
            '988'
        )
    )
)
) {
    // Отримання результату виконання методу
    $result = $api->getData();
} else {
    // Під час виконання сталася помилка, виведення коду помилки і тексту повідомлення
    echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}

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

https://api.mobizon.ua/service/Message/List

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

Пошук може бути здійснений за ID та за даними з полів кампанії.

Параметри запиту

ПараметрТипОпис
criteriaarrayКритерії пошуку (див. таблицю Критерії пошуку).
paginationarrayПараметри посторінкового виведення (див. таблицю Параметри посторінкового виведення).
sortarrayПараметри сортування (див. таблицю Параметри сортування).
withNumberInfointegerДаний параметр дозволяє отримати від сервера додаткову інформацію про номер одержувача, таку як «країна» і «оператор».
Можливі значення:
0 – не отримувати (встановлено за замовчуванням);
1 – отримувати.

Критерії пошуку

Інформація про поля SMS-повідомлення, за якими здійснюється пошук. Для пошуку можна використовувати як одне поле, так і кілька полів одночасно.

ПараметрТипОпис
criteria[campaignIds]array \ stringПошук за ідентифікаторами кампаній.
Параметр повинен бути переданий у вигляді масиву або рядку ідентифікаторів, розділених комами.
Максимальна кількість ідентифікаторів – 100, при перевищенні цього ліміту пошук буде відбуватися за першими 100 ID зі списку.
criteria[from]stringПошук за підписом відправника.
Пошук проходить за підписом відправника, який було створено в кампанії.
criteria[to]stringПошук за номером телефону одержувача.
Дозволено пошук як за цілим номером, так і за його частиною.
Наприклад:
380443399669 – знайде всі кампанії, в яких брав участь цей номер;
38097 – будуть знайдені всі кампанії з номерами, що містять зазначену комбінацію цифр.
У пошуку може брати участь тільки один номер.
criteria[text]stringПошук за текстом повідомлення кампанії.
Здійснюється за принципом повної відповідності шуканого значення.
criteria[status]integerПошук за статусом повідомлення.
criteria[groups]stringПошук за ідентифікаторами контактних груп, які використовуються в кампанії.
Параметр повинен бути переданий у вигляді масиву або рядку ідентифікаторів, розділених комами.
criteria[campaignStatus]stringПошук за статусом кампанії SMS-повідомлення.
criteria[campaignCreateTsFrom]stringПошук за датою та часом створення кампаній, починаючи з зазначеної дати і часу.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
criteria[campaignCreateTsTo]stringПошук за датою та часом створення кампаній до зазначеної дати і часу.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
criteria[campaignSentTsFrom]stringПошук за датою та часом відправлених кампаній, починаючи з зазначеної дати і часу.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
criteria[campaignSentTsTo]stringПошук за датою та часом відправлених кампаній до зазначеної дати і часу.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
criteria[startSendTsFrom]stringПошук за датою та часом відправлених повідомлень, починаючи з зазначеної дати і часу.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
criteria[startSendTsTo]stringПошук за датою та часом відправлених повідомлень до зазначеної дати і часу.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
criteria[statusUpdateTsFrom]stringПошук за датою створення повідомлень, статус яких був змінений, починаючи з зазначених дати та часу.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
criteria[statusUpdateTsTo]stringПошук за датою створення повідомлень, статус яких був змінений до зазначених дати та часу.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.

Параметри посторінкового виведення

Дані параметри створені для структурованого (часткового) виводу запитуваної інформації.

ПараметрТипОпис
pagination[pageSize]integerКількість елементів, які відображаються на сторінці (25, 50, 100).
pagination[currentPage]integerПоточна сторінка
Нумерація сторінок починається з 0.

Параметри сортування

За допомогою даних параметрів можна відсортувати результати пошуку по одному з полів в порядку зростання (ASC) або спадання (DESC).

Наприклад:

Сортування за номером одержувача за зростанням – sort[to]: ASC.

Сортування за статусом повідомлення за спаданням – sort[status]: DESC.

ПараметрОпис
sort[campaignId]Сортування за ідентифікатором кампанії.
sort[from]Сортування за підписом відправника.
sort[to]Сортування за номером одержувача.
sort[text]Сортування за текстом.
sort[status]Сортування за статусом повідомлення.
sort[startSendTs]Сортування за часом відправки.
sort[statusUpdateTs]Сортування за оновленням статусу.
sort[segNum]Сортування за кількістю сегментів.

Відповідь сервера

Масив даних:

ПолеТипОпис
itemsarrayСписок знайдених повідомлень (див. таблицю Список повідомлень).
totalItemCountintegerЗагальна кількість знайдених елементів.
Список повідомлень

Кожне з повідомлень містить поля:

ПолеТипОпис
idintegerІдентифікатор повідомлення.
campaignIdintegerІдентифікатор кампанії повідомлення.
segNumintegerКількість сегментів.
segUserBuyfloatВартість сегмента повідомлення для користувача
Вказується в валюті користувача.
fromstringПідпис відправника.
tostringНомер отримувача.
textstringТекст повідомлення.
statusstringСтатус повідомлення (див. таблицю Список можливих статусів повідомлень).
groupsstringІдентифікатори контактних груп, в які входив номер одержувача на момент створення кампанії.
uuidstringВнутрішній ідентифікатор повідомлення.
countryA2stringКод країни одержувача в форматі ISO-3166 alpha2.
operatorNamestringНазва оператора одержувача.
startSendTsdateДата і час відправки повідомлення.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
statusUpdateTsdateДата і час останнього оновлення статусу повідомлення.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.

Examples

curl -X POST \
  'https://api.mobizon.ua/service/message/list?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'criteria%5Bfrom%5D=Alpha&pagination%5BcurrentPage%5D=2&pagination%5BpageSize%5D=50&sort%5BcampaignId%5D=ASC'
var data = "criteria%5Bfrom%5D=Alpha&pagination%5BcurrentPage%5D=2&pagination%5BpageSize%5D=50&sort%5BcampaignId%5D=ASC";

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});

xhr.open("POST", "https://api.mobizon.ua/service/message/list?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK");
xhr.setRequestHeader("content-type", "application/x-www-form-urlencoded");
xhr.setRequestHeader("cache-control", "no-cache");

xhr.send(data);
<?php
use Mobizon\MobizonApi;

$api = new MobizonApi('KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK', 'api.mobizon.ua');

// Вызов АПИ метода
if ($api->call(
    'message',
    'list',
    array(
        //критерії пошуку
        'criteria' => array(
            //підпис відправника
            'from' => 'Alpha'
        ),
        //параметри посторінкового виведення
        'pagination' => array(
            //поточна сторінка
            'currentPage' => '2',
            //кількість елементів, які відображаються на сторінці
            'pageSize' => '50'
        ),
        //параметри сортування
        'sort' => array(
            //сортування за ідентифікатором кампанії
            'campaignId' => 'ASC'
        )
    )
)
) {
    // Отримання результату виконання методу
    $result = $api->getData();
} else {
    // Під час виконання сталася помилка, виведення коду помилки і тексту повідомлення
    echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}

Відправка одиночного SMS повідомлення

https://api.mobizon.ua/service/Message/SendSmsMessage

Даний метод дозволяє відправити одиночне SMS-повідомлення на вказаний номер мобільного телефону.

Параметри запиту

ПараметрТипОпис
recipientstringТелефонний номер одержувача SMS-повідомлення.
Номер повинен бути в міжнародному форматі та містити тільки цифри.
Наприклад: 380443399669.
Якщо в номері є “+” на початку, то його слід закодувати в URL-сутність %2B або видалити, залишивши тільки цифри.
textstringТекст SMS-повідомлення, закодований в URL-сутність.
Якщо під час спроби відправити повідомлення за допомогою GET запиту система не повертає відповідь з даними повідомлення, слід в першу чергу звернути увагу на наявність спецсимволів в тілі запиту, такими символами є: ? / \ & + та [пробіл].
Наявність таких символів говорить про те, що текст не було закодовано.
fromstringПідпис відправника.
Для використання власного підпису відправника його необхідно попередньо зареєструвати.
Якщо підпис не вказано, буде використано підпис обраний за замовчуванням в вашому акаунті.
Якщо у вас немає заведених підписів або відсутня можливість відправки з вказаним підписом, по можливості буде використано один з загальних підписів сервісу.
Детальніше про підписи відправника читайте в розділі “Підписи відправника”.
paramsarrayДодаткові параметри (див. таблицю Додаткові параметри).

Додаткові параметри

ПараметрТипОпис
params[name]stringНазва кампанії.
params[deferredToTs]stringДата і час відкладеної відправки SMS-повідомлення.
Можна встановити початок відправки не раніше ніж через годину і не пізніше ніж через 14 днів.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
params[mclass]integerКлас повідомлення, що відправляється:
0 – повідомлення відображаються спливаючим вікном і ніде не зберігаються (flashSMS);
1 – повідомлення зберігаються в папку Вхідних повідомлень телефону (встановлено за замовчуванням).
params[validity]integerМаксимальний час очікування доставки повідомлення, якщо абонент не прийняв його відразу.
Наприклад, якщо у абонента телефон вимкнений або знаходиться за межами мережі.
Вказується в хвилинах з моменту відправки: від 60 хвилин (1 година) до 1440 хвилин (24 години).

Відповідь сервера

У разі успішної відправки повідомлення у відповіді міститься масив з наступними полями:

ПолеТипОпис
campaignIdintegerІдентифікатор створеної SMS-кампанії.
messageIdintegerІдентифікатор створеного SMS-повідомлення.
statusintegerСтатус відправки SMS-кампанії.
1 – кампанія очікує модерацію;
2 – кампанія відправлена без модерації.

Коди відповідей API

КодОпис
0SMS-повідомлення успішно відправлено.
1Якщо хоча б один з параметрів вказано невірно.

Examples

curl -X POST \
  'https://api.mobizon.ua/service/message/sendSmsMessage?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'recipient=380443399669&text=Test+sms+message&from=YourAlpha&params%5Bvalidity%5D=1440'
var data = "recipient=380443399669&text=Test+sms+message&from=YourAlpha&params%5Bvalidity%5D=1440";

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});

xhr.open("POST", "https://api.mobizon.ua/service/message/sendSmsMessage?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK");
xhr.setRequestHeader("content-type", "application/x-www-form-urlencoded");
xhr.setRequestHeader("cache-control", "no-cache");

xhr.send(data);
<?php

use 'Mobizon\MobizonApi.php';

$api = new Mobizon\MobizonApi('KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK', 'api.mobizon.ua');

// API call to send a message
if ($api->call('message',
    'sendSMSMessage',
    array(
        // Recipient international phone number
        'recipient' => '380443399669',
        // Message text
        'text' => 'Test sms message',
        // Alphaname is optional, if you don't have registered alphaname, just skip this parameter and your message will be sent with our free common alphaname, if it's available for this direction.
         'from' => 'YourAlpha',
         // Message will be expired after 1440 min (24h)
         'params[validity]' => 1440
    ))
) {
    // Get message ID assigned by our system to request it's delivery report later.
    $messageId = $api->getData('messageId');

    if (!$messageId) {
        // Message is not accepted, see error code and data for details.
    }
    // Message has been accepted by API.
} else {
    // An error occurred while sending message
    echo '[' . $api->getCode() . '] ' . $api->getMessage() . 'See details below:' . PHP_EOL . print_r($api->getData(), true) . PHP_EOL;
}