Реєстрація

Модуль Campaign

Цей модуль містить функції для створення SMS кампаній, додавання в них одержувачів одним із можливих способів, запуску кампанії у відправку, видалення неактуальних кампаній, перегляду списку кампаній і пошуку по них.

Методи API

Додавання одержувачів в масову 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

Додавання одержувачів в масову SMS кампанію

https://api.mobizon.ua/service/Campaign/AddRecipients

В одному запиті дозволена передача тільки даних про одержувачів одного типу:

  • список номерів/ID контактних карт/ID контактів
  • список ID груп із контактної книги
  • файл зі списком одержувачів.

При спробі передати відразу кілька різних типів одержувачів буде повернута помилка 12. Якщо необхідно додати в одну розсилку одержувачів із кількох джерел, слід зробити це в кілька запитів.

При додаванні номерів одержувачів, контактів або контактних карт максимальне число одержувачів, що завантажуються в одному запиті, не може перевищувати 500 номерів. У разі перевищення ліміту буде повернута помилка 12 і одержувачі не будуть додані.

Для завантаження в одну кампанію будь-якої бажаної кількості контактів слід розбивати список на порції по 500 або менше штук і завантажувати кожну порцію окремим викликом апі - одержувачі будуть додаватися до вже існуючого списку, якщо не вказано параметр replace=1.

Завантаження номерів, контактів і карт виконується в основному потоці вебсервера і повертає результат по кожному обробленому одержувачу у вигляді масиву (див. формат даних, що повертаються, нижче).

Завантаження із контактної групи або з файлу викликає створення фонової задачі (асинхронне завантаження) і повертає її ID для подальшого відстеження статусу. У цьому випадку код відповіді API буде 100.

Номери одержувачів повинні передаватися в міжнародному форматі. Всі сторонні символи будуть видалені з номера автоматично.

Кожен номер перевіряється на можливість відправки на нього повідомлення за кодом країни та оператора, якому він належить.

Всі номери, що не пройшли перевірку, будуть відхилені з відповідним кодом помилки (code), а для кожного доданого номера буде повернуто ID створеного повідомлення (messageId) для можливості подальшого запиту статусу.

Якщо не всі передані одержувачі були додані (виникли помилки), то API може повернути один із двох кодів відповіді:

  • 98 - якщо не всі одержувачі були додані, але хоча б один одержувач пройшов перевірку
  • 99 - якщо жоден одержувач не пройшов перевірку.

На весь час додавання одержувачів кампанія блокується на додавання іншими процесами, тому паралельне додавання в кілька потоків в одну кампанію неможливе.

Параметри запиту

ПараметрТипОпис
idintegerІдентифікатор кампанії, в яку необхідно додати одержувачів
recipientsarray stringДля звичайної розсилки (без використання змінних-плейсхолдерів у тексті) одержувачі можуть бути передані у вигляді:
  • рядка з номерами одержувачів, розділених комами або перенесеннями рядків;
  • одновимірного масиву, де кожен елемент масиву відповідає одному номеру одержувача;
  • двовимірного масиву, де кожен елемент - це масив, що містить елемент із ключем recipient і номером одержувача як значення.
Для шаблонної розсилки одержувачі повинні бути передані у вигляді двовимірного масиву, де кожен елемент - це масив, що містить елемент із ключем recipient і номером одержувача як значення. Також у цьому масиві можуть бути елементи з ключами, відповідними назвам змінних (плейсхолдерів) у тексті SMS (без оточуючих їх фігурних дужок).
При цьому, якщо якісь із плейсхолдерів, що містяться в тексті, не передані в масиві з даними, то обробка відбуватиметься залежно від значення, переданого в параметрі params[placeholdersFlag] (див. нижче опис цього параметра).
recipientContactsarray stringМасив або рядок, розділений комами або перенесеннями рядків контактів із контактної книги. Контакт може бути вказаний як:
  • ідентифікатор картки. У цьому разі для розсилки буде використовуватися значення поля 'номер мобільного телефону', позначеного як поле для відправлення розсилок;
  • {ідентифікатор картки}:{ключ поля картки} (наприклад: 123456:mobile, якщо поле мобільного телефону у вашій книзі має ключ 'mobile'). Для розсилки буде використовуватися значення вказаного поля картки.
