НТТP протокол для отправки каскадной рассылки
Запрос отправляется на адрес: https://webapi.smsgold.ru/v1/cascade/
Метод отправки запроса: POST Content-Type: application/json
Структура отправляемого JSON запроса:
{
"auth": {
"user": "XXXXX",
"pass": "PASSWORD"
},
"number": "79XXXXXXXXX",
"stages": [
перечисление возможных шагов каскада в очередности отправки
]
}
Список параметров JSON запроса:
| Имя параметра | Значение параметра |
|---|---|
| number | Телефонный номер получателя сообщения в международном формате без символа "+". |
| auth {...} | Блок авторизации: |
| user | Зарегистрированное в системе ID пользователя вида XXXXX или ХХХХХ.X |
| pass | Пароль пользователя. |
| stages [...] | Перечисление возможных шагов каскада, которые необходимо задействовать при отправке сообщений на номер абонента. Шаги можно указывать в любом порядке: |
| "type": "vk" | ВКонтакте и Одноклассники. |
| "type": "flashCall" | Отправка кода звонком. |
| "type": "voiceCode" | Отправка кода голосом. |
| "type": "voice" | Голосовые оповещения. |
| "type": "telegramBot" | Отправка сообщения подписчику Telegram бота. |
| "type": "telegramPersonal" | Отправка сообщения пользователю Telegram, используя номер телефона или имя пользователя. |
| "type": "sms" | SMS. |
Параметры каждого из возможных шагов передаются в наборе пар "ключ-значение" вложенной записи (объекта) "payload".
Параметры шага "ВКонтакте и Одноклассники" (обязательные и необязательные):
| Имя параметра | Значение параметра |
|---|---|
| vkTemplateName | Имя шаблона, зарегистрированного ранее. Приходит при создании шаблона в письме с подтверждением от ВК ОК. Также можно получить при просмотре списка шаблонов. |
| vkService | Присылается с первым одобренным шаблоном для подключаемой группы на указанный при запросе шаблона e-mail. |
| vkRoutes | Маршрут отправки (vk - значение по умолчанию ВКонтакте, ok - Одноклассники, vk,ok - оба, т.е. доставка производится до первого получения уведомления на физическое устройство. При указании нескольких каналов доставки в итоге использован и тарифицирован будет только один из каналов.) |
| vkDeliveryPolicy | (any, mobile_device_required, verified_phone_number) |
| vkTtl | Время жизни сообщения в секундах (от 60 до 24*60*60). |
| vkReadTtl | Принимает значения от 0 сек. (не использовать каскад по непрочтению) до 24*60*60 сек. Работает по принципу: если сообщение не было прочитано в течении установленного количества секунд - осуществляется следующий шаг, даже если сообщение было доставлено. Денежные средства за отправку сообщения ВК ОК не возвращаются, а в отчете появляется еще одно сообщение, т.е обновления старого объекта не происходит. |
| vkTemplateData | Передача переменных из шаблона {"any_variable_name1": "any_variable_value1", "any_variable_name2": "any_variable_value2"...}(Если в шаблоне используются переменные, то данный параметр обязателен). |
Пример блока "type": "vk" в отправляемом JSON запросе (развернуть)...
{
"auth": {
"user": "XXXXX",
"pass": "PASSWORD"
},
"number": "79XXXXXXXXX",
"stages": [
...
{
"type": "vk",
"payload": {
"vkTemplateName": "string",
"vkService": "string",
"vkRoutes": "string",
"vkDeliveryPolicy": "string",
"vkTtl": 0,
"vkReadTtl": 0,
"vkTemplateData": {
"any_variable_name": "any_variable_value"
}
}
},
...
]
}
Параметры шага "Отправка кода звонком" не используются.
Пример блока "type": "flashCall" в отправляемом JSON запросе (развернуть)...
{
"auth": {
"user": "XXXXX",
"pass": "PASSWORD"
},
"number": "79XXXXXXXXX",
"stages": [
...
{
"type": "flashCall"
},
...
]
}
Параметры шага "Отправка кода голосом" (необязательные):
| Имя параметра | Значение параметра |
|---|---|
| code | 4-значный код. Если параметр не передавать - код генерируется на нашей стороне. |
Пример блока "type": "voiceCode" в отправляемом JSON запросе (развернуть)...
{
"auth": {
"user": "XXXXX",
"pass": "PASSWORD"
},
"number": "79XXXXXXXXX",
"stages": [
...
{
"type": "voiceCode",
"payload": {
"code": "XXXX"
}
},
...
]
}
Параметры шага "Голосовые оповещения" (обязательные):
| Имя параметра | Значение параметра |
|---|---|
| text | Текст сообщения, которое при голосовом оповещении будет преобразовано в голосовое сообщение. |
| sender | Номер отправителя от которого будет осуществлен голосовой вызов (регистрируется через личный кабинет). |
Пример блока "type": "voice" в отправляемом JSON запросе (развернуть)...
{
"auth": {
"user": "XXXXX",
"pass": "PASSWORD"
},
"number": "79XXXXXXXXX",
"stages": [
...
{
"type": "voice",
"payload": {
"text": "string",
"sender": "78XXXXXXXXX"
}
},
...
]
}
Параметры шага "Отправка сообщения подписчику Telegram бота" (взаимоисключающие обязательные, обязательные и необязательные):
| Имя параметра | Значение параметра |
|---|---|
| subscriberId | Идентификатор пользователя. Значение параметра "id" из запроса "Получить список подписчиков бота" (ссылка "НТТP протокол для взаимодействия с Telegram" блок "Получить список подписчиков бота") или меню личного кабинета "Чат-боты \ Боты и каналы" ссылка "Управление" у нужного бота, затем значение в колонке "Идентификатор" напротив имени пользователя.(параметры subscriberId и botId взаимоисключающие, можно использовать только один!) |
| botId | Идентификатор Telegram бота. Значение параметра "id" из запроса "Получить список подключенных ботов" (ссылка "НТТP протокол для взаимодействия с Telegram" блок "Получить список подключенных ботов") или меню личного кабинета "Чат-боты \ Боты и каналы" колонка "Идентификатор" напротив необходимого Telegram бота (подключается непосредственно пользователем - кнопка "Добавить канал" далее иконка "Telegram бот").(параметры botId и subscriberId взаимоисключающие, можно использовать только один!) |
| text | Текст передаваемого сообщения. |
| file {...} | Блок с прикрепленным к сообщению файлом: |
| name | Имя файла. |
| mime | Медиа тип файла тип/подтип (image/png, text/plain, video/mp4 ...). |
| baseString | Файл преобразованный в строку. |
| buttons [{...}, {...}, ...] | Массив c кнопками. Кнопок может быть несколько: |
| text | Текст, отображаемый на кнопке. |
| url | URL-адрес для перехода по кнопке. |
Пример блока "type": "telegramBot" с использованием subscriberId в отправляемом JSON запросе (развернуть)...
{
"auth": {
"user": "XXXXX",
"pass": "PASSWORD"
},
"number": "79XXXXXXXXX",
"stages": [
...
{
"type": "telegramBot",
"payload": {
"subscriberId": "XXXXXXXXXXXXXXXXXXXXXXXX",
"text": "Текст Вашего сообщения",
"file": {
"name": "image.png",
"mime": "image/png",
"baseString": "string"
},
"buttons": [
{
"text": "Текст на кнопке 1",
"url": "https://ссылка_для_кнопки_1"
},
{
"text": "Текст на кнопке 2",
"url": "https://ссылка_для_кнопки_2"
}
]
}
},
...
]
}
Пример блока "type": "telegramBot" с использованием botId в отправляемом JSON запросе (развернуть)...
{
"auth": {
"user": "XXXXX",
"pass": "PASSWORD"
},
"number": "79XXXXXXXXX",
"stages": [
...
{
"type": "telegramBot",
"payload": {
"botId": "ZZZZZZZZZZZZZZZZZZZZZZZZ",
"text": "Текст Вашего сообщения",
"file": {
"name": "image.png",
"mime": "image/png",
"baseString": "string"
},
"buttons": [
{
"text": "Текст на кнопке 1",
"url": "https://ссылка_для_кнопки_1"
},
{
"text": "Текст на кнопке 2",
"url": "https://ссылка_для_кнопки_2"
}
]
}
},
...
]
}
Параметры шага "Отправка сообщения пользователю Telegram, используя номер телефона или имя пользователя" (обязательные и необязательные):
| Имя параметра | Значение параметра |
|---|---|
| connectionId | Идентификатор личного Telegram аккаунта. Меню личного кабинета "Чат-боты \ Боты и каналы" колонка "Идентификатор" напротив необходимого личного Telegram аккаунта (подключается непосредственно пользователем для своего мобильного номера - кнопка "Добавить канал" далее иконка "Личный Telegram аккаунт"). |
| username | Имя абонента в Telegram. Можно передавать оба параметра username и number или не указывать username. Если передаются оба, то сначала идёт попытка связаться с пользователем по имени абонента, как безопасный вариант, потом уже по номеру телефона. ВАЖНО: Начинать диалог по номеру (т.е. без указания username) можно не раньше чем раз в 3 минуты. |
| text | Текст передаваемого сообщения. |
| file {...} | Блок с прикрепленным к сообщению файлом: |
| name | Имя файла. |
| mime | Медиа тип файла тип/подтип (image/png, text/plain, video/mp4 ...). |
| baseString | Файл преобразованный в строку. |
Пример блока "type": "telegramPersonal" в отправляемом JSON запросе (развернуть)...
{
"auth": {
"user": "XXXXX",
"pass": "PASSWORD"
},
"number": "79XXXXXXXXX",
"stages": [
...
{
"type": "telegramPersonal",
"payload": {
"connectionId": "YYYYYYYYYYYYYYYYYYYYYYYY",
"username": "string",
"text": "Текст Вашего сообщения",
"file": {
"name": "image.png",
"mime": "image/png",
"baseString": "string"
}
}
},
...
]
}
Параметры шага "SMS" (обязательные и необязательные):
| Имя параметра | Значение параметра |
|---|---|
| text | Текст, передаваемый в SMS. |
| sender | Подпись отправителя, строка длиной до 11 символов (текст) или до 16 символов (номер) в зависимости от типа. Параметр не может быть пустым. Имя отправителя обязательно должно быть одобрено в личном кабинете на платформе. |
| validity_period | Время жизни смс в минутах - максимальное время, в течение которого сообщение должно быть доставлено на телефон. Если в течение этого времени доставка не возможна (например абонент не в зоне действия сети или телефонный аппарат абонента выключен), то сообщение доставлено не будет и получит статус "просрочено". Внимание, данная функция может не работает для некоторых направлений, например для CDMA телефонов. (необязательный параметр, значение по умолчанию: 1440 минут (24 часа)). |
Пример блока "type": "sms" в отправляемом JSON запросе (развернуть)...
{
"auth": {
"user": "XXXXX",
"pass": "PASSWORD"
},
"number": "79XXXXXXXXX",
"stages": [
...
{
"type": "sms",
"payload": {
"text": "Текст Вашего сообщения",
"sender": "SENDERNAME",
"validity_period": 1440
}
}
]
}