Реєстрація

Модуль Message

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

Методи API

Отримання звіту про статус доставки 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 ідентифікаторів повідомлень.

Примеры

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Дата і час останнього оновлення статусу повідомлення.
Формат: РРРР-ММ-ДД ГГ-ХХ-СС.

Примеры

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[shortenLinks]integerПараметр, що вказує на необхідність застосувати функцію скорочення до всіх посилань у тексті SMS. За замовчуванням: 0 (вимкнено). Встановіть у 1, щоб увімкнути.
params[validity]integerМаксимальний час очікування доставки повідомлення, якщо одержувач не може прийняти його відразу.
Наприклад, якщо у абонента телефон вимкнений або знаходиться поза межами мережі.
Вказується в хвилинах з моменту відправки: від 60 хвилин (1 година) до 1440 хвилин (24 години).

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

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

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

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

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

Примеры

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;
}