Регистрация

Модуль Message

Создание, отправка, и другие функции для работы с одиночными сообщениями (не рассылками).

API methods

Получение отчета о статусе доставки SMS сообщения
https://api.mobizon.ua/service/Message/GetSMSStatus

Получение списка SMS сообщений
https://api.mobizon.ua/service/Message/List

Отправка одиночного SMS сообщения
https://api.mobizon.ua/service/Message/SendSmsMessage

Получение отчета о статусе доставки SMS сообщения

https://api.mobizon.ua/service/Message/GetSMSStatus

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

Независимо от типа входного параметра, возвращаемый результат всегда представлен в виде массива.

Если передавать несуществующие или не принадлежащие пользователю идентификаторы сообщений, то результат не будет содержать информации об этих сообщениях.

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

ПараметрТипОписание
idsarray stringИдентификатор(ы) сообщения(й).
Массив или строка идентификаторов, разделенных запятыми.
Максимальное количество идентификаторов в одном запросе – 100.

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

ПолеТипОписание
idintegerИдентификатор сообщения.
statusstringСтатус сообщения.
Cм. таблицу Список возможных статусов сообщений.
segNumintegerКоличество сегментов в данном сообщении.
startSendTsstringВремя начала отправки сообщения.
Формат: ГГГГ-ММ-ДД ЧЧ-ММ-СС.
Если сообщение еще не отправлено, значение поля будет NULL.
statusUpdateTsstringВремя последнего обновления статуса сообщения.
Формат: ГГГГ-ММ-ДД ЧЧ-ММ-СС.
Если сообщение еще не отправлено, значение поля будет NULL.

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

КодОписание
0Отчет о статусе доставки успешно получен.
2Eсли не указано ни одного идентификатора сообщений.
12Eсли указано более 100 идентификаторов сообщений.

Examples

curl -X POST \
  'https://api.mobizon.ua/service/message/getSMSStatus?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'ids%5B0%5D=123&ids%5B1%5D=556&ids%5B2%5D=988'
var data = "ids%5B0%5D=123&ids%5B1%5D=556&ids%5B2%5D=988";

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/message/getSMSStatus?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(
    'message',
    'getSMSStatus',
    array(
        //идентификаторы сообщений
        'ids' => array(
            '123',
            '556',
            '988'
        )
    )
)
) {
    // Получение результата выполнения метода
    $result = $api->getData();
} else {
    // Во время выполнения произошла ошибка, вывод кода ошибки и текста сообщения
    echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}

Получение списка SMS сообщений

https://api.mobizon.ua/service/Message/List

Данный метод позволяет получить список созданных SMS-сообщений.

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

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

ПараметрТипОписание
criteriaarrayКритерии поиска (см. таблицу Критерии поиска).
paginationarrayПараметры постраничного вывода (см. таблицу Параметры постраничного вывода).
sortarrayПараметры сортировки (см. таблицу Параметры сортировки).
withNumberInfointegerДанный параметр позволяет получить от сервера дополнительную информацию о номере получателя, такую как «страна» и «оператор».
Возможные значения:
0 – не получать (установлено по умолчанию);
1 – получать.

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

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

