Документация API для SMS рассылок

Unisender API — это специальный интерфейс для разработчиков, который нужен, чтобы встроить возможности рассылок в другой веб-сервис или десктоп-приложение.

Наш API для SMS-рассылок позволяет управлять списками контактов, создавать и отправлять SMS-сообщения, анализировать статистику. Кроме того, есть методы для партнеров.

Пользоваться API можно бесплатно на любом аккаунте сервиса. Чтобы получить доступ к API для SMS-рассылок требуется ключ, который можно найти в личном кабинете.

Не передавайте ключ доступа другим людям и не делайте видимым в коде веб-страниц. Иначе мошенники смогут отправить любую SMS-рассылку от имени вашей компании.

Принцип использования API

Вызов метода

Обращение к методам API для SMS-рассылок — это HTTPS-запрос к URL вида:

https://api.unisender.com/LANG/api/METHOD?format=json&api_key=KEY&arg1=ARG_1&argN=ARG_N

где:

LANG *	язык сообщений сервера API (в данный момент поддерживается ru, en, ua)
METHOD *	название метода
KEY *	ключ доступа к API
ARG_1 ... ARG_N	аргументы метода (свои для каждого метода)

Все параметры запроса должны быть в кодировке UTF-8. Параметры в примере указаны в GET-запросе. Также можно передавать их и в POST-запросе. Параметр api_key рекомендуется передавать только через POST. В этом случае он не будет сохраняться в логах прокси-серверов.

Ответ на запрос приходит в виде объекта формата JSON. Если вы хотите сжать запрос или ответ, воспользуйтесь алгоритмами gzip или bzip2.

Результат успешного вызова метода

Если вызов успешен, то объект будет включать поле "result", содержимое которого зависит от вызванного метода. При этом в ответе не будет поля "error".

Также при успешном вызове допустимо наличие поля "warnings". Оно содержит массив объектов-предупреждений с единственным строковым полем "warning".

Пример ответа успешного вызова метода:

{
    "result": {
        "message_id":34423432
    },
    "warnings": [
        {"warning":"probably not a mobile phone"}
    ]
}

Результат неуспешного вызова метода

Если при выполнении метода возникла ошибка, в ответе вы увидите поле "error" с HTML-сообщением об ошибке и поле "code", в котором указывается код ошибки.

Пример ответа с ошибкой:

{
    "code": "invalid_arg",
    "error": "fields: This value \"mymail@@@@mail.ru\" is not a valid email address.",
    "result": ""
}

Основные коды ошибок при работе с API

Список доступных методов для создания и отправки SMS

Работа со списками контактов
Создание и отправка сообщений
Получение статистики
Работа с дополнительными полями и метками
Методы для партнёрских сайтов

Работа со списками контактов:

getLists — получить списки для рассылок с их кодами;
createList — создать новый список контактов;
updateList — изменить свойства списка рассылки;
deleteList — удалить список контактов;
subscribe — подписать адресата на один или несколько списков рассылки;
exclude — исключить адресата из списков рассылки;
unsubscribe — отписать адресата от рассылки;
importContacts — массовый импорт и синхронизация контактов;
exportContacts — экспорт данных по контактам;
getTotalContactsCount — получить информацию о размере базы пользователя;
getContactCount — получить количество контактов в списке;
getContact — получить информацию об одном контакте.

Создание и отправка сообщений:

createSmsMessage — создать SMS для массовой рассылки;
createCampaign — запланировать отправку SMS сообщения;
cancelCampaign — отменить запланированную ранее массовую рассылку;
sendSms — отправить SMS-сообщение;
checkSms — проверить статус доставки SMS;
deleteMessage — удалить сообщение.

Получение статистики:

getCampaignDeliveryStats — получить отчёт о статусах доставки сообщений для заданной рассылки SMS;
getCampaignCommonStats — получить общие сведения о результатах доставки для заданной SMS-рассылки;
getVisitedLinks — получить статистику переходов по ссылкам;
getCampaigns — получить список рассылок;
getCampaignStatus — получить статус рассылки SMS;
getMessages — получить список сообщений;
getMessage — получить информацию об SMS-сообщении;
listMessages — получить список сообщений без тела и вложений.

Работа с дополнительными полями и метками:

getFields — получить список пользовательских полей;
createField — создать новое поле;
updateField — изменить параметры поля;
deleteField — удалить поле;
getTags — получить список пользовательских меток;
deleteTag — удалить метку.

Методы для партнёрских сайтов:

validateSender — подтвердить обратный адрес;
register — зарегистрировать пользователя (для партнёрских сайтов);
checkUserExists — проверить существование пользователя по логину или email;
getUserInfo — получить информацию о пользователе (для партнёрских сайтов);
getUsers — получить информацию о пользователях (для партнёрских сайтов);
transferMoney — перевести деньги на счёт пользователя (для партнёрских сайтов);
getAvailableTariffs — получить список тарифов (для партнёрских сайтов);
changeTariff — переключить тариф пользователю (для партнёрских сайтов);
setSenderDomain — получить DKIM-ключ для домена отправителя.

Порядок вызова методов для SMS-рассылки

У вас может быть один или несколько списков контактов. Прежде чем рассылать SMS по списку, узнайте код списка в сервисе методом getLists либо создайте новый список с помощью метода createList.

Добавьте контакты в список с помощью метода importContacts (массовое добавление контактов) или subscribe (добавление контактов по одному).

Теперь можно отправлять сообщения. Рассылка создается с помощью метода createSmsMessage. Не забудьте указать id списка с телефонами. Тогда сообщение уйдет всем подписчикам из этого списка, которые были активны на момент вызова createSmsMessage.

Осталось отправить SMS-рассылку. Для отправки смс используйте метод createCampaign. Укажите message_id, который вы получили после отправки метода createSmsMessage. Вы можете отправить рассылку сразу или запланировать на любое время.

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

Цепочка createSmsMessage -> createCampaign отправляет массовую SMS-рассылку по списку. Также можно отправлять одиночные SMS методом sendSms и проверять статус доставки с помощью checkSms.

После рассылки используйте метод getCampaignDeliveryStats, чтобы получить результаты отправки смс.

Быстрый старт

Если вы хотите быстро добавить возможность рассылки SMS в ваш проект, воспользуйтесь нашей библиотекой для класса PHP.

Также для настройки API используйте базовую инструкцию по созданию интеграции.

API для SMS-рассылок