Якщо розсилка шаблонна, то дані для заповнення плейсхолдерів у тексті будуть використовуватися з відповідної контактної картки.
recipientGroupsarray stringМасив або рядок, розділений комами або перенесеннями рядків ідентифікаторів груп із контактної книги, за якими буде сформовано кампанію. Якщо один і той самий контакт міститься в кількох групах - він буде доданий до кампанії тільки один раз. Якщо кілька контактів містять однаковий номер телефону - доданий буде тільки перший із них.
recipientsFilefileОб'єкт завантаженого файлу з одержувачами - файл CSV або Excel (тільки XLS) із номерами одержувачів у міжнародному форматі.
Для звичайної розсилки (без використання змінних-плейсхолдерів у тексті) - номери по одному в рядку.
Для шаблонної розсилки - номери по одному в рядку в одному зі стовпців із заголовком recipient, в інших стовпцях можуть бути дані для підстановки в плейсхолдери. Заголовки таких стовпців (у першому рядку таблиці) повинні строго відповідати плейсхолдерам у тексті SMS (без оточуючих фігурних дужок, з урахуванням регістру символів). Для імен плейсхолдерів дозволені тільки латинські букви та цифри, а також символи '_', '-'. У разі наявності стовпців із однаковими заголовками, буде повернута помилка.
При цьому, якщо для якихось із плейсхолдерів, що містяться в тексті, немає відповідних стовпців, то обробка відбуватиметься залежно від значення, переданого в параметрі params[placeholdersFlag] (див. нижче опис цього параметра).
paramsarrayДодаткові налаштування (див. таблицю Додаткові налаштування).
Додаткові налаштування
ПараметрТипОпис
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 : При завантаженні одержувачів зі списку номерів, контактів або контактних карт повертається масив, кожен елемент якого містить дані про завантажених одержувачів:

