API

Описание протоколов интеграции с внешними приложениями.

• Каскадные рассылки по API
• Типы сообщений при отправке через API
• HTTP API
• Возможные статусы сообщений

Каскадные рассылки по API

Для организации каскадных рассылок через API необходимо учесть, что в настоящий момент такая возможность присутствует только при работе по протоколу HTTP

Процесс запуска каскадной рассылки очень прост. Для этого Вам необходимо создать рассылку с типом "Рассылка по сценарию"

Для формирования каскада рассылки необходимо передать через API СМС сообщение с типом bulk и в качестве подписи отправителя указать цифровой код "Рассылки по сценарию". Тем самым будет запущен каскад для заданного СМС.

Типы сообщений при отправке через API

При отправке сообщений в платформу Kupon.mobi вы можете отправлять типы сообщений указанных в списке ниже:

• sms
• push
• viber
• whatsapp
• telegram
• vk
• ok
• email
• hlr
• voice
• mms
• bot
• bulk *

Для доставки любого из указанных выше типов необходимо, чтобы в Вашем аккаунте был настроен и доступен канал для данных сообщений.

* Виртуальный тип сообщения bulk, который можно применить для формирования каскадной рассылки по API.

HTTP API

Отправка сообщений из платформы осуществляется посредством отправки специальным образом сформированных GET/POST запросов к сервису. 
В случае возникновения вопросов обращайтесь в службу технической поддержки по телефону 8­ 800 ­100 ­6003 Звонок по России бесплатный.
Наши специалисты могут помочь Вам связать Ваш сайт, интернет магазин или ваше программное обеспечение с нашим сервисом абсолютно бесплатно.

Техническая часть

Адрес сервиса: https://1-pulse.kupon.mobi/api/v1/bulk/send-message

Параметры

• token - API токен, используемый для доступа к сервису. Сформировать токен вы можете в вашем личном кабинете по ссылке https://1-pulse.kupon.mobi/platform#/campaign/app/new;

• sent_text - отправляемый текст сообщения;

• html_text  - отправляемый HTML форматированный текст сообщения используется при отправке Email и Push сообщений;
• sent_date - время и дата отправки сообщения в формате ГГГГ-ММ-ДД ЧЧ:ММ;
• sent_to - получатель(ли) сообщения (номер мобильного телефона в международном формате без ведущего "+", адрес электронной почты, список PUSH токенов через запятую), для типа сообщения bulk  поле sent_to должно содержать номер телефона или email ;
• type - тип сообщения ;
• sender -  имя отправителя которое увидят Ваши клиенты в поле "от кого". Так же при использовании каскадной рассылки в этом поле указывается номер рассылки, по правилам которой необходимо формировать каскад сообщений
• charset - кодировка текста в поле sent_text иhtml_text. Доступные варианты: UTF16BE, UTF16LE, CP1251, UTF-8, UTF-16BE, UTF-16LE, UCS-2BE, UCS-2LE, UCS2BE, UCS2LE.
• ttl - срок жизни сообщения в минутах, в течении которого система будет пытаться отправить сообщение и/или ожидать получения конечного статуса сообщения.
• button * - надпись на кнопке;
• action * - url кодированный адрес страницы, которая откроется по кнопке или команда боту;
• image * - url кодированный адрес картинки, отправляемый в сообщении. Картинки отправленные из раздела Медиа, автоматически подгоняются под требования мессенджеров, картинки со сторонних ресурсов отправляются без дополнительной обработки, по этому требуют более тщательной подготовки и проверки отображения в целевых мессенджерах;
• callback - url кодированный адрес, на который система будет пытаться отправить статус сообщения. Статус считается доставленным если на запрос получен код 200. В противном случае будет две попытки через 1 минуту и через 10 минут. По истечении трех попыток, дальнейшие попытки отправить статус сообщения не предпринимаются. Модификатор {id} используется для подстановки идентификатора сообщения, {status} для подстановки статуса сообщения;
• find_token = 1 - включает поиск токенов по номеру телефона или email для сообщений, доставляемых по специальным токенам (Bot, Push);
• kannel_status = 1 - включить совместимость статусов с сервером kannel, при отправке через callback.

* - для сообщений типа bulk игнорируется, если параметр задан в настройках рассылки;

Ответы сервиса

В ответ на отправку POST/GET запроса формируется объект JSON. Если сообщение было отправлено формируется JSON структура содержащая поле type=success, поле id=<id>Идентификатора сообщения присвоенный системой<id>. В случае ошибки поле type=error, поле msg=описание ошибки. При получении статуса сообщения происходит вызов callback.

Адрес сервиса: https://1-pulse.kupon.mobi/api/v1/bulk/send-list-messages

• token - API токен, используемый для доступа к сервису. Сформировать токен вы можете вашем личном кабинете
• type - тип сообщения ;
• sender -  имя отправителя которое увидят Ваши клиенты в поле "от кого". Так же при использовании каскадной рассылки в этом поле указывается номер рассылки, по правилам которой необходимо формировать каскад сообщений
• charset - кодировка текста в поле sent_text иhtml_text. Доступные варианты: UTF16BE, UTF16LE, CP1251, UTF-8, UTF-16BE, UTF-16LE, UCS-2BE, UCS-2LE, UCS2BE, UCS2LE.
• messages - json коллекция группы сообщений

Возможные статусы сообщений

При отправке сообщений процесс доставки контролируется промежуточными и конечными статусами. Возможные типы статусов и их цифровое обозначение в списке ниже:

• -4 -  входящее сообщение;
• -3 - сообщение не найдено;
• -1 - ожидает отправки;
• 0 - отправлено, поступило в очередь доставки к оператору;
• 1 - доставлено;
• 2 - прочитано;
• 3 - просрочено, истекло ttl - время жизни сообщения;
• 4 - в сообщении нажата ссылка;
• 20 - не доставлено;
• 22 - неверный получатель, ошибка в адресе получателя;
• 23 - данное направление запрещено, сработал СПАМ фильтр, фильтр оператора;
• 24 - недостаточно средств на отправку сообщения;
• 25 - получатель не доступен, не в сети;