Створення, відправка та інші функції для роботи з одиночними повідомленнями (не розсилками).
Отримання звіту про статус доставки 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[shortenLinks] | integer | Параметр, що вказує на необхідність застосувати функцію скорочення до всіх посилань у тексті SMS. За замовчуванням: 0 (вимкнено). Встановіть у 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;
}