ПараметрТипОписание
criteria[campaignIds]array \ stringПоиск по идентификаторам кампаний.
Параметр должен быть передан в виде массива или строки идентификаторов, разделенных запятыми.
Максимальное количество идентификаторов – 100, при превышении этого лимита поиск будет происходить по первым 100 ID из списка.
criteria[from]stringПоиск по подписи отправителя.
Поиск проходит по подписи отправителя, которая была создана в кампании.
criteria[to]stringПоиск по номеру телефона получателя.
Разрешен поиск как по целому номеру, так и по его части.
Например:
380443399669 – найдет все кампании, в которых участвовал этот номер;
38097 – будут найдены все кампании с номерами, содержащими указанную комбинацию цифр.
В поиске может участвовать только один номер.
criteria[text]stringПоиск по тексту сообщения кампании.
Осуществляется по принципу полного соответствия искомого значения.
criteria[status]integerПоиск по статусу сообщения.
criteria[groups]stringПоиск по идентификаторам контактных групп, используемым в кампании.
Параметр должен быть передан в виде массива или строки идентификаторов, разделенных запятыми.
criteria[campaignStatus]stringПоиск по статусу кампании SMS-сообщения.
criteria[campaignCreateTsFrom]stringПоиск по дате и времени создания кампаний, начиная с указанной даты и времени.
Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС.
criteria[campaignCreateTsTo]stringПоиск по дате и времени создания кампаний до указанной даты и времени.
Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС.
criteria[campaignSentTsFrom]stringПоиск по дате и времени отправленных кампаний, начиная с указанной даты и времени.
Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС.
criteria[campaignSentTsTo]stringПоиск по дате и времени отправленных кампаний до указанной даты и времени.
Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС.
criteria[startSendTsFrom]stringПоиск по дате и времени отправленных сообщений, начиная с указанной даты и времени.
Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС.
criteria[startSendTsTo]stringПоиск по дате и времени отправленных сообщений до указанной даты и времени.
Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС.
criteria[statusUpdateTsFrom]stringПоиск по дате и времени сообщений, статус которых был изменен, начиная с указанных даты и времени.
Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС.
criteria[statusUpdateTsTo]stringПоиск по дате и времени сообщений, статус которых был изменен до указанных даты и времени.
Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС.

Параметры постраничного вывода

Данные параметры созданы для структурированного (частичного) вывода запрашиваемой информации.

ПараметрТипОписание
pagination[pageSize]integerКоличество отображаемых элементов на странице (25, 50, 100).
pagination[currentPage]integerТекущая страница
Нумерация страниц начинается с 0.

Параметры сортировки

С помощью данных параметров можно отсортировать результаты поиска по одному из полей в порядке возрастания (ASC) или убывания (DESC).

Например:

Сортировка по номеру получателя по возрастанию – sort[to]: ASC.

Сортировка по статусу сообщения по убыванию – sort[status]: DESC.

ПараметрОписание
sort[campaignId]Сортировка по идентификатору кампании.
sort[from]Сортировка по подписи отправителя.
sort[to]Сортировка по номеру получателя.
sort[text]Сортировка по тексту.
sort[status]Сортировка по статусу сообщения.
sort[startSendTs]Сортировка по времени отправки.
sort[statusUpdateTs]Сортировка по обновлению статуса.
sort[segNum]Сортировка по количеству сегментов.

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

Массив данных:

ПолеТипОписание
itemsarrayСписок найденных сообщений (см. таблицу Список сообщений).
totalItemCountintegerОбщее количество найденных элементов.
Список сообщений

Каждое из сообщений содержит поля:

ПолеТипОписание
idintegerИдентификатор сообщения.
campaignIdintegerИдентификатор кампании сообщения.
segNumintegerКоличество сегментов.
segUserBuyfloatСтоимость сегмента сообщения для пользователя
Указывается в валюте пользователя.
fromstringПодпись отправителя.
tostringНомер получателя.
textstringТекст сообщения.
statusstringСтатус сообщения (см. таблицу Список возможных статусов сообщений).
groupsstringИдентификаторы контактных групп, в которые входил номер получателя на момент создания кампании.
uuidstringВнутренний идентификатор сообщения.
countryA2stringКод страны получателя в формате ISO-3166 alpha2.
operatorNamestringНазвание оператора получателя.
startSendTsdateДата и время отправки сообщения.
Формат: ГГГГ-ММ-ДД ЧЧ-ММ-СС.
statusUpdateTsdateДата и время последнего обновления статуса сообщения.
Формат: ГГГГ-ММ-ДД ЧЧ-ММ-СС.

Examples

curl -X POST \
  'https://api.mobizon.ua/service/message/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%5BcampaignId%5D=ASC'
var data = "criteria%5Bfrom%5D=Alpha&pagination%5BcurrentPage%5D=2&pagination%5BpageSize%5D=50&sort%5BcampaignId%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/message/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(
    'message',
    'list',
    array(
        //критерии поиска
        'criteria' => array(
            //подпись отправителя
            'from' => 'Alpha'
        ),
        //параметры постраничного вывода
        'pagination' => array(
            //текущая страница
            'currentPage' => '2',
            //количество отображаемых элементов на странице
            'pageSize' => '50'
        ),
        //параметры сортировки
        'sort' => array(
            //сортировка по идентификтору кампании
            'campaignId' => 'ASC'
        )
    )
)
) {
    // Получение результата выполнения метода
    $result = $api->getData();
} else {
    // Во время выполнения произошла ошибка, вывод кода ошибки и текста сообщения
    echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}

