Данный модуль содержит функции для создания SMS кампаний, добавления в них получателей одним из возможных способов, запуска кампании в отправку, удаления неактуальных кампаний, просмотра списка кампаний и поиска по ним.
Добавление получателей в массовую 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
https://api.mobizon.kz/service/Campaign/AddRecipients
В одном запросе разрешена передача только данных о получателях одного типа:
При попытке передать сразу несколько разных типов получателей будет возвращена ошибка 12. Если необходимо добавить в одну рассылку получателей из нескольких источников, следует сделать это в несколько запросов.
При добавлении номеров получателей, контактов или контактных карт максимальное число получателей, загружаемых в одном запросе, не может превышать 500 номеров. В случае превышения лимита будет возвращена ошибка 12 и получатели не будут добавлены.
Для загрузки в одну кампанию любого желаемого количества контактов следует разбивать список на порции по 500 или меньше штук и загружать каждую порцию отдельным вызовом апи - получатели будут добавляться к уже существующему списку, если не указан параметр replace=1.
Загрузка номеров, контактов и карт выполняется в основном потоке вебсервера и возвращает результат по каждому обработанному получателю в виде массива (см. формат возвращаемых данных ниже).
Загрузка из контактной группы или из файла вызывает создание фоновой задачи (асинхронная загрузка) и возвращает ее ID для дальнейшего отслеживания статуса. В этом случае код ответа API будет 100.
Номера получателей должны передаваться в международном формате. Все посторонние символы будут удалены из номера автоматически.
Каждый номер проверяется на возможность отправки на него сообщения по коду страны и оператора, которому он принадлежит.
Все не прошедшие проверку номера будут отклонены с соответствующим кодом ошибки (code), а для каждого добавленного номера будет возвращен ID созданного сообщения (messageId) для возможности последующего запроса статуса.
Если не все переданные получатели были добавлены (возникли ошибки), то API может вернуть один из двух кодов ответа:
На все время добавления получателей кампания блокируется на добавление другими процессами, поэтому параллельное добавление в несколько потоков в одну кампанию невозможно.
Параметр | Тип | Описание |
---|---|---|
id | integer | Идентификатор кампании, в которую необходимо добавить получателей |
recipients | array string | Для обычной рассылки (без использования переменных-плейсхолдеров в тексте) получатели, могут быть переданы в виде:
recipient и номером получателя в качестве значения. Так же в данном массиве могут находиться элементы с ключами, соответствующими названиям переменных (плейсхолдеров) в тексте SMS (без окружающих их фигурных скобок).При этом, если какие-то из плейсхолдеров, содержащихся в тексте, не переданы в массиве с данными, то обработка будет происходить в зависимости от значения, переданного в параметре params[placeholdersFlag] (см. ниже описание этого параметра). |
recipientContacts | array string | Массив или строка разделенных запятыми или переносами строк контактов из контактной книги. Контакт может быть указан как:
|
recipientGroups | array string | Массив или строка разделенных запятыми или переносами строк идентификаторов групп из контактной книги, по которым будет сформирована кампания. Если один и тот же контакт содержится в нескольких группах - он будет добавлен в кампанию только один раз. Если несколько контактов содержат одинаковый номер телефона - добавлен будет только первый из них. |
recipientsFile | file | Объект загруженного файла с получателями - файл CSV или Excel (только XLS) с номерами получателей в международном формате. Для обычной рассылки (без использования переменных-плейсхолдеров в тексте) - номера по одному в строку. Для шаблонной рассылки - номера по одному в строку в одном из столбцов с заголовком recipient , в остальных столбцах могут быть данные для подстановки в плейсхолдеры. Заголовки таких столбцов (в первой строке таблицы) должны строго соответствовать плейсхолдерам в тексте SMS (без окружающих фигурных скобок, с учетом регистра символов). Для имен плейсхолдеров разрешены только латинские буквы и цифры, а также символы '_ ', '- '. При наличии столбцов с одинаковыми заголовками, будет возвращена ошибка.При этом, если для каких-либо из плейсхолдеров, содержащихся в тексте, нет соответствующих столбцов, то обработка будет происходить в зависимости от значения, переданного в параметре params[placeholdersFlag] (см. ниже описание данного параметра). |
params | array | Дополнительные настройки (см. таблицу Дополнительные настройки). |
Параметр | Тип | Описание |
---|---|---|
params[replace] | integer | Указывает, нужно ли удалить всех уже добавленных получателей и начать добавление заново: 0 - нет, добавить получателей к уже добавленным ранее (значение по умолчанию); 1 - да, удалить всех добавленных ранее получателей перед добавлением новых; |
params[placeholdersFlag] | integer | Обработка недостающих переменных (плейсхолдеров) для шаблонной рассылки. Если каких либо значений переменных для подстановки в текст не найдено, то возможно одно из следующих поведений: 1 - сообщение добавляется в рассылку, но плейсхолдеры остаются в тексте как есть, замена не происходит (поведение по умолчанию); 2 - сообщение добавляется, а плейсхолдеры удаляются (может быть полезно в случае, если вы используете в тексте фигурные скобки и не хотите, чтобы они были удалены при отправке); 3 - сообщение отклоняется с ошибкой, сообщающей о недостающих данных для подстановки в текст. |
params[recipientsFileEncoding] | string | Кодировка файла с данными получателей. Доступные кодировки: KOI8-R, CP866, WINDOWS-1252, WINDOWS-1251, UTF-8, ASCII, ISO-8859-1, UCS-2. По умолчанию: UTF-8. |
params[recipientsFileSkipHeader] | integer | Указывает, нужно ли пропустить первую строку файла и начать обработку со второй. Полезно, если загрузка получателей происходит из файла, в котором в первой строке находятся названия столбцов. В этом случае первую строку лучше пропустить и начать обработку файла со второй строки. Возможные значения: 0 - начинать с первой строки (значение по умолчанию); 1 - пропускать первую строку файла и начинать обработку со второй (принудительно установлено в случае шаблонной рассылки); В случае шаблонной рассылки значение данного параметра всегда равно 1 и не может быть переопределено, так как в первой строке должны содержаться названия переменных для подстановки. |
params[recipientsFileDelimiter] | string | Разделитель столбцов в файле с данными получателей, по умолчанию: , (запятая). При необходимости вы можете использовать любой другой символ. |
params[recipientsFileEnclosure] | string | Обрамитель текста в файле с данными получателей, по умолчанию: ' (одинарная кавычка). Данный символ должен обрамлять с двух сторон тексты в столбцах, содержащих символ разделителя, чтобы система могла правильно разобрать файл на столбцы. |
array | integer : При загрузке получателей из списка номеров, контактов или контактных карт возвращается массив, каждый элемент которого содержит данные о загруженных получателях:
Поле | Тип | Описание |
---|---|---|
recipient | string | Номер получателя, который добавляется в кампанию |
code | integer | Код результата добавления получателя: 0 - номер успешно добавлен в кампанию 1 - в переданных данных отсутствует номер телефона или его значение пустое 2 - в переданных данных не обнаружен номер телефона (скорее всего данные некорректно отформатированы) 3 - номер не соответствует международному формату телефонных номеров 4 - номер уже был добавлен в кампанию (исключение дубликатов из рассылки) 5 - номер находится в стоп-листе (это может быть как ваш стоп-лист, так и стоп-лист системы) 6 - отправка в страну назначения ограничена настройками вашего аккаунта 7 - невозможно определить оператора и/или страну назначения 8 - в системе отсутствует возможность отправки на данного оператора, обратитесь в нашу техподдержку для уточнения возможности отправки 20 - переданые данные не содержат всех необходимых плейсхолдеров (если placeholdersFlag установлен в значение 1 )30 - контактная карта не найдена в контактной книге ( recipient будет равен null )31 - контактная карта не содержит мобильного номера ( recipient будет равен null )32 - контакт не найден в контактной книге ( recipient будет равен null )51 - по техническим причинам на данный момент невозможно создать короткую ссылку 99 - системная ошибка при добавлении номера получателя |
messageId | integer | Идентификатор добавленного сообщения, если номер был добавлен, по указанному идентификатору можно получить статус сообщения. |
number | integer | Исходное, переданное пользователем значение номера получателя (если передан номер получателя) |
contact | integer | Идентификатор переданного контакта (если передавался recipientContacts ) |
При загрузке файла с получателями или списка контактных групп возвращается числовой идентификатор фоновой задачи добавления получателей. Детали работы с фоновыми задачами см. здесь.
Код | Описание |
---|---|
1 | Если какие либо параметры содержат неверные значения. |
2 | Если кампания с указанным ID не найдена. |
10 | Если указанная кампания заблокирована другим процессом добавления получателей или статус кампании не позволяет добавление получателей. |
12 | Если не передан ни один тип получателей или передано несколько типов получателей в одном запросе. |
98 | Если из всех переданных получателей хотя бы один не был добавлен в кампанию. |
99 | Если ни один получатель не был добавлен в кампанию в результате выполнения запроса. |
100 | Если была запущена фоновая задача добавления получателей. Детали работы с фоновыми задачами см. здесь. |
Для добавления в рассылку списка получателей можно передать их массив вот так:
recipients[]=380971112233&recipients[]=79101112233&recipients[]=77071112233
или вот так:
recipients=380971112233,79101112233,77071112233
Обе формы записи идентичны.
Предположим, что текст SMS следующий: Здравствуйте, {name}! Ваш баланс на {date} составляет {balance}{currency}.
В таком случае в параметре recipients
должны быть переданы данные вида:
recipients[0][recipient]=380971112233
&recipients[0][name]=%D0%92%D0%B0%D1%81%D0%B8%D0%BB%D0%B8%D0%B9
&recipients[0][date]=26.10.17
&recipients[0][balance]=123.45
&recipients[0][currency]=%D0%B3%D1%80%D0%BD
&recipients[1][recipient]=380971112255
&recipients[1][name]=%D0%9E%D0%BB%D1%8C%D0%B3%D0%B0
&recipients[1][date]=26.10.17
&recipients[1][balance]=3222.99
&recipients[1][currency]=%D1%80%D1%83%D0%B1
&recipients[2][recipient]=4901122211112
&recipients[2][name]=Markus
&recipients[2][date]=26.10.17
&recipients[2][balance]=555.45
&recipients[2][currency]=eur
Все данные в передаваемых на сервер полях HTTP запроса должны быть предварительно закодированы в URL encoded string (в каждом языке программирования для этого есть соответствующая функция).
https://api.mobizon.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
– идентификатор кампании, если она успешно создана.
Код | Описание |
---|---|
0 | Кампания успешно создана. |
1 | Если какие-либо параметры содержат неверные значения. |
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 минут.
Параметр | Тип | Описание |
---|---|---|
id | integer | Идентификатор кампании. |
Код | Описание |
---|---|
0 | Кампания успешно удалена. |
2 | Если кампания с указанным идентификатором не найдена. |
10 | Если кампания с указанным идентификатором не может быть удалена. |
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.
Параметр | Тип | Описание |
---|---|---|
id | integer | Идентификатор кампании. |
Массив данных, содержащий следующие поля:
Поле | Тип | Описание |
---|---|---|
id | string | Идентификатор кампании. |
moderationStatus | string | Текущий статус модерации: MODERATION – кампания находится на модерации; DECLINED – кампания отклонена модератором; READY_FOR_SEND – кампания разрешена модератором; AUTO_READY_FOR_SEND – кампания отправлена без модерации. |
commonStatus | string | Текущий статус кампании: MODERATION – кампания проходит модерацию; DECLINED – кампания отклонена модератором (причина отклонения указана в поле globalComment); READY_FOR_SEND – кампания готова к отправке, но отправка еще не началась; RUNNING – кампания в процессе отправки; SENT – кампания полностью отправлена, но еще не все сообщения получили отчет о доставке от оператора связи; DONE – кампания полностью завершена: все окончательные отчеты о доставке получены, счетчики содержат окончательные значения. |
groupsList | array | Список контактных групп, включенных в кампанию. Для каждой группы содержит: id – номер группы; name – имя группы; cardsCnt – количество контактов в группе, доступных для отправки сообщения. Если группы не использовались в кампании, это поле будет пустым. |
type | integer | Тип кампании: 1 – Одиночное сообщение (отправка на один номер); 2 – Массовая рассылка; 3 – Шаблонная кампания; 7 – Функциональная (служебная) кампания. |
msgType | string | Тип сообщений кампании. На данный момент поддерживается только тип «SMS». |
rateLimit | integer | Ограничение количества сообщений, отправленных за период времени, указанный в поле ratePeriod . |
ratePeriod | integer | Период времени в секундах, за который будет отправлено количество SMS, указанное в поле rateLimit . |
sendStatus | string | Статус отправки кампании: SENT – кампания отправлена; DONE – кампания завершена. |
isDeleted | integer | Флаг, означающий, что кампания удалена: 0 – кампания доступна; 1 – кампания удалена. |
deferredToTs | string | Дата и время отложенной отправки кампании. Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС . |
createTs | string | Дата и время создания кампании. Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС . |
startSendTs | string | Дата и время фактического начала отправки кампании. Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС . |
endSendTs | string | Дата и время окончания отправки всех сообщений кампании. Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС . |
name | string | Название кампании. |
from | string | Подпись отправителя, которая была выбрана для отправки кампании. |
text | string | Полный текст сообщения или шаблонный текст с плейсхолдерами. |
validity | integer | Максимальное время ожидания доставки сообщения, если получатель не может принять его сразу, в минутах с момента отправки. |
mclass | integer | Класс отправляемого сообщения: 0 – сообщения отображаются всплывающим окном и нигде не сохраняются (flashSMS); 1 – сообщения сохраняются в папку Входящих сообщений телефона. |
trackShortLinkRecipients | integer | Использована ли функция отслеживания получателей: 0 – функция не использована; 1 – функция использована. |
groups | string | Идентификаторы контактных групп, используемых в кампании, разделенные запятыми. |
globalComment | string | Комментарий модератора, в случае, если кампания отклонена. |
curl -X POST \
'https://api.mobizon.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
.
ВАЖНО!
Из-за технических особенностей подсчета стоимости кампании, данные о возможной стоимости кампании указаны на момент добавления получателей и не меняются с течением времени.
Изменения могут произойти только при повторной загрузке получателей или при редактировании данных кампании (в случае редактирования данных все получатели и расчеты сбрасываются – требуется повторная загрузка).
Параметр | Тип | Описание |
---|---|---|
id | integer | Идентификатор кампании. |
getFilledTplCampaignText | integer | Формат возвращаемых данных: 0 – текст кампании с плейсхолдерами; 1 – возвращать текст шаблонной кампании, заполненный реальными данными получателя (по умолчанию). |
Поле | Тип | Описание |
---|---|---|
id | integer | Идентификатор кампании. |
moderationStatus | string | Текущий статус модерации: MODERATION – кампания находится на модерации; DECLINED – кампания отклонена модератором; READY_FOR_SEND – кампания разрешена модератором; AUTO_READY_FOR_SEND – кампания отправлена без модерации. |
commonStatus | string | Текущий статус кампании: MODERATION – кампания проходит модерацию; DECLINED – кампания отклонена модератором (причина отклонения указана в поле globalComment );READY_FOR_SEND – кампания готова к отправке, но отправка еще не началась; RUNNING – кампания в процессе отправки; SENT – кампания полностью отправлена, но еще не все сообщения получили отчет о доставке от оператора связи; DONE – кампания полностью обработана, все окончательные отчеты о доставке получены. |
groupsList | array | Список контактных групп, включенных в кампанию. Для каждой группы содержит: id – номер группы; name – имя группы; cardsCnt – количество контактов в группе, доступных для отправки сообщения. Если группы не использовались в кампании, это поле будет пустым. |
type | integer | Тип кампании: 1 – Одиночное сообщение (отправка на один номер); 2 – Массовая рассылка; 3 – Шаблонная кампания; 7 – Функциональная (служебная) кампания. |
msgType | string | Тип сообщений кампании. На данный момент поддерживается только тип «SMS». |
rateLimit | integer | Ограничение количества сообщений, отправленных за период времени, указанный в поле ratePeriod . |
ratePeriod | integer | Период, в течение которого за отрезок времени будет отправлено количество SMS, указанное в поле rateLimit . |
sendStatus | string | Статус отправки кампании: SENT – кампания отправлена; DONE – кампания завершена. |
isDeleted | integer | Флаг, который означает, что кампания удалена: 0 – кампания доступна; 1– кампания удалена. |
deferredToTs | string | Дата и время отложенной отправки кампании. Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС . |
createTs | string | Дата и время создания кампании. Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС . |
startSendTs | string | Дата и время фактического начала отправки кампании. Если отправка не была начата, то данное поле содержит NULL. Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС . |
endSendTs | string | Дата и время окончания отправки всех сообщений кампании. Если отправка сообщений не была завершена – данное поле содержит NULL. Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС . |
name | string | Название кампании. |
from | string | Подпись отправителя, которая была выбрана для отправки кампании. |
text | string | Полный текст сообщения или шаблонный текст с плейсхолдерами. |
validity | integer | Максимальное время ожидания доставки сообщения, если получатель не может принять его сразу, в минутах с момента отправки. |
mclass | integer | Класс отправляемого сообщения: 0 – сообщения отображаются всплывающим окном и нигде не сохраняются (flashSMS); 1 – сообщения сохраняются в папку Входящих сообщений телефона. |
trackShortLinkRecipients | integer | Использована ли функция отслеживания получателей: 0 – функция не использована; 1 – функция использована. |
groups | string | Идентификаторы контактных групп, используемых в кампании, разделенные запятыми. |
globalComment | string | Комментарий модератора, в случае, если кампания отклонена. |
creationWay | integer | Способ создания кампании: 1 – с помощью Интернет-браузера; 5 – функциональная (служебная) кампания. |
counters | array | Различные счетчики кампании, описанные в таблице Поля объекта counters . |
counters
Поле | Тип | Описание |
---|---|---|
updateTs | datetime | Время последнего обновления счетчиков. Для снижения нагрузки на систему обновление счетчиков может происходить с задержкой. Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС . |
totalNewSegNum | integer | Общее количество сегментов со статусом NEW . |
totalAcceptdSegNum | integer | Общее количество сегментов со статусом ACCEPTD . |
totalDelivrdSegNum | integer | Общее количество сегментов со статусом DELIVRD . |
totalRejectdSegNum | integer | Общее количество сегментов со статусом REJECTD . |
totalExpiredSegNum | integer | Общее количество сегментов со статусом EXPIRED . |
totalUndelivSegNum | integer | Общее количество сегментов со статусом UNDELIV . |
totalDeletedSegNum | integer | Общее количество сегментов со статусом DELETED . |
totalUnknownSegNum | integer | Общее количество сегментов со статусом UNKNOWN . |
totalPdlivrdSegNum | integer | Общее количество сегментов со статусом PDLIVRD . |
totalSegNum | integer | Общее количество сегментов в кампании. Обновляется при добавлении получателей. |
totalNewMsgNum | integer | Общее количество сообщений со статусом NEW . |
totalAcceptdMsgNum | integer | Общее количество сообщений со статусом ACCEPTD . |
totalDelivrdMsgNum | integer | Общее количество сообщений со статусом DELIVRD . |
totalRejectdMsgNum | integer | Общее количество сообщений со статусом REJECTD . |
totalExpiredMsgNum | integer | Общее количество сообщений со статусом EXPIRED . |
totalUndelivMsgNum | integer | Общее количество сообщений со статусом UNDELIV . |
totalDeletedMsgNum | integer | Общее количество сообщений со статусом DELETED . |
totalUnknownMsgNum | integer | Общее количество сообщений со статусом UNKNOWN . |
totalPdlivrdMsgNum | integer | Общее количество сообщений со статусом PDLIVRD . |
totalMsgNum | integer | Общее количество сообщений (не сегментов). Обновляется при обработке (перед отправкой) сообщений/сегментов кампании. |
totalNewMsgCost | float | Общая стоимость всех сегментов со статусом NEW . |
totalAcceptdMsgCost | float | Общая стоимость всех сегментов со статусом ACCEPTD . |
totalDelivrdMsgCost | float | Общая стоимость всех сегментов со статусом DELIVRD . |
totalRejectdMsgCost | float | Общая стоимость всех сегментов со статусом REJECTD . |
totalExpiredMsgCost | float | Общая стоимость всех сегментов со статусом EXPIRED . |
totalUndelivMsgCost | float | Общая стоимость всех сегментов со статусом UNDELIV . |
totalDeletedMsgCost | float | Общая стоимость всех сегментов со статусом DELETED . |
totalUnknownMsgCost | float | Общая стоимость всех сегментов со статусом UNKNOWN . |
totalPdlivrdMsgCost | float | Общая стоимость всех сегментов со статусом PDLIVRD . |
totalCost | float | Общая стоимость кампании. |
recipientsRejected | integer | Количество отклоненных получателей (не включенных в кампанию). Обновляется при добавлении получателей. |
curl -X POST \
'https://api.mobizon.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 и другим полям.
Параметр | Тип | Описание |
---|---|---|
criteria | array | Критерии поиска (см. таблицу Критерии поиска). |
pagination | array | Параметры постраничного вывода (см. таблицу Параметры постраничного вывода). |
sort | array | Параметры сортировки (см. таблицу Параметры сортировки). |
Ниже перечислены поля кампаний по которым осуществляется поиск. Поиск можно осуществлять как по одному, так и по нескольким полям одновременно.
Параметр | Тип | Описание |
---|---|---|
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] | Сортировка по дате и времени окончания отправки кампании. |
Содержит массив из двух полей:
Поле | Тип | Описание |
---|---|---|
items | array | Список найденных кампаний. Описание полей кампании смотрите в описании метода campaign/getInfo. |
totalItemCount | integer | Общее количество найденных элементов. |
Статус | Описание |
---|---|
NEW | Кампания создана, но пользователь еще не отправил ее. В этом статусе разрешено добавление получателей. |
MODERATION | Проходит модерацию на соответствие правилам сервиса. |
DECLINED | Отклонена модератором, так как не соответствует правилам сервиса или требованиям операторов, номера которых присутствуют в кампании. |
READY_FOR_SEND | Кампания готова к отправке, но отправка еще не началась. |
AUTO_READY_FOR_SEND | Нет необходимости в модерации кампании. Кампания будет отправлена без модерации. |
NOT_YET_SENT | Включает все статусы, когда кампания еще не была отправлена. Это значение используется только для поиска. У кампаний его быть не может. |
RUNNING | Кампания запущена, идет процесс отправки оператору. |
DEFERRED | Отправка кампании запланирована на определенное время. Это значение используется только для поиска. У кампаний его быть не может. |
SENT | Кампания полностью отправлена, но еще не все сообщения получили отчет о доставке от операторов связи. |
DONE | Кампания полностью обработана, все окончательные отчеты о доставке получены. После установки этого статуса никакие счетчики кампании не изменяются. |
curl -X POST \
'https://api.mobizon.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.
Обращаем ваше внимание! В зависимости от условий, таких как подозрение на спам, наличие подозрительного содержимого в тексте сообщения, ограничение для определенного направления и т.д., а также условий сотрудничества (заключенный договор), кампания может попасть на модерацию.
Параметр | Тип | Описание |
---|---|---|
id | integer | Идентификатор кампании. |
integer
: статус отправки кампании.
1 – кампания проверяется модератором;
2 – кампания отправлена.
Код | Описание |
---|---|
0 | Кампания успешно отправлена. |
2 | Если кампания не найдена. |
10 | Если не удалось сменить статус кампании. |
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;
}