ПолеТипОпис
recipientstringНомер одержувача, який додається в кампанію
codeintegerКод результату додавання одержувача:
0 - номер успішно доданий у кампанію
1 - у переданих даних відсутній номер телефону або його значення порожнє
2 - у переданих даних не виявлено номер телефону (швидше за все дані некоректно відформатовані)
3 - номер не відповідає міжнародному формату телефонних номерів
4 - номер уже був доданий у кампанію (виключення дублікатів із розсилки)
5 - номер знаходиться в стоп-листі (це може бути як ваш стоп-лист, так і стоп-лист системи)
6 - відправка в країну призначення обмежена налаштуваннями вашого акаунту
7 - неможливо визначити оператора та/або країну призначення
8 - у системі відсутня можливість відправки на цього оператора, зверніться в нашу техпідтримку для уточнення можливості відправки
20 - передані дані не містять усіх необхідних плейсхолдерів (якщо placeholdersFlag встановлено в значення 1)
30 - контактну картку не знайдено в контактній книзі (recipient буде дорівнювати null)
31 - контактна картка не містить мобільного номера (recipient буде дорівнювати null)
32 - контакт не знайдено в контактній книзі (recipient буде дорівнювати null)
51 - з технічних причин на цей момент неможливо створити коротке посилання
99 - системна помилка під час додавання номера одержувача
messageIdintegerІдентифікатор доданого повідомлення, якщо номер було додано, за вказаним ідентифікатором можна отримати статус повідомлення.
numberintegerВихідне, передане користувачем значення номера одержувача (якщо передано номер одержувача)
contactintegerІдентифікатор переданого контакту (якщо передавався 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 – ідентифікатор кампанії, якщо вона успішно створена.

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

КодОпис
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 хвилин.

Параметри запиту

ПараметрТипОпис
idintegerІдентифікатор кампанії.

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

КодОпис
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.

Параметри запиту

ПараметрТипОпис
idintegerІдентифікатор кампанії.

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

Масив даних, що містить наступні поля:

ПолеТипОпис
idstringІдентифікатор кампанії.
moderationStatusstringПоточний статус модерації:
MODERATION – кампанія знаходиться на модерації;
DECLINED – кампанія відхилена модератором;
READY_FOR_SEND – кампанія дозволена модератором;
AUTO_READY_FOR_SEND – кампанія відправлена без модерації.
commonStatusstringПоточний статус кампанії:
MODERATION – кампанія проходить модерацію;
DECLINED – кампанія відхилена модератором (причина відхилення вказана в полі globalComment);
READY_FOR_SEND – кампанія готова до відправки, але відправка ще не почалася;
RUNNING – кампанія в процесі відправки;
SENT – кампанія повністю відправлена, але ще не всі повідомлення отримали звіт про доставку від оператора зв'язку;
DONE – кампанія повністю завершена: всі остаточні звіти про доставку отримані, лічильники містять остаточні значення.
groupsListarrayСписок контактних груп, включених в кампанію.
Для кожної групи містить:
id – номер групи;
name – ім'я групи;
cardsCnt – кількість контактів в групі, доступних для відправки повідомлення.
Якщо групи не використовувалися в кампанії, це поле буде порожнім.
typeintegerТип кампанії:
1 – Одноразове повідомлення (відправка на один номер);
2 – Масова розсилка;
3 – Шаблонна кампанія;
7 – Функціональна (службова) кампанія.
msgTypestringТип повідомлень кампанії.
На даний момент підтримується тільки тип «SMS».
rateLimitintegerОбмеження кількості повідомлень, відправлених за період часу, вказаний в полі ratePeriod.
ratePeriodintegerПеріод часу в секундах, за який буде відправлено кількість SMS, вказане в полі rateLimit.
sendStatusstringСтатус відправки кампанії:
SENT – кампанія відправлена;
DONE – кампанія завершена.
isDeletedintegerПрапор, що означає, що кампанія видалена:
0 – кампанія доступна;
1 – кампанія видалена.
deferredToTsstringДата і час відкладеної відправки кампанії.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
createTsstringДата і час створення кампанії.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
startSendTsstringДата і час фактичного початку відправки кампанії.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
endSendTsstringДата і час закінчення відправки всіх повідомлень кампанії.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
namestringНазва кампанії.
fromstringПідпис відправника, яка була вибрана для відправки кампанії.
textstringПовний текст повідомлення або шаблонний текст з плейсхолдерами.
validityintegerМаксимальний час очікування доставки повідомлення, якщо отримувач не може прийняти його відразу, в хвилинах з моменту відправки.
mclassintegerКлас відправленого повідомлення:
0 – повідомлення відображаються спливаючим вікном і ніде не зберігаються (flashSMS);
1 – повідомлення зберігаються в папку Вхідних повідомлень телефону.
trackShortLinkRecipientsintegerВикористана чи функція відстеження отримувачів:
0 – функція не використана;
1 – функція використана.
groupsstringІдентифікатори контактних груп, використовуваних в кампанії, розділені комами.
globalCommentstringКоментар модератора, в разі, якщо кампанія відхилена.

Примеры

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.

ВАЖЛИВО!

Через технічні особливості підрахунку вартості кампанії, дані про можливу вартість кампанії вказані на момент додавання одержувачів і не змінюються з плином часу.

Зміни можуть відбутися тільки при повторному завантаженні одержувачів або при редагуванні даних кампанії (у разі редагування даних всі одержувачі та розрахунки скидаються – потрібне повторне завантаження).

Параметри запиту

ПараметрТипОпис
idintegerІдентифікатор кампанії.
getFilledTplCampaignTextintegerФормат даних, що повертаються:
0 – текст кампанії з плейсхолдерами;
1 – повертати текст шаблонної кампанії, заповнений реальними даними одержувача (за замовчуванням).

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

ПолеТипОпис
idintegerІдентифікатор кампанії.
moderationStatusstringПоточний статус модерації:
MODERATION – кампанія знаходиться на модерації;
DECLINED – кампанія відхилена модератором;
READY_FOR_SEND – кампанія дозволена модератором;
AUTO_READY_FOR_SEND – кампанія відправлена без модерації.
commonStatusstringПоточний статус кампанії:
MODERATION – кампанія проходить модерацію;
DECLINED – кампанія відхилена модератором (причина відхилення вказана в полі globalComment);
READY_FOR_SEND – кампанія готова до відправки, але відправка ще не почалася;
RUNNING – кампанія в процесі відправки;
SENT – кампанія повністю відправлена, але ще не всі повідомлення отримали звіт про доставку від оператора зв'язку;
DONE – кампанія повністю оброблена, всі остаточні звіти про доставку отримані.
groupsListarrayСписок контактних груп, включених в кампанію.
Для кожної групи містить:
id – номер групи;
name – ім'я групи;
cardsCnt – кількість контактів у групі, доступних для відправки повідомлення.
Якщо групи не використовувалися в кампанії, це поле буде порожнім.
typeintegerТип кампанії:
1 – Одиничне повідомлення (відправка на один номер);
2 – Масова розсилка;
3 – Шаблонна кампанія;
7 – Функціональна (службова) кампанія.
msgTypestringТип повідомлень кампанії.
На даний момент підтримується тільки тип «SMS».
rateLimitintegerОбмеження кількості повідомлень, відправлених за період часу, вказаний у полі ratePeriod.
ratePeriodintegerПеріод, протягом якого за відрізок часу буде відправлено кількість SMS, зазначене в полі rateLimit.
sendStatusstringСтатус відправки кампанії:
SENT – кампанія відправлена;
DONE – кампанія завершена.
isDeletedintegerПрапорець, що означає, що кампанія видалена:
0 – кампанія доступна;
1– кампанія видалена.
deferredToTsstringДата і час відкладеної відправки кампанії.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
createTsstringДата і час створення кампанії.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
startSendTsstringДата і час фактичного початку відправки кампанії.
Якщо відправка не була розпочата, то це поле містить NULL.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
endSendTsstringДата і час завершення відправки всіх повідомлень кампанії.
Якщо відправка повідомлень не була завершена – це поле містить NULL.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
namestringНазва кампанії.
fromstringПідпис відправника, який був обраний для відправки кампанії.
textstringПовний текст повідомлення або шаблонний текст із плейсхолдерами.
validityintegerМаксимальний час очікування доставки повідомлення, якщо одержувач не може прийняти його відразу, в хвилинах з моменту відправки.
mclassintegerКлас відправленого повідомлення:
0 – повідомлення відображаються спливаючим вікном і ніде не зберігаються (flashSMS);
1 – повідомлення зберігаються в папку Вхідних повідомлень телефону.
trackShortLinkRecipientsintegerЧи була використана функція відстеження одержувачів:
0 – функція не використана;
1 – функція використана.
groupsstringІдентифікатори контактних груп, які використовуються в кампанії, розділені комами.
globalCommentstringКоментар модератора, якщо кампанія відхилена.
creationWayintegerСпосіб створення кампанії:
1 – за допомогою Інтернет-браузера;
5функціональна (службова) кампанія.
countersarrayРізні лічильники кампанії, описані в таблиці Поля об'єкта counters.
Поля об'єкта counters
ПолеТипОпис
updateTsdatetimeЧас останнього оновлення лічильників.
Для зниження навантаження на систему оновлення лічильників може відбуватися із затримкою.
Формат: РРРР-ММ-ДД ГГ:ХХ:СС.
totalNewSegNumintegerЗагальна кількість сегментів зі статусом NEW.
totalAcceptdSegNumintegerЗагальна кількість сегментів зі статусом ACCEPTD.
totalDelivrdSegNumintegerЗагальна кількість сегментів зі статусом DELIVRD.
totalRejectdSegNumintegerЗагальна кількість сегментів зі статусом REJECTD.
totalExpiredSegNumintegerЗагальна кількість сегментів зі статусом EXPIRED.
totalUndelivSegNumintegerЗагальна кількість сегментів зі статусом UNDELIV.
totalDeletedSegNumintegerЗагальна кількість сегментів зі статусом DELETED.
totalUnknownSegNumintegerЗагальна кількість сегментів зі статусом UNKNOWN.
totalPdlivrdSegNumintegerЗагальна кількість сегментів зі статусом PDLIVRD.
totalSegNumintegerЗагальна кількість сегментів у кампанії. Оновлюється при додаванні одержувачів.
totalNewMsgNumintegerЗагальна кількість повідомлень зі статусом NEW.
totalAcceptdMsgNumintegerЗагальна кількість повідомлень зі статусом ACCEPTD.
totalDelivrdMsgNumintegerЗагальна кількість повідомлень зі статусом DELIVRD.
totalRejectdMsgNumintegerЗагальна кількість повідомлень зі статусом REJECTD.
totalExpiredMsgNumintegerЗагальна кількість повідомлень зі статусом EXPIRED.
totalUndelivMsgNumintegerЗагальна кількість повідомлень зі статусом UNDELIV.
totalDeletedMsgNumintegerЗагальна кількість повідомлень зі статусом DELETED.
totalUnknownMsgNumintegerЗагальна кількість повідомлень зі статусом UNKNOWN.
totalPdlivrdMsgNumintegerЗагальна кількість повідомлень зі статусом PDLIVRD.
totalMsgNumintegerЗагальна кількість повідомлень (не сегментів). Оновлюється при обробці (перед відправкою) повідомлень/сегментів кампанії.
totalNewMsgCostfloatЗагальна вартість усіх сегментів зі статусом NEW.
totalAcceptdMsgCostfloatЗагальна вартість усіх сегментів зі статусом ACCEPTD.
totalDelivrdMsgCostfloatЗагальна вартість усіх сегментів зі статусом DELIVRD.
totalRejectdMsgCostfloatЗагальна вартість усіх сегментів зі статусом REJECTD.
totalExpiredMsgCostfloatЗагальна вартість усіх сегментів зі статусом EXPIRED.
totalUndelivMsgCostfloatЗагальна вартість усіх сегментів зі статусом UNDELIV.
totalDeletedMsgCostfloatЗагальна вартість усіх сегментів зі статусом DELETED.
totalUnknownMsgCostfloatЗагальна вартість усіх сегментів зі статусом UNKNOWN.
totalPdlivrdMsgCostfloatЗагальна вартість усіх сегментів зі статусом PDLIVRD.
totalCostfloatЗагальна вартість кампанії.
recipientsRejectedintegerКількість відхилених одержувачів (не включених у кампанію). Оновлюється при додаванні одержувачів.

Примеры

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 та іншими полями.

Параметри запиту

ПараметрТипОпис
criteriaarrayКритерії пошуку (див. таблицю Критерії пошуку).
paginationarrayПараметри посторінкового виводу (див. таблицю Параметри посторінкового виводу).
sortarrayПараметри сортування (див. таблицю Параметри сортування).

Критерії пошуку

Нижче перераховані поля кампаній за якими здійснюється пошук. Пошук можна здійснювати як за одним, так і за кількома полями одночасно.

ПараметрТипОпис
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]Сортування за датою і часом закінчення відправки кампанії.

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

Містить масив з двох полів:

ПолеТипОпис
itemsarrayСписок знайдених кампаній.
Опис полів кампанії дивіться в описі методу campaign/getInfo.
totalItemCountintegerЗагальна кількість знайдених елементів.
Статуси кампаній
СтатусОпис
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.

Звертаємо вашу увагу! Залежно від умов, таких як підозра на спам, наявність підозрілого вмісту в тексті повідомлення, обмеження для певного напряму тощо, а також умов співпраці (укладений договір), кампанія може потрапити на модерацію.

Параметри запиту

ПараметрТипОпис
idintegerІдентифікатор кампанії.

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

integer: статус відправки кампанії.

Можливі значення:

1 – кампанія перевіряється модератором;
2 – кампанія відправлена.

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

КодОпис
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;
}