Отправка одиночного SMS сообщения

https://api.mobizon.ua/service/Message/SendSmsMessage

Данный метод позволяет отправить одиночное SMS-сообщение на указанный номер мобильного телефона.

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

ПараметрТипОписание
recipientstringТелефонный номер получателя SMS-сообщения.
Номер должен быть в международном формате и содержать только цифры.
Например: 380443399669.
Если в номере есть “+” в начале, то его следует закодировать в URL-сущность %2B или удалить, оставив только цифры.
textstringТекст SMS-сообщения, закодированный в URL-сущность.
Если во время попытки отправить сообщение при помощи GET запроса система не возвращает ответ с данными сообщения, следует в первую очередь обратить внимание на наличие спецсимволов в теле запроса, такими символами являются: ? / \ & + и [пробел].
Наличие таких символов говорит о том, что текст не был закодирован.
fromstringПодпись отправителя.
Для использования собственной подписи отправителя ее необходимо предварительно зарегистрировать.
Если подпись не указана, будет использована подпись выбранная по умолчанию в вашем аккаунте.
Если у вас нет заведенных подписей или отсутствует возможность отправки с указанной подписью, по возможности будет использована одна из общих подписей сервиса.
Подробнее о подписях отправителя читайте в разделе “Подписи отправителя”.
paramsarrayДополнительные параметры (см. таблицу Дополнительные параметры).

Дополнительные параметры

ПараметрТипОписание
params[name]stringНазвание кампании.
params[deferredToTs]stringДата и время отложенной отправки SMS-сообщения.
Можно установить начало отправки не ранее чем через час и не позднее чем через 14 дней.
Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС.
params[mclass]integerКласс отправляемого сообщения:
0 – сообщения отображаются всплывающим окном и нигде не сохраняются (flashSMS);
1 – сообщения сохраняются в папку Входящих сообщений телефона (установлен по умолчанию).
params[validity]integerМаксимальное время ожидания доставки сообщения, если получатель не может принять его сразу.
Например, если у абонента телефон выключен или находится за пределами сети.
Указывается в минутах с момента отправки: от 60 минут (1 час) до 1440 минут (24 часа).

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

В случае успешной отправки сообщения в ответе содержится массив со следующими полями:

ПолеТипОписание
campaignIdintegerИдентификатор созданной SMS-кампании.
messageIdintegerИдентификатор созданного SMS-сообщения.
statusintegerСтатус отправки SMS-кампании.
1 – кампания ожидает модерации;
2 – кампания отправлена без модерации.

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

КодОписание
0SMS-сообщение успешно отправлено.
1Если хотя бы один из параметров указан неверно.

Examples

curl -X POST \
  'https://api.mobizon.ua/service/message/sendSmsMessage?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'recipient=380443399669&text=Test+sms+message&from=YourAlpha&params%5Bvalidity%5D=1440'
var data = "recipient=380443399669&text=Test+sms+message&from=YourAlpha&params%5Bvalidity%5D=1440";

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/message/sendSmsMessage?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.php';

$api = new Mobizon\MobizonApi('KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK', 'api.mobizon.ua');

// API call to send a message
if ($api->call('message',
    'sendSMSMessage',
    array(
        // Recipient international phone number
        'recipient' => '380443399669',
        // Message text
        'text' => 'Test sms message',
        // Alphaname is optional, if you don't have registered alphaname, just skip this parameter and your message will be sent with our free common alphaname, if it's available for this direction.
         'from' => 'YourAlpha',
         // Message will be expired after 1440 min (24h)
         'params[validity]' => 1440
    ))
) {
    // Get message ID assigned by our system to request it's delivery report later.
    $messageId = $api->getData('messageId');

    if (!$messageId) {
        // Message is not accepted, see error code and data for details.
    }
    // Message has been accepted by API.
} else {
    // An error occurred while sending message
    echo '[' . $api->getCode() . '] ' . $api->getMessage() . 'See details below:' . PHP_EOL . print_r($api->getData(), true) . PHP_EOL;
}