Регистрация

Модуль Campaign

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

API methods

Добавление получателей в массовую SMS кампанию
https://api.mobizon.kz/service/Campaign/AddRecipients

Создание новой кампании
https://api.mobizon.kz/service/Campaign/Create

Удаление кампании
https://api.mobizon.kz/service/Campaign/Delete

Получение основных данных кампании
https://api.mobizon.kz/service/Campaign/Get

Получение статистических данных кампании
https://api.mobizon.kz/service/Campaign/GetInfo

Получение списка кампаний
https://api.mobizon.kz/service/Campaign/List

Отправка кампании
https://api.mobizon.kz/service/Campaign/Send

Добавление получателей в массовую SMS кампанию

https://api.mobizon.kz/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.kz/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.kz/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%97%D0%B4%D1%80%D0%B0%D0%B2%D1%81%D1%82%D0%B2%D1%83%D0%B9%D1%82%D0%B5%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%BE%D1%81%D1%82%D0%B0%D0%B2%D0%BB%D1%8F%D0%B5%D1%82+%7Bbalance%7D%7Bcurrency%7D.'
var data = "data%5Btype%5D=3&data%5Bfrom%5D=Alpha&data%5Btext%5D=%D0%97%D0%B4%D1%80%D0%B0%D0%B2%D1%81%D1%82%D0%B2%D1%83%D0%B9%D1%82%D0%B5%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%BE%D1%81%D1%82%D0%B0%D0%B2%D0%BB%D1%8F%D0%B5%D1%82+%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.kz/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.kz');

// Вызов АПИ метода
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.kz/service/Campaign/Delete

Данный метод позволяет удалить кампанию по ее ID.
Кампания может быть удалена, если ее отправка еще не началась.
Если кампания отложена: отложенная кампания может быть удалена при условии, что до начала отправки осталось не менее 5 минут.

Параметры запроса

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

Коды ответов API

КодОписание
0Кампания успешно удалена.
2Если кампания с указанным идентификатором не найдена.
10Если кампания с указанным идентификатором не может быть удалена.

Examples

curl -X POST \
  'https://api.mobizon.kz/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.kz/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.kz');

// Вызов АПИ метода
if ($api->call(
    'campaign',
    'delete',
    array(
        //идентификатор кампании
        'id' => '123'
    )
)
) {
    // Получение результата выполнения метода
    $result = $api->getData();
} else {
    // Во время выполнения произошла ошибка, вывод кода ошибки и текста сообщения
    echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}

Получение основных данных кампании

https://api.mobizon.kz/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.kz/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.kz/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.kz');

// Вызов АПИ метода
if ($api->call(
    'campaign',
    'get',
    array(
        //идентификатор кампании
        'id' => '123'
    )
)
) {
    // Получение результата выполнения метода
    $result = $api->getData();
} else {
    // Во время выполнения произошла ошибка, вывод кода ошибки и текста сообщения
    echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}

Получение статистических данных кампании

https://api.mobizon.kz/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.kz/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.kz/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.kz');

// Вызов АПИ метода
if ($api->call(
    'campaign',
    'getInfo',
    array(
        //идентификатор кампании
        'id' => '123'
    )
)
) {
    // Получение результата выполнения метода
    $result = $api->getData();
} else {
    // Во время выполнения произошла ошибка, вывод кода ошибки и текста сообщения
    echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}

Получение списка кампаний

https://api.mobizon.kz/service/Campaign/List

Данный метод позволяет получить список созданных кампаний. Поиск может быть осуществлен по ID и другим полям.

Параметры запроса

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

Критерии поиска

Ниже перечислены поля кампаний по которым осуществляется поиск. Поиск можно осуществлять как по одному, так и по нескольким полям одновременно.

ПараметрТипОписание
criteria[id]integerПоиск одной кампании по ее ID.
criteria[ids]arrayПоиск нескольких кампаний по их ID.
Параметр должен быть передан в виде массива или строки идентификаторов, разделенных запятыми.
Максимальное количество идентификаторов – 100, при превышении этого лимита поиск будет происходить по первым 100 ID из списка.
criteria[recipient]stringПоиск по номеру телефона получателя или его части.
Например:
77273573423 – найдет все кампании, в которых участвовал этот номер;
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.kz/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.kz/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.kz');

// Вызов АПИ метода
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.kz/service/Campaign/Send

Данный метод позволяет отправить созданную кампанию по ее ID.

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

Параметры запроса

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

Ответ сервера

integer: статус отправки кампании.

Возможные значения:

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

Коды ответов API

КодОписание
0Кампания успешно отправлена.
2Если кампания не найдена.
10Если не удалось сменить статус кампании.

Examples

curl -X POST \
  'https://api.mobizon.kz/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.kz/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.kz');

// Вызов АПИ метода
if ($api->call(
    'campaign',
    'send',
    array(
        //идентификатор кампании
        'id' => '123'
    )
)
) {
    // Получение результата выполнения метода
    $result = $api->getData();
} else {
    // Во время выполнения произошла ошибка, вывод кода ошибки и текста сообщения
    echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}