Створення, відправка, та інші функції для роботи з одиночними повідомленнями (не розсилками).
Отримання звіту про статус доставки SMS повідомлення
https://api.mobizon.ua/service/Message/GetSMSStatus
Отримання списку SMS повідомлень
https://api.mobizon.ua/service/Message/List
Відправка одиночного SMS повідомлення
https://api.mobizon.ua/service/Message/SendSmsMessage
https://api.mobizon.ua/service/Message/GetSMSStatus
Даний метод дозволяє отримати дані про поточний статус доставки одного або декількох SMS-повідомлень.
Незалежно від типу вхідного параметра, результат, що повертається, завжди представлений у вигляді масиву.
Якщо передавати неіснуючі ідентифікатори повідомлень або ті, які не належать користувачеві, то результат не буде містити інформації про ці повідомлення.
Параметр | Тип | Опис |
---|---|---|
ids | array string | Ідентифікатор (и) повідомлення (ь). Масив або рядок ідентифікаторів, розділених комами. Максимальна кількість ідентифікаторів в одному запиті – 100. |
Поле | Тип | Опис |
---|---|---|
id | integer | Ідентифікатор повідомлення. |
status | string | Статус повідомлення. Див. таблицю Список можливих статусів повідомлень. |
segNum | integer | Кількість сегментів в даному повідомленні. |
startSendTs | string | Час початку відправки повідомлення. Формат: РРРР-ММ-ДД ГГ-ХХ-СС .Якщо повідомлення ще не відправлено, значення поля буде NULL. |
statusUpdateTs | string | Час останнього оновлення статусу повідомлення. Формат: РРРР-ММ-ДД ГГ-ХХ-СС .Якщо повідомлення ще не відправлено, значення поля буде NULL. |
Код | Опис |
---|---|
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;
}
https://api.mobizon.ua/service/Message/List
Даний метод дозволяє отримати список створених SMS-повідомлень.
Пошук може бути здійснений за ID та за даними з полів кампанії.
Параметр | Тип | Опис |
---|---|---|
criteria | array | Критерії пошуку (див. таблицю Критерії пошуку). |
pagination | array | Параметри посторінкового виведення (див. таблицю Параметри посторінкового виведення). |
sort | array | Параметри сортування (див. таблицю Параметри сортування). |
withNumberInfo | integer | Даний параметр дозволяє отримати від сервера додаткову інформацію про номер одержувача, таку як «країна» і «оператор». Можливі значення: 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] | Сортування за кількістю сегментів. |
Масив даних:
Поле | Тип | Опис |
---|---|---|
items | array | Список знайдених повідомлень (див. таблицю Список повідомлень). |
totalItemCount | integer | Загальна кількість знайдених елементів. |
Кожне з повідомлень містить поля:
Поле | Тип | Опис |
---|---|---|
id | integer | Ідентифікатор повідомлення. |
campaignId | integer | Ідентифікатор кампанії повідомлення. |
segNum | integer | Кількість сегментів. |
segUserBuy | float | Вартість сегмента повідомлення для користувача Вказується в валюті користувача. |
from | string | Підпис відправника. |
to | string | Номер отримувача. |
text | string | Текст повідомлення. |
status | string | Статус повідомлення (див. таблицю Список можливих статусів повідомлень). |
groups | string | Ідентифікатори контактних груп, в які входив номер одержувача на момент створення кампанії. |
uuid | string | Внутрішній ідентифікатор повідомлення. |
countryA2 | string | Код країни одержувача в форматі ISO-3166 alpha2. |
operatorName | string | Назва оператора одержувача. |
startSendTs | date | Дата і час відправки повідомлення. Формат: РРРР-ММ-ДД ГГ:ХХ:СС . |
statusUpdateTs | date | Дата і час останнього оновлення статусу повідомлення. Формат: РРРР-ММ-ДД ГГ:ХХ:СС . |
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;
}
https://api.mobizon.ua/service/Message/SendSmsMessage
Даний метод дозволяє відправити одиночне SMS-повідомлення на вказаний номер мобільного телефону.
Параметр | Тип | Опис |
---|---|---|
recipient | string | Телефонний номер одержувача SMS-повідомлення. Номер повинен бути в міжнародному форматі та містити тільки цифри. Наприклад: 380443399669. Якщо в номері є “+” на початку, то його слід закодувати в URL-сутність %2B або видалити, залишивши тільки цифри. |
text | string | Текст SMS-повідомлення, закодований в URL-сутність. Якщо під час спроби відправити повідомлення за допомогою GET запиту система не повертає відповідь з даними повідомлення, слід в першу чергу звернути увагу на наявність спецсимволів в тілі запиту, такими символами є: ? / \ & + та [пробіл] .Наявність таких символів говорить про те, що текст не було закодовано. |
from | string | Підпис відправника. Для використання власного підпису відправника його необхідно попередньо зареєструвати. Якщо підпис не вказано, буде використано підпис обраний за замовчуванням в вашому акаунті. Якщо у вас немає заведених підписів або відсутня можливість відправки з вказаним підписом, по можливості буде використано один з загальних підписів сервісу. Детальніше про підписи відправника читайте в розділі “Підписи відправника”. |
params | array | Додаткові параметри (див. таблицю Додаткові параметри). |
Параметр | Тип | Опис |
---|---|---|
params[name] | string | Назва кампанії. |
params[deferredToTs] | string | Дата і час відкладеної відправки SMS-повідомлення. Можна встановити початок відправки не раніше ніж через годину і не пізніше ніж через 14 днів. Формат: РРРР-ММ-ДД ГГ:ХХ:СС . |
params[mclass] | integer | Клас повідомлення, що відправляється: 0 – повідомлення відображаються спливаючим вікном і ніде не зберігаються (flashSMS); 1 – повідомлення зберігаються в папку Вхідних повідомлень телефону (встановлено за замовчуванням). |
params[validity] | integer | Максимальний час очікування доставки повідомлення, якщо абонент не прийняв його відразу. Наприклад, якщо у абонента телефон вимкнений або знаходиться за межами мережі. Вказується в хвилинах з моменту відправки: від 60 хвилин (1 година) до 1440 хвилин (24 години). |
У разі успішної відправки повідомлення у відповіді міститься масив з наступними полями:
Поле | Тип | Опис |
---|---|---|
campaignId | integer | Ідентифікатор створеної SMS-кампанії. |
messageId | integer | Ідентифікатор створеного SMS-повідомлення. |
status | integer | Статус відправки SMS-кампанії. 1 – кампанія очікує модерацію; 2 – кампанія відправлена без модерації. |
Код | Опис |
---|---|
0 | SMS-повідомлення успішно відправлено. |
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¶ms%5Bvalidity%5D=1440'
var data = "recipient=380443399669&text=Test+sms+message&from=YourAlpha¶ms%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;
}