Даний модуль містить функції для створення 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 або менше штук і завантажувати кожну порцію окремим викликом API - одержувачі будуть додаватися до вже існуючого списку, якщо не вказано параметр replace=1.
Завантаження номерів, контактів і карт виконується в основному потоці веб-сервера та повертає результат по кожному обробленому одержувачу у вигляді масиву (див. формат даних, що повертаються, нижче).
Завантаження з контактної групи або з файлу викликає створення фонового завдання (асинхронне завантаження) і повертає його ID для подальшого відстеження статусу. В цьому випадку код відповіді API буде 100.
Номери одержувачів повинні передаватися в міжнародному форматі. Всі сторонні символи будуть видалені з номера автоматично.
Кожен номер перевіряється на можливість відправки на нього повідомлення за кодом країни та оператором, якому він належить.
Всі номери, що не пройшли перевірку, будуть відхилені з відповідним кодом помилки (code), а для кожного доданого номеру буде повернуто ID створеного повідомлення (messageId) для можливості подальшого запиту статусу.
Якщо не всі передані одержувачі були додані (виникли помилки), то API може повернути один з двох кодів відповіді:
На весь час додавання одержувачів кампанія блокується на додавання іншими процесами, тому паралельне додавання неможливе.
Параметр | Тип | Опис |
---|---|---|
id | integer | Ідентифікатор кампанії, в яку необхідно додати одержувачів |
recipients | array string | Для звичайної розсилки одержувачі можуть бути передані у вигляді:
recipient і номером одержувача в якості значення, так само можуть перебувати (але не обов'язково) елементи з ключами, що відповідають назвам змінних (плейсхолдерів) в тексті SMS (без оточуючих їх фігурних дужок).При цьому, якщо якісь із плейсхолдерів, що містяться в тексті, не передані, то обробка буде відбуватися в залежності від переданого параметра placeholdersFlag (див. нижче опис прапора). Приклади запитів див. нижче. |
recipientContacts | array string | Масив або рядок (розділених комами або символами переноса рядків) контактів із контактної книги. Контакт може бути за значений як:
|
recipientGroups | array string | Масив або рядок ідентифікаторів груп (розділених комами або символами переноса рядків) із контактної книги, за якими буде сформовано кампанію. Якщо один і той же контакт міститься в кількох групах, він буде доданий до кампанії лише один раз. Якщо кілька контактів містять однаковий номер телефону, доданий буде лише перший з них. |
recipientsFile | file | Масив або рядок розділених комами або переносами рядків ідентифікаторів груп з контактної книги, за якими буде сформована кампанія. Об'єкт завантаженого файлу з одержувачами - файл CSV або Excel (тільки XLS) з номерами одержувачів в міжнародному форматі. Для звичайної розсилки - номери по одному в рядок. Для шаблонної розсилки - номери по одному в рядок в одному з стовпців з заголовком recipient , в інших стовпцях можуть бути плейсходери, заголовки стовпців повинні відповідати плейсхолдерам в тексті SMS (без оточуючих фігурних дужок). Для тексту плейсхолдерів дозволені тільки латинські букви і цифри, а також символи '_ ', '- '. При наявності стовпців з однаковими заголовками, буде повернуто помилку. При цьому якщо для будь-яких з плейсхолдерів, що містяться в тексті, немає відповідних стовпців, то обробка буде відбуватися в залежності від переданого значення placeholdersFlag параметра params (див. нижче опис прапору). |
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 | Початкове, передане користувачем значення номера одержувача (якщо переданий номер одержувача) |
contactId | integer | Ідентифікатор переданого контакту (якщо передавався recipientsContactIds ) |
contactCardId | integer | Ідентифікатор переданої контактної карти (якщо передавався recipientsCardIds ) |
При завантаженні файлу з одержувачами або списку контактних груп повертається числовий ідентифікатор фонового завдання додавання одержувачів. Деталі роботи з фоновими завданнями див. тут.
Код | Опис |
---|---|
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[mclass] | integer | Клас повідомлення, яке відправляється: 0 – повідомлення відображаються спливаючим вікном і ніде не зберігаються (flashSMS); 1 – повідомлення зберігаються в папку Вхідних повідомлень телефону (встановлено за замовчуванням). |
data[validity] | integer | Максимальний час очікування доставки повідомлення, якщо абонент не прийняв його відразу. Наприклад, якщо телефон вимкнений або знаходиться за межами покриття мережі. Вказується в хвилинах з моменту відправки: від 60 (1 година) до 1440 (24 години). |
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%8E%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%D0%BA%D0%BB%D0%B0%D0%B4%D0%B0%D1%94+%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%8E%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%D0%BA%D0%BB%D0%B0%D0%B4%D0%B0%D1%94+%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;
}