Создание, отправка, и другие функции для работы с одиночными сообщениями (не рассылками).
Получение отчета о статусе доставки SMS сообщения
https://api.mobizon.ua/service/Message/GetSMSStatus
Получение списка SMS сообщений
https://api.mobizon.ua/service/Message/List
Отправка одиночного SMS сообщения
https://api.mobizon.ua/service/Message/SendSmsMessage
https://api.mobizon.ua/service/Message/GetSMSStatus
Данный метод позволяет получить данные о текущем статусе доставки одного или нескольких SMS-сообщений.
Независимо от типа входного параметра, возвращаемый результат всегда представлен в виде массива.
Если передавать несуществующие или не принадлежащие пользователю идентификаторы сообщений, то результат не будет содержать информации об этих сообщениях.
Параметр | Тип | Описание |
---|---|---|
ids | array string | Идентификатор(ы) сообщения(й). Массив или строка идентификаторов, разделенных запятыми. Максимальное количество идентификаторов в одном запросе – 100. |
Поле | Тип | Описание |
---|---|---|
id | integer | Идентификатор сообщения. |
status | string | Статус сообщения. Cм. таблицу Список возможных статусов сообщений. |
segNum | integer | Количество сегментов в данном сообщении. |
startSendTs | string | Время начала отправки сообщения. Формат: ГГГГ-ММ-ДД ЧЧ-ММ-СС .Если сообщение еще не отправлено, значение поля будет NULL. |
statusUpdateTs | string | Время последнего обновления статуса сообщения. Формат: ГГГГ-ММ-ДД ЧЧ-ММ-СС .Если сообщение еще не отправлено, значение поля будет NULL. |
Код | Описание |
---|---|
0 | Отчет о статусе доставки успешно получен. |
2 | Eсли не указано ни одного идентификатора сообщений. |
12 | Eсли указано более 100 идентификаторов сообщений. |
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;
}
https://api.mobizon.ua/service/Message/List
Данный метод позволяет получить список созданных SMS-сообщений.
Поиск может быть осуществлен по ID и данным из полей кампании.
Параметр | Тип | Описание |
---|---|---|
criteria | array | Критерии поиска (см. таблицу Критерии поиска). |
pagination | array | Параметры постраничного вывода (см. таблицу Параметры постраничного вывода). |
sort | array | Параметры сортировки (см. таблицу Параметры сортировки). |
withNumberInfo | integer | Данный параметр позволяет получить от сервера дополнительную информацию о номере получателя, такую как «страна» и «оператор». Возможные значения: 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] | Сортировка по количеству сегментов. |
Массив данных:
Поле | Тип | Описание |
---|---|---|
items | array | Список найденных сообщений (см. таблицу Список сообщений). |
totalItemCount | integer | Общее количество найденных элементов. |
Каждое из сообщений содержит поля:
Поле | Тип | Описание |
---|---|---|
id | integer | Идентификатор сообщения. |
campaignId | integer | Идентификатор кампании сообщения. |
segNum | integer | Количество сегментов. |
segUserBuy | float | Стоимость сегмента сообщения для пользователя Указывается в валюте пользователя. |
from | string | Подпись отправителя. |
to | string | Номер получателя. |
text | string | Текст сообщения. |
status | string | Статус сообщения (см. таблицу Список возможных статусов сообщений). |
groups | string | Идентификаторы контактных групп, в которые входил номер получателя на момент создания кампании. |
uuid | string | Внутренний идентификатор сообщения. |
countryA2 | string | Код страны получателя в формате ISO-3166 alpha2. |
operatorName | string | Название оператора получателя. |
startSendTs | date | Дата и время отправки сообщения. Формат: ГГГГ-ММ-ДД ЧЧ-ММ-СС . |
statusUpdateTs | date | Дата и время последнего обновления статуса сообщения. Формат: ГГГГ-ММ-ДД ЧЧ-ММ-СС . |
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;
}
https://api.mobizon.ua/service/Message/SendSmsMessage
Данный метод позволяет отправить одиночное SMS-сообщение на указанный номер мобильного телефона.
Параметр | Тип | Описание |
---|---|---|
recipient | string | Телефонный номер получателя SMS-сообщения. Номер должен быть в международном формате и содержать только цифры. Например: 380443399669. Если в номере есть “+” в начале, то его следует закодировать в URL-сущность %2B или удалить, оставив только цифры. |
text | string | Текст SMS-сообщения, закодированный в URL-сущность. Если во время попытки отправить сообщение при помощи GET запроса система не возвращает ответ с данными сообщения, следует в первую очередь обратить внимание на наличие спецсимволов в теле запроса, такими символами являются: ? / \ & + и [пробел] .Наличие таких символов говорит о том, что текст не был закодирован. |
from | string | Подпись отправителя. Для использования собственной подписи отправителя ее необходимо предварительно зарегистрировать. Если подпись не указана, будет использована подпись выбранная по умолчанию в вашем аккаунте. Если у вас нет заведенных подписей или отсутствует возможность отправки с указанной подписью, по возможности будет использована одна из общих подписей сервиса. Подробнее о подписях отправителя читайте в разделе “Подписи отправителя”. |
params | array | Дополнительные параметры (см. таблицу Дополнительные параметры). |
Параметр | Тип | Описание |
---|---|---|
params[name] | string | Название кампании. |
params[deferredToTs] | string | Дата и время отложенной отправки SMS-сообщения. Можно установить начало отправки не ранее чем через час и не позднее чем через 14 дней. Формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС . |
params[mclass] | integer | Класс отправляемого сообщения: 0 – сообщения отображаются всплывающим окном и нигде не сохраняются (flashSMS); 1 – сообщения сохраняются в папку Входящих сообщений телефона (установлен по умолчанию). |
params[validity] | integer | Максимальное время ожидания доставки сообщения, если получатель не может принять его сразу. Например, если у абонента телефон выключен или находится за пределами сети. Указывается в минутах с момента отправки: от 60 минут (1 час) до 1440 минут (24 часа). |
В случае успешной отправки сообщения в ответе содержится массив со следующими полями:
Поле | Тип | Описание |
---|---|---|
campaignId | integer | Идентификатор созданной SMS-кампании. |
messageId | integer | Идентификатор созданного SMS-сообщения. |
status | integer | Статус отправки SMS-кампании. 1 – кампания ожидает модерации; 2 – кампания отправлена без модерации. |
Код | Описание |
---|---|
0 | SMS-сообщение успешно отправлено. |
1 | Если хотя бы один из параметров указан неверно. |
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¶ms%5Bvalidity%5D=1440'
var data = "recipient=380443399669&text=Test+sms+message&from=YourAlpha¶ms%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;
}