Цей модуль містить функції для створення SMS кампаній, додавання в них одержувачів одним із можливих способів, запуску кампанії у відправку, видалення неактуальних кампаній, перегляду списку кампаній і пошуку по них.
Додавання одержувачів в масову SMS кампанію
https://api.mobizon.ua/service/Campaign/AddRecipients
Створення нової кампанії
https://api.mobizon.ua/service/Campaign/Create
Видалення кампанії
https://api.mobizon.ua/service/Campaign/Delete
Отримання основних даних кампанії
https://api.mobizon.ua/service/Campaign/Get
Отримання статистичних даних кампанії
https://api.mobizon.ua/service/Campaign/GetInfo
Отримання списку кампаній
https://api.mobizon.ua/service/Campaign/List
Відправка кампанії
https://api.mobizon.ua/service/Campaign/Send
https://api.mobizon.ua/service/Campaign/AddRecipients
В одному запиті дозволена передача тільки даних про одержувачів одного типу:
При спробі передати відразу кілька різних типів одержувачів буде повернута помилка 12. Якщо необхідно додати в одну розсилку одержувачів із кількох джерел, слід зробити це в кілька запитів.
При додаванні номерів одержувачів, контактів або контактних карт максимальне число одержувачів, що завантажуються в одному запиті, не може перевищувати 500 номерів. У разі перевищення ліміту буде повернута помилка 12 і одержувачі не будуть додані.
Для завантаження в одну кампанію будь-якої бажаної кількості контактів слід розбивати список на порції по 500 або менше штук і завантажувати кожну порцію окремим викликом апі - одержувачі будуть додаватися до вже існуючого списку, якщо не вказано параметр replace=1.
Завантаження номерів, контактів і карт виконується в основному потоці вебсервера і повертає результат по кожному обробленому одержувачу у вигляді масиву (див. формат даних, що повертаються, нижче).
Завантаження із контактної групи або з файлу викликає створення фонової задачі (асинхронне завантаження) і повертає її ID для подальшого відстеження статусу. У цьому випадку код відповіді API буде 100.
Номери одержувачів повинні передаватися в міжнародному форматі. Всі сторонні символи будуть видалені з номера автоматично.
Кожен номер перевіряється на можливість відправки на нього повідомлення за кодом країни та оператора, якому він належить.
Всі номери, що не пройшли перевірку, будуть відхилені з відповідним кодом помилки (code), а для кожного доданого номера буде повернуто ID створеного повідомлення (messageId) для можливості подальшого запиту статусу.
Якщо не всі передані одержувачі були додані (виникли помилки), то API може повернути один із двох кодів відповіді:
На весь час додавання одержувачів кампанія блокується на додавання іншими процесами, тому паралельне додавання в кілька потоків в одну кампанію неможливе.
| Параметр | Тип | Опис |
|---|---|---|
id | integer | Ідентифікатор кампанії, в яку необхідно додати одержувачів |
recipients | array string | Для звичайної розсилки (без використання змінних-плейсхолдерів у тексті) одержувачі можуть бути передані у вигляді:
recipient і номером одержувача як значення. Також у цьому масиві можуть бути елементи з ключами, відповідними назвам змінних (плейсхолдерів) у тексті SMS (без оточуючих їх фігурних дужок).При цьому, якщо якісь із плейсхолдерів, що містяться в тексті, не передані в масиві з даними, то обробка відбуватиметься залежно від значення, переданого в параметрі params[placeholdersFlag] (див. нижче опис цього параметра). |
recipientContacts | array string | Масив або рядок, розділений комами або перенесеннями рядків контактів із контактної книги. Контакт може бути вказаний як:
|
recipientGroups | array string | Масив або рядок, розділений комами або перенесеннями рядків ідентифікаторів груп із контактної книги, за якими буде сформовано кампанію. Якщо один і той самий контакт міститься в кількох групах - він буде доданий до кампанії тільки один раз. Якщо кілька контактів містять однаковий номер телефону - доданий буде тільки перший із них. |
recipientsFile | file | Об'єкт завантаженого файлу з одержувачами - файл CSV або Excel (тільки XLS) із номерами одержувачів у міжнародному форматі. Для звичайної розсилки (без використання змінних-плейсхолдерів у тексті) - номери по одному в рядку. Для шаблонної розсилки - номери по одному в рядку в одному зі стовпців із заголовком recipient, в інших стовпцях можуть бути дані для підстановки в плейсхолдери. Заголовки таких стовпців (у першому рядку таблиці) повинні строго відповідати плейсхолдерам у тексті SMS (без оточуючих фігурних дужок, з урахуванням регістру символів). Для імен плейсхолдерів дозволені тільки латинські букви та цифри, а також символи '_', '-'. У разі наявності стовпців із однаковими заголовками, буде повернута помилка.При цьому, якщо для якихось із плейсхолдерів, що містяться в тексті, немає відповідних стовпців, то обробка відбуватиметься залежно від значення, переданого в параметрі params[placeholdersFlag] (див. нижче опис цього параметра). |
params | array | Додаткові налаштування (див. таблицю Додаткові налаштування). |
| Параметр | Тип | Опис |
|---|---|---|
params[replace] | integer | Вказує, чи потрібно видалити всіх уже доданих одержувачів і почати додавання заново: 0 - ні, додати одержувачів до вже доданих раніше (значення за замовчуванням); 1 - так, видалити всіх доданих раніше одержувачів перед додаванням нових; |
params[placeholdersFlag] | integer | Обробка відсутніх змінних (плейсхолдерів) для шаблонної розсилки. Якщо якихось значень змінних для підстановки в текст не знайдено, то можливе одне з таких поведінок: 1 - повідомлення додається в розсилку, але плейсхолдери залишаються в тексті як є, заміна не відбувається (поведінка за замовчуванням); 2 - повідомлення додається, а плейсхолдери видаляються (може бути корисно в разі, якщо ви використовуєте в тексті фігурні дужки і не хочете, щоб вони були видалені під час відправки); 3 - повідомлення відхиляється з помилкою, що повідомляє про відсутні дані для підстановки в текст. |
params[recipientsFileEncoding] | string | Кодування файлу з даними одержувачів. Доступні кодування: KOI8-R, CP866, WINDOWS-1252, WINDOWS-1251, UTF-8, ASCII, ISO-8859-1, UCS-2. За замовчуванням: UTF-8. |
params[recipientsFileSkipHeader] | integer | Вказує, чи потрібно пропустити перший рядок файлу та почати обробку з другого. Корисно, якщо завантаження одержувачів відбувається з файлу, в якому в першому рядку знаходяться назви стовпців. У цьому випадку перший рядок краще пропустити і почати обробку файлу з другого рядка. Можливі значення: 0 - починати з першого рядка (значення за замовчуванням); 1 - пропускати перший рядок файлу і починати обробку з другого (примусово встановлено в разі шаблонної розсилки); У разі шаблонної розсилки значення цього параметра завжди дорівнює 1 і не може бути перевизначено, оскільки в першому рядку повинні міститися назви змінних для підстановки. |
params[recipientsFileDelimiter] | string | Роздільник стовпців у файлі з даними одержувачів, за замовчуванням: , (кома). За потреби ви можете використовувати будь-який інший символ. |
params[recipientsFileEnclosure] | string | Обрамлювач тексту у файлі з даними одержувачів, за замовчуванням: ' (одинарна лапка). Цей символ має обрамляти з двох сторін тексти в стовпцях, що містять символ роздільника, щоб система могла правильно розібрати файл на стовпці. |
array | integer : При завантаженні одержувачів зі списку номерів, контактів або контактних карт повертається масив, кожен елемент якого містить дані про завантажених одержувачів:
| Поле | Тип | Опис |
|---|---|---|
recipient | string | Номер одержувача, який додається в кампанію |
code | integer | Код результату додавання одержувача: 0 - номер успішно доданий у кампанію 1 - у переданих даних відсутній номер телефону або його значення порожнє 2 - у переданих даних не виявлено номер телефону (швидше за все дані некоректно відформатовані) 3 - номер не відповідає міжнародному формату телефонних номерів 4 - номер уже був доданий у кампанію (виключення дублікатів із розсилки) 5 - номер знаходиться в стоп-листі (це може бути як ваш стоп-лист, так і стоп-лист системи) 6 - відправка в країну призначення обмежена налаштуваннями вашого акаунту 7 - неможливо визначити оператора та/або країну призначення 8 - у системі відсутня можливість відправки на цього оператора, зверніться в нашу техпідтримку для уточнення можливості відправки 20 - передані дані не містять усіх необхідних плейсхолдерів (якщо placeholdersFlag встановлено в значення 1)30 - контактну картку не знайдено в контактній книзі ( recipient буде дорівнювати null)31 - контактна картка не містить мобільного номера ( recipient буде дорівнювати null)32 - контакт не знайдено в контактній книзі ( recipient буде дорівнювати null)51 - з технічних причин на цей момент неможливо створити коротке посилання 99 - системна помилка під час додавання номера одержувача |
messageId | integer | Ідентифікатор доданого повідомлення, якщо номер було додано, за вказаним ідентифікатором можна отримати статус повідомлення. |
number | integer | Вихідне, передане користувачем значення номера одержувача (якщо передано номер одержувача) |
contact | integer | Ідентифікатор переданого контакту (якщо передавався recipientContacts) |
При завантаженні файлу з одержувачами або списку контактних груп повертається числовий ідентифікатор фонової задачі додавання одержувачів. Деталі роботи з фоновими задачами див. тут.
| Код | Опис |
|---|---|
| 1 | Якщо якісь параметри містять неправильні значення. |
| 2 | Якщо кампанію з указаним ID не знайдено. |
| 10 | Якщо вказану кампанію заблоковано іншим процесом додавання одержувачів або статус кампанії не дозволяє додавання одержувачів. |
| 12 | Якщо не передано жодного типу одержувачів або передано кілька типів одержувачів в одному запиті. |
| 98 | Якщо з усіх переданих одержувачів хоча б один не був доданий у кампанію. |
| 99 | Якщо жоден одержувач не був доданий у кампанію в результаті виконання запиту. |
| 100 | Якщо було запущено фонову задачу додавання одержувачів. Деталі роботи з фоновими задачами див. тут. |
Для додавання в розсилку списку одержувачів можна передати їх масив ось так:
recipients[]=380971112233&recipients[]=79101112233&recipients[]=77071112233
або ось так:
recipients=380971112233,79101112233,77071112233
Обидві форми запису ідентичні.
Припустимо, що текст SMS наступний: Доброго дня, {name}! Ваш баланс на {date} становить {balance}{currency}.
У такому разі в параметрі recipients повинні бути передані дані виду:
recipients[0][recipient]=380971112233
&recipients[0][name]=%D0%92%D0%B0%D1%81%D0%B8%D0%BB%D0%B8%D0%B9
&recipients[0][date]=26.10.17
&recipients[0][balance]=123.45
&recipients[0][currency]=%D0%B3%D1%80%D0%BD
&recipients[1][recipient]=380971112255
&recipients[1][name]=%D0%9E%D0%BB%D1%8C%D0%B3%D0%B0
&recipients[1][date]=26.10.17
&recipients[1][balance]=3222.99
&recipients[1][currency]=%D1%80%D1%83%D0%B1
&recipients[2][recipient]=4901122211112
&recipients[2][name]=Markus
&recipients[2][date]=26.10.17
&recipients[2][balance]=555.45
&recipients[2][currency]=eur
Всі дані в переданих на сервер полях HTTP запиту повинні бути попередньо закодовані в URL encoded string (у кожній мові програмування для цього є відповідна функція).
https://api.mobizon.ua/service/Campaign/Create
Цей метод дозволяє створити нову SMS-кампанію. Після створення кампанії в неї необхідно додати отримувачів, а потім відправити.
data array – Параметри кампанії
| Параметр | Тип | Опис |
|---|---|---|
data[name] | string | Назва кампанії. Завдяки цьому полю зручніше орієнтуватися в створюваних кампаніях. Наприклад: «Знижки на «Чорну П'ятницю» або «Нагадування про негативний баланс на рахунку». Максимальна довжина назви кампанії – 255 символів. |
data[text] | string | Текст SMS повідомлення для відправки. Для шаблонної розсилки (data[type]=3) цей текст повинен містити змінні, які будуть замінені на значення, унікальні для кожного отримувача. Змінна повинна бути написана символами латиниці, цифрами і символами «_» ,«-», і обрамлена в фігурні дужки, наприклад: {name} або {clientBalance}.Вимоги до тексту SMS. В тексті повідомлення ви можете використовувати короткі посилання і функцію відстеження отримувачів, щоб дізнатися хто з отримувачів перейшов за вашою посиланням. |
data[type] | integer | Тип кампанії: 1 – Одноразове повідомлення (відправка на один номер); 2 – Масова розсилка (встановлено за замовчуванням); 3 – Шаблонна кампанія (текст повідомлення може містити плейсхолдери, які будуть замінені на унікальний для кожного отримувача текст). |
data[from] | string | Підпис відправника. Для використання власного підпису відправника її необхідно попередньо зареєструвати. Якщо підпис не вказана, буде використано підпис, встановлений за замовчуванням або стандартний підпис сервісу. |
data[rateLimit] | integer | Обмеження кількості повідомлень, відправлених за період часу, вказаний в полі ratePeriod.Ця опція дозволяє уповільнити швидкість відправки великої SMS-розсилки з метою розподілу навантаження на ваш Кол-Центр. Обмеження швидкості відправки – не більше 100 повідомлень в секунду в перерахунку на посекундну відправку. Повідомлення відправляються через рівні проміжки часу пакетами по 10 штук, виходячи з вказаного rateLimit за ratePeriod. Наприклад, якщо вказати швидкість 600 і період 60, то кожну секунду буде відправлятися 600/60=10 SMS. |
data[ratePeriod] | integer | Період часу в секундах за який буде відправлятися кількість SMS, вказане в полі rateLimit.Може бути рівним: 60 – 1 хвилина; 3600 – 1 година; 86400 – 1 доба. |
data[deferredToTs] | string | Дата і час відкладеної відправки кампанії. Можна встановити початок відправки не раніше ніж через годину, і не пізніше ніж через 14 днів. Формат: РРРР-ММ-ДД ГГ:ХХ:СС. |
data[validity] | integer | Максимальний час очікування доставки повідомлення, якщо отримувач не може прийняти його відразу. Наприклад, якщо телефон вимкнений або знаходиться за межами дії мережі. Вказується в хвилинах з моменту відправки: від 60 (1 година) до 1440 (24 години). |
data[shortenLinks] | integer | Скорочувати посилання в тексті - 1, за замовчуванням не скорочуються - 0. |
data[trackShortLinkRecipients] | integer | Функція відстеження отримувачів. Доступна до використання тільки якщо в тексті повідомлення (в полі data[text]) є короткі посилання, створені в нашому сервісі.0 – не використовувати функцію (встановлено за замовчуванням); 1 – використовувати функцію. |
integer – ідентифікатор кампанії, якщо вона успішно створена.
| Код | Опис |
|---|---|
| 0 | Кампанія успішно створена. |
| 1 | Якщо які-небудь параметри містять невірні значення. |
curl -X POST \
'https://api.mobizon.ua/service/campaign/create?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'data%5Btype%5D=3&data%5Bfrom%5D=Alpha&data%5Btext%5D=%D0%92%D1%96%D1%82%D0%B0%D1%94%D0%BC%D0%BE%2C+%7Bname%7D%21+%D0%92%D0%B0%D1%88+%D0%B1%D0%B0%D0%BB%D0%B0%D0%BD%D1%81+%D0%BD%D0%B0+%7Bdate%7D+%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%B8%D1%82%D1%8C+%7Bbalance%7D%7Bcurrency%7D.'
var data = "data%5Btype%5D=3&data%5Bfrom%5D=Alpha&data%5Btext%5D=%D0%92%D1%96%D1%82%D0%B0%D1%94%D0%BC%D0%BE%2C+%7Bname%7D%21+%D0%92%D0%B0%D1%88+%D0%B1%D0%B0%D0%BB%D0%B0%D0%BD%D1%81+%D0%BD%D0%B0+%7Bdate%7D+%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%B8%D1%82%D1%8C+%7Bbalance%7D%7Bcurrency%7D.";
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/campaign/create?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(
'campaign',
'create',
array(
//параметри кампанії
'data' => array(
//тип кампанії
'type' => '3',
//підпис відправника
'from' => 'Alpha',
//текст повідомлення
'text' => 'Вітаємо, {name}! Ваш баланс на {date} становить {balance}{currency}.'
)
)
)
) {
// Отримання результату виконання методу
$result = $api->getData();
} else {
// Під час виконання сталася помилка, вивід коду помилки і тексту повідомлення
echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}
https://api.mobizon.ua/service/Campaign/Delete
Цей метод дозволяє видалити кампанію за її ID.
Кампанія може бути видалена, якщо її відправка ще не почалася.
Якщо кампанія відкладена: відкладена кампанія може бути видалена за умови, що до початку відправки залишилося не менше 5 хвилин.
| Параметр | Тип | Опис |
|---|---|---|
id | integer | Ідентифікатор кампанії. |
| Код | Опис |
|---|---|
| 0 | Кампанія успішно видалена. |
| 2 | Якщо кампанія з вказаним ідентифікатором не знайдена. |
| 10 | Якщо кампанія з вказаним ідентифікатором не може бути видалена. |
curl -X POST \
'https://api.mobizon.ua/service/campaign/delete?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'id=123'
var data = "id=123";
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/campaign/delete?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(
'campaign',
'delete',
array(
//ідентифікатор кампанії
'id' => '123'
)
)
) {
// Отримання результату виконання методу
$result = $api->getData();
} else {
// Під час виконання сталася помилка, вивід коду помилки і тексту повідомлення
echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}
https://api.mobizon.ua/service/Campaign/Get
Цей метод дозволяє отримати основні дані створеної кампанії за її ID.
| Параметр | Тип | Опис |
|---|---|---|
id | integer | Ідентифікатор кампанії. |
Масив даних, що містить наступні поля:
| Поле | Тип | Опис |
|---|---|---|
id | string | Ідентифікатор кампанії. |
moderationStatus | string | Поточний статус модерації: MODERATION – кампанія знаходиться на модерації; DECLINED – кампанія відхилена модератором; READY_FOR_SEND – кампанія дозволена модератором; AUTO_READY_FOR_SEND – кампанія відправлена без модерації. |
commonStatus | string | Поточний статус кампанії: MODERATION – кампанія проходить модерацію; DECLINED – кампанія відхилена модератором (причина відхилення вказана в полі globalComment); READY_FOR_SEND – кампанія готова до відправки, але відправка ще не почалася; RUNNING – кампанія в процесі відправки; SENT – кампанія повністю відправлена, але ще не всі повідомлення отримали звіт про доставку від оператора зв'язку; DONE – кампанія повністю завершена: всі остаточні звіти про доставку отримані, лічильники містять остаточні значення. |
groupsList | array | Список контактних груп, включених в кампанію. Для кожної групи містить: id – номер групи; name – ім'я групи; cardsCnt – кількість контактів в групі, доступних для відправки повідомлення. Якщо групи не використовувалися в кампанії, це поле буде порожнім. |
type | integer | Тип кампанії: 1 – Одноразове повідомлення (відправка на один номер); 2 – Масова розсилка; 3 – Шаблонна кампанія; 7 – Функціональна (службова) кампанія. |
msgType | string | Тип повідомлень кампанії. На даний момент підтримується тільки тип «SMS». |
rateLimit | integer | Обмеження кількості повідомлень, відправлених за період часу, вказаний в полі ratePeriod. |
ratePeriod | integer | Період часу в секундах, за який буде відправлено кількість SMS, вказане в полі rateLimit. |
sendStatus | string | Статус відправки кампанії: SENT – кампанія відправлена; DONE – кампанія завершена. |
isDeleted | integer | Прапор, що означає, що кампанія видалена: 0 – кампанія доступна; 1 – кампанія видалена. |
deferredToTs | string | Дата і час відкладеної відправки кампанії. Формат: РРРР-ММ-ДД ГГ:ХХ:СС. |
createTs | string | Дата і час створення кампанії. Формат: РРРР-ММ-ДД ГГ:ХХ:СС. |
startSendTs | string | Дата і час фактичного початку відправки кампанії. Формат: РРРР-ММ-ДД ГГ:ХХ:СС. |
endSendTs | string | Дата і час закінчення відправки всіх повідомлень кампанії. Формат: РРРР-ММ-ДД ГГ:ХХ:СС. |
name | string | Назва кампанії. |
from | string | Підпис відправника, яка була вибрана для відправки кампанії. |
text | string | Повний текст повідомлення або шаблонний текст з плейсхолдерами. |
validity | integer | Максимальний час очікування доставки повідомлення, якщо отримувач не може прийняти його відразу, в хвилинах з моменту відправки. |
mclass | integer | Клас відправленого повідомлення: 0 – повідомлення відображаються спливаючим вікном і ніде не зберігаються (flashSMS); 1 – повідомлення зберігаються в папку Вхідних повідомлень телефону. |
trackShortLinkRecipients | integer | Використана чи функція відстеження отримувачів: 0 – функція не використана; 1 – функція використана. |
groups | string | Ідентифікатори контактних груп, використовуваних в кампанії, розділені комами. |
globalComment | string | Коментар модератора, в разі, якщо кампанія відхилена. |
curl -X POST \
'https://api.mobizon.ua/service/campaign/get?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'id=123'
var data = "id=123";
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/campaign/get?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(
'campaign',
'get',
array(
//ідентифікатор кампанії
'id' => '123'
)
)
) {
// Отримання результату виконання методу
$result = $api->getData();
} else {
// Під час виконання сталася помилка, вивід коду помилки і тексту повідомлення
echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}
https://api.mobizon.ua/service/Campaign/GetInfo
Цей метод дозволяє отримати основні та статистичні дані кампанії за її ID.
Статистика формується за допомогою різних лічильників, які відображаються в полі counters.
ВАЖЛИВО!
Через технічні особливості підрахунку вартості кампанії, дані про можливу вартість кампанії вказані на момент додавання одержувачів і не змінюються з плином часу.
Зміни можуть відбутися тільки при повторному завантаженні одержувачів або при редагуванні даних кампанії (у разі редагування даних всі одержувачі та розрахунки скидаються – потрібне повторне завантаження).
| Параметр | Тип | Опис |
|---|---|---|
id | integer | Ідентифікатор кампанії. |
getFilledTplCampaignText | integer | Формат даних, що повертаються: 0 – текст кампанії з плейсхолдерами; 1 – повертати текст шаблонної кампанії, заповнений реальними даними одержувача (за замовчуванням). |
| Поле | Тип | Опис |
|---|---|---|
id | integer | Ідентифікатор кампанії. |
moderationStatus | string | Поточний статус модерації: MODERATION – кампанія знаходиться на модерації; DECLINED – кампанія відхилена модератором; READY_FOR_SEND – кампанія дозволена модератором; AUTO_READY_FOR_SEND – кампанія відправлена без модерації. |
commonStatus | string | Поточний статус кампанії: MODERATION – кампанія проходить модерацію; DECLINED – кампанія відхилена модератором (причина відхилення вказана в полі globalComment);READY_FOR_SEND – кампанія готова до відправки, але відправка ще не почалася; RUNNING – кампанія в процесі відправки; SENT – кампанія повністю відправлена, але ще не всі повідомлення отримали звіт про доставку від оператора зв'язку; DONE – кампанія повністю оброблена, всі остаточні звіти про доставку отримані. |
groupsList | array | Список контактних груп, включених в кампанію. Для кожної групи містить: id – номер групи; name – ім'я групи; cardsCnt – кількість контактів у групі, доступних для відправки повідомлення. Якщо групи не використовувалися в кампанії, це поле буде порожнім. |
type | integer | Тип кампанії: 1 – Одиничне повідомлення (відправка на один номер); 2 – Масова розсилка; 3 – Шаблонна кампанія; 7 – Функціональна (службова) кампанія. |
msgType | string | Тип повідомлень кампанії. На даний момент підтримується тільки тип «SMS». |
rateLimit | integer | Обмеження кількості повідомлень, відправлених за період часу, вказаний у полі ratePeriod. |
ratePeriod | integer | Період, протягом якого за відрізок часу буде відправлено кількість SMS, зазначене в полі rateLimit. |
sendStatus | string | Статус відправки кампанії: SENT – кампанія відправлена; DONE – кампанія завершена. |
isDeleted | integer | Прапорець, що означає, що кампанія видалена: 0 – кампанія доступна; 1– кампанія видалена. |
deferredToTs | string | Дата і час відкладеної відправки кампанії. Формат: РРРР-ММ-ДД ГГ:ХХ:СС. |
createTs | string | Дата і час створення кампанії. Формат: РРРР-ММ-ДД ГГ:ХХ:СС. |
startSendTs | string | Дата і час фактичного початку відправки кампанії. Якщо відправка не була розпочата, то це поле містить NULL. Формат: РРРР-ММ-ДД ГГ:ХХ:СС. |
endSendTs | string | Дата і час завершення відправки всіх повідомлень кампанії. Якщо відправка повідомлень не була завершена – це поле містить NULL. Формат: РРРР-ММ-ДД ГГ:ХХ:СС. |
name | string | Назва кампанії. |
from | string | Підпис відправника, який був обраний для відправки кампанії. |
text | string | Повний текст повідомлення або шаблонний текст із плейсхолдерами. |
validity | integer | Максимальний час очікування доставки повідомлення, якщо одержувач не може прийняти його відразу, в хвилинах з моменту відправки. |
mclass | integer | Клас відправленого повідомлення: 0 – повідомлення відображаються спливаючим вікном і ніде не зберігаються (flashSMS); 1 – повідомлення зберігаються в папку Вхідних повідомлень телефону. |
trackShortLinkRecipients | integer | Чи була використана функція відстеження одержувачів: 0 – функція не використана; 1 – функція використана. |
groups | string | Ідентифікатори контактних груп, які використовуються в кампанії, розділені комами. |
globalComment | string | Коментар модератора, якщо кампанія відхилена. |
creationWay | integer | Спосіб створення кампанії: 1 – за допомогою Інтернет-браузера; 5 – функціональна (службова) кампанія. |
counters | array | Різні лічильники кампанії, описані в таблиці Поля об'єкта counters. |
counters| Поле | Тип | Опис |
|---|---|---|
updateTs | datetime | Час останнього оновлення лічильників. Для зниження навантаження на систему оновлення лічильників може відбуватися із затримкою. Формат: РРРР-ММ-ДД ГГ:ХХ:СС. |
totalNewSegNum | integer | Загальна кількість сегментів зі статусом NEW. |
totalAcceptdSegNum | integer | Загальна кількість сегментів зі статусом ACCEPTD. |
totalDelivrdSegNum | integer | Загальна кількість сегментів зі статусом DELIVRD. |
totalRejectdSegNum | integer | Загальна кількість сегментів зі статусом REJECTD. |
totalExpiredSegNum | integer | Загальна кількість сегментів зі статусом EXPIRED. |
totalUndelivSegNum | integer | Загальна кількість сегментів зі статусом UNDELIV. |
totalDeletedSegNum | integer | Загальна кількість сегментів зі статусом DELETED. |
totalUnknownSegNum | integer | Загальна кількість сегментів зі статусом UNKNOWN. |
totalPdlivrdSegNum | integer | Загальна кількість сегментів зі статусом PDLIVRD. |
totalSegNum | integer | Загальна кількість сегментів у кампанії. Оновлюється при додаванні одержувачів. |
totalNewMsgNum | integer | Загальна кількість повідомлень зі статусом NEW. |
totalAcceptdMsgNum | integer | Загальна кількість повідомлень зі статусом ACCEPTD. |
totalDelivrdMsgNum | integer | Загальна кількість повідомлень зі статусом DELIVRD. |
totalRejectdMsgNum | integer | Загальна кількість повідомлень зі статусом REJECTD. |
totalExpiredMsgNum | integer | Загальна кількість повідомлень зі статусом EXPIRED. |
totalUndelivMsgNum | integer | Загальна кількість повідомлень зі статусом UNDELIV. |
totalDeletedMsgNum | integer | Загальна кількість повідомлень зі статусом DELETED. |
totalUnknownMsgNum | integer | Загальна кількість повідомлень зі статусом UNKNOWN. |
totalPdlivrdMsgNum | integer | Загальна кількість повідомлень зі статусом PDLIVRD. |
totalMsgNum | integer | Загальна кількість повідомлень (не сегментів). Оновлюється при обробці (перед відправкою) повідомлень/сегментів кампанії. |
totalNewMsgCost | float | Загальна вартість усіх сегментів зі статусом NEW. |
totalAcceptdMsgCost | float | Загальна вартість усіх сегментів зі статусом ACCEPTD. |
totalDelivrdMsgCost | float | Загальна вартість усіх сегментів зі статусом DELIVRD. |
totalRejectdMsgCost | float | Загальна вартість усіх сегментів зі статусом REJECTD. |
totalExpiredMsgCost | float | Загальна вартість усіх сегментів зі статусом EXPIRED. |
totalUndelivMsgCost | float | Загальна вартість усіх сегментів зі статусом UNDELIV. |
totalDeletedMsgCost | float | Загальна вартість усіх сегментів зі статусом DELETED. |
totalUnknownMsgCost | float | Загальна вартість усіх сегментів зі статусом UNKNOWN. |
totalPdlivrdMsgCost | float | Загальна вартість усіх сегментів зі статусом PDLIVRD. |
totalCost | float | Загальна вартість кампанії. |
recipientsRejected | integer | Кількість відхилених одержувачів (не включених у кампанію). Оновлюється при додаванні одержувачів. |
curl -X POST \
'https://api.mobizon.ua/service/campaign/getInfo?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'id=123'
var data = "id=123";
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/campaign/getInfo?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(
'campaign',
'getInfo',
array(
//ідентифікатор кампанії
'id' => '123'
)
)
) {
// Отримання результату виконання методу
$result = $api->getData();
} else {
// Під час виконання сталася помилка, вивід коду помилки і тексту повідомлення
echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}
https://api.mobizon.ua/service/Campaign/List
Цей метод дозволяє отримати список створених кампаній. Пошук може бути здійснений за ID та іншими полями.
| Параметр | Тип | Опис |
|---|---|---|
criteria | array | Критерії пошуку (див. таблицю Критерії пошуку). |
pagination | array | Параметри посторінкового виводу (див. таблицю Параметри посторінкового виводу). |
sort | array | Параметри сортування (див. таблицю Параметри сортування). |
Нижче перераховані поля кампаній за якими здійснюється пошук. Пошук можна здійснювати як за одним, так і за кількома полями одночасно.
| Параметр | Тип | Опис |
|---|---|---|
criteria[id] | integer | Пошук однієї кампанії за її ID. |
criteria[ids] | array | Пошук кількох кампаній за їх ID. Параметр повинен бути переданий у вигляді масиву або рядка ідентифікаторів, розділених комами. Максимальна кількість ідентифікаторів – 100, при перевищенні цього ліміту пошук буде відбуватися за першими 100 ID зі списку. |
criteria[recipient] | string | Пошук за номером телефону отримувача або його частини. Наприклад: 380443399669 – знайде всі кампанії, в яких брав участь цей номер; 38097 – будуть знайдені всі кампанії з номерами, що містять вказану комбінацію цифр. У пошуку може брати участь тільки один номер. |
criteria[from] | string | Пошук за підписом відправника, який був використаний у кампанії. |
criteria[text] | string | Пошук за текстом повідомлення кампанії. Здійснюється за принципом повної відповідності шуканого значення. |
criteria[status] | string | Пошук за статусом кампанії. |
criteria[createTsFrom] | string | Пошук кампаній, створених починаючи з вказаної дати і часу. Формат: РРРР-ММ-ДД ГГ:ХХ:СС. |
criteria[createTsTo] | string | Пошук кампаній, створених до вказаної дати і часу. Формат: РРРР-ММ-ДД ГГ:ХХ:СС. |
criteria[sentTsFrom] | string | Пошук кампаній, відправка яких відбулася починаючи з вказаної дати і часу. Формат: РРРР-ММ-ДД ГГ:ХХ:СС. |
criteria[sentTsTo] | string | Пошук кампаній, відправка яких відбулася до вказаної дати і часу. Формат: РРРР-ММ-ДД ГГ:ХХ:СС. |
criteria[type] | integer | Пошук за типом кампанії: 1 – Одноразове повідомлення (відправка на один номер); 2 – Масова розсилка (встановлено за замовчуванням); 3 – Шаблонна кампанія (текст повідомлення може містити плейсхолдери, які будуть замінені на унікальний для кожного отримувача текст). |
criteria[groups] | string | Пошук за ідентифікаторами контактних груп, використовуваних у кампанії. Параметр повинен бути переданий у вигляді масиву або рядка ідентифікаторів, розділених комами. |
Ці параметри призначені для структурованого (часткового) виводу запитуваної інформації.
| Параметр | Тип | Опис |
|---|---|---|
pagination[pageSize] | integer | Кількість відображуваних елементів на сторінці (25, 50, 100). |
pagination[currentPage] | integer | Поточна сторінка. Нумерація сторінок починається з 0. |
За допомогою цих параметрів можна відсортувати результати пошуку за одним з полів у порядку зростання (ASC) або спадання (DESC).
Наприклад:
Сортування за датою створення кампанії у порядку зростання – sort[createTs]=ASC.
Сортування за ID кампанії у порядку спадання – sort[id]=DESC.
| Параметр | Опис |
|---|---|
sort[id] | Сортування за ID кампанії. |
sort[name] | Сортування за ім'ям кампанії. |
sort[from] | Сортування за підписом відправника. |
sort[counters.totalMsgNum] | Сортування за кількістю телефонних номерів кампанії. |
sort[counters.totalCost] | Сортування за вартістю кампанії. |
sort[createTs] | Сортування за датою і часом створення кампанії. |
sort[startSendTs] | Сортування за датою і часом початку відправки кампанії. |
sort[endSendTs] | Сортування за датою і часом закінчення відправки кампанії. |
Містить масив з двох полів:
| Поле | Тип | Опис |
|---|---|---|
items | array | Список знайдених кампаній. Опис полів кампанії дивіться в описі методу campaign/getInfo. |
totalItemCount | integer | Загальна кількість знайдених елементів. |
| Статус | Опис |
|---|---|
| NEW | Кампанія створена, але користувач ще не відправив її. У цьому статусі дозволено додавання отримувачів. |
| MODERATION | Проходить модерацію на відповідність правилам сервісу. |
| DECLINED | Відхилена модератором, оскільки не відповідає правилам сервісу або вимогам операторів, номери яких присутні в кампанії. |
| READY_FOR_SEND | Кампанія готова до відправки, але відправка ще не почалася. |
| AUTO_READY_FOR_SEND | Немає необхідності у модерації кампанії. Кампанія буде відправлена без модерації. |
| NOT_YET_SENT | Включає всі статуси, коли кампанія ще не була відправлена. Це значення використовується тільки для пошуку. У кампаній його бути не може. |
| RUNNING | Кампанія запущена, йде процес відправки оператору. |
| DEFERRED | Відправка кампанії запланована на певний час. Це значення використовується тільки для пошуку. У кампаній його бути не може. |
| SENT | Кампанія повністю відправлена, але ще не всі повідомлення отримали звіт про доставку від операторів зв'язку. |
| DONE | Кампанія повністю оброблена, всі остаточні звіти про доставку отримані. Після встановлення цього статусу жодні лічильники кампанії не змінюються. |
curl -X POST \
'https://api.mobizon.ua/service/campaign/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%5Btype%5D=ASC'
var data = "criteria%5Bfrom%5D=Alpha&pagination%5BcurrentPage%5D=2&pagination%5BpageSize%5D=50&sort%5Btype%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/campaign/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(
'campaign',
'list',
array(
//критерії пошуку
'criteria' => array(
//підпис відправника
'from' => 'Alpha'
),
//параметри посторінкового виводу
'pagination' => array(
//поточна сторінка
'currentPage' => '2',
//кількість відображуваних елементів на сторінці
'pageSize' => '50'
),
//параметри сортування
'sort' => array(
//сортування за типом кампанії
'type' => 'ASC'
)
)
)
) {
// Отримання результату виконання методу
$result = $api->getData();
} else {
// Під час виконання сталася помилка, вивід коду помилки і тексту повідомлення
echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}
https://api.mobizon.ua/service/Campaign/Send
Цей метод дозволяє відправити створену кампанію за її ID.
Звертаємо вашу увагу! Залежно від умов, таких як підозра на спам, наявність підозрілого вмісту в тексті повідомлення, обмеження для певного напряму тощо, а також умов співпраці (укладений договір), кампанія може потрапити на модерацію.
| Параметр | Тип | Опис |
|---|---|---|
id | integer | Ідентифікатор кампанії. |
integer: статус відправки кампанії.
1 – кампанія перевіряється модератором;
2 – кампанія відправлена.
| Код | Опис |
|---|---|
| 0 | Кампанія успішно відправлена. |
| 2 | Якщо кампанію не знайдено. |
| 10 | Якщо не вдалося змінити статус кампанії. |
curl -X POST \
'https://api.mobizon.ua/service/campaign/send?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'id=123'
var data = "id=123";
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/campaign/send?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(
'campaign',
'send',
array(
//ідентифікатор кампанії
'id' => '123'
)
)
) {
// Отримання результату виконання методу
$result = $api->getData();
} else {
// Під час виконання сталася помилка, вивід коду помилки і тексту повідомлення
echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}