Реєстрація

Модуль Campaign

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

API methods

Додавання одержувачів в масову 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 або менше штук і завантажувати кожну порцію окремим викликом API - одержувачі будуть додаватися до вже існуючого списку, якщо не вказано параметр replace=1.

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

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

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

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

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

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

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

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

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

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

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

КодОпис
0Кампанія успішно створена.
1Якщо будь-які параметри містять невірні значення.

Examples

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 хвилин.

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

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

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

КодОпис
0Кампанія успішно видалена.
2Якщо кампанію із зазначеним ідентифікатором не знайдено.
10Якщо кампанію із зазначеним ідентифікатором не може бути видалено.

Examples

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Коментар модератора, в разі, якщо кампанія відхилена.

Examples

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Кількість відхилених одержувачів (які не включені до кампанії). Оновлюється при додаванні одержувачів.

Examples

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Кампанія повністю оброблена, всі остаточні звіти про доставку отримані.
Після установки цього статусу ніякі лічильники кампанії не змінюються.

Examples

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Якщо не вдалося змінити статус кампанії.

Examples

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;
}