Протокол интеграции HTTP(s) (POST) для отправки уведомлений в VK
ВНИМАНИЕ
Для использования данного вида интеграции Вам необходимо зарегистрироваться на серверной платформе Stream Telecom, либо зарегистрироваться через менеджера компании. Отправитель VK/OK регистрируется путем подачи заявки менеджерам нашей компании.
Пароль для интеграции задается в настройках пользователя во вкладке Настройки API.
Общие положения
Серверная платформа Stream-Telecom и клиент компании (далее ЗАКАЗЧИК) обмениваются HTTPS URL- encoded запросами, используя форматы передач данных JSON, параметры запроса включаются в текст запроса в кодировке UTF-8. Обмен данными построен по схеме запрос/ответ с использованием метода POST и не требует постоянного TCP/IP соединения.
Для отправки сообщений VK, требуется предварительная регистрация группы и шаблонов сообщенийОтправлять сообщения VK можно в следующем виде:
- Текст
- Текст с изображением
Точка доступа
Запросы ЗАКАЗЧИКА должны передаваться на сервер ИСПОЛНИТЕЛЯ по URL: http://gateway.api.sc/rest/Send/SendIM/VKNotify/
Функции
Пример простого запроса:
{
"login":"LOGIN",
"pass":"PASSWORD",
"service":"SERVICE_NAME",
"id_tmpl":"8",
"tmpl_data":{"username": "Alexey","balance":"100 000.00"},
"ttl":"60",
"phones":{
"1":{"phone":"79999999998"}
}
}
Ответ
{"1":{"id":218}}
Пример запроса пакетной отправки:
{
"login":"LOGIN",
"pass":"PASSWORD",
"service":"SERVICE_NAME",
"phones":{
"1":{"phone":"79999999999","id_tmpl":"8","tmpl_data":{"username": "Alexey","balance":"100 000.00"},"ttl":"600"},
"2":{"phone":"79999999998","id_tmpl":"8","tmpl_data":{"username": "Alexander","balance":"1 000.00"},"ttl":"600"}
}
}
Ответ
{"1":{"id":219},"2":{"id":220}}
Пример смешанного запроса:
{
"login":"LOGIN",
"pass":"PASSWORD",
"service":"SERVICE_NAME",
"id_tmpl":"8",
"tmpl_data":{"username": "Alex","balance":"1000"},
"ttl":"60",
"phones":{
"1":{"phone":"79999999998","id_tmpl":"8","tmpl_data":{"username": "Alexei","balance":"50.2"}},
"10":{"phone":"79999999999","ttl":"600"},
"100":{"phone":"79999999997","id_tmpl":"8","tmpl_data":{"username": "Evgeniy","balance":"100"}}
}
}
Ответ
{"1":{"id":59},"10":{"id":60},"100":{"id":61}}
Название |
Обязательное поле |
Тип данных |
Описание |
login |
Да |
String |
Логин от учетной записи Stream Telecom |
pass |
Да |
String |
Пароль для api (задается в личном кабинете во вкладке Настройка > Безопасность) |
service |
Да |
String |
Идентификатор группы ВКонтакте (присваивается в рамках заявки) |
id_tmpl |
Да |
String |
Идентификатор шаблона |
tmpl_data |
Да |
String |
JSON объект, где ключи имена переменных в шаблоне Пример: Шаблон: Здравствуй #username#. На Ваш личный кошелек было зачислено #balance# виртуальных монет. "tmpl_data": {"username":"Петр","balance":"100"} |
text |
Нет |
String |
Текст сообщения в кодировке UTF8. (перенос строки '\n'). |
ttl |
Нет |
Integer |
время жизни сообщения в секундах (по умолчанию 7200) |
phones |
Да |
Integer |
Список номеров телефонов получателей |
Параметр |
Описание |
id |
Идентификатор сообщения |
Данный метод позволяет отправить смс, в случае недоставки сообщения VK.
Пример запроса для всей рассылки:
{
"login":"LOGIN",
"pass":"PASSWORD",
"service":" SERVICE_NAME",
"id_tmpl":"8",
"tmpl_data":{"username": "Alex","balance":"1000"},
"ttl":"600",
"extra_param":{
"viber":{"sourceAddressIM":"TESTSENDER","textIM":"Test message","validityPeriod":"60"},
"sms":{"sourceAddressSMS":"TESTSENDER","textSMS":"Test message"}
},
"phones":{
"1":{"phone":"79999999998"}
}
}
Название |
Обязательное поле |
Тип данных |
Описание |
login |
Да |
String |
Логин от учетной записи Stream Telecom |
pass |
Да |
String |
Пароль для api (задается в личном кабинете во вкладке Настройка > Безопасность) |
service |
Да |
String |
Идентификатор группы ВКонтакте (присваивается в рамках заявки) |
id_tmpl |
Да |
String |
Идентификатор шаблона |
tmpl_data |
Да |
String |
JSON объект, где ключи имена переменных в шаблоне Пример: Шаблон: Здравствуй #username#. На Ваш личный кошелек было зачислено # balance# виртуальных монет. "tmpl_data": {"username":"Петр","balance":"100"} |
extra_param |
Нет |
String |
Дополнительные данные, которые вводятся для отправки viber или смс в случае недоставки сообщения ВКонтакте |
sourceAddressIM |
Нет |
String |
Имя отправителя для сообщения Viber |
textIM |
Нет |
String |
Текст сообщения Viber |
validityPeriod |
Нет |
Integer |
Срок жизни сообщения |
sourceAddressSMS |
Нет |
String |
Имя отправителя для отправки смс |
testSMS |
Нет |
String |
Текст смс |
ttl |
Нет |
Integer |
время жизни сообщения в секундах (по умолчанию 7200) |
phones |
Да |
Integer |
Список номеров телефонов получателей |
Ответ:
{"1": {"id": 174}}
Параметр |
Описание |
id |
Идентификатор сообщения |
Пример запроса для выделенных номеров:
{
"login":"LOGIN",
"pass":"PASSWORD",
"service":" SERVICE_NAME",
"id_tmpl":"8",
"tmpl_data":{"username": "Alex","balance":"1000"},
"ttl":"600",
"phones":{
"1":{"extra_param":{
"viber":{"sourceAddressIM":" TESTSENDER ","textIM":" Test message ","validityPeriod":"60"},
"sms":{"sourceAddressSMS":" TESTSENDER ","textSMS":" Test message "}
},"phone":"79999999998"}
"10":{"extra_param":{
"sms":{"sourceAddressSMS":" TESTSENDER ","textSMS":" Test message "}
},"phone":"79999999999"}
}
}
Название |
Обязательное поле |
Тип данных |
Описание |
login |
Да |
String |
Логин от учетной записи Stream Telecom |
pass |
Да |
String |
Пароль для api (задается в личном кабинете во вкладке Настройка > Безопасность) |
service |
Да |
String |
Идентификатор группы ВКонтакте (присваивается в рамках заявки) |
id_tmpl |
Да |
String |
Идентификатор шаблона |
tmpl_data |
Да |
String |
JSON объект, где ключи имена переменных в шаблоне Пример: Шаблон: Здравствуй #username#. На Ваш личный кошелек было зачислено # balance# виртуальных монет. "tmpl_data": {"username":"Петр","balance":"100"} |
extra_param |
Нет |
String |
Дополнительные данные, которые вводятся для отправки viber или смс в случае недоставки сообщения ВКонтакте |
sourceAddressIM |
Нет |
String |
Имя отправителя для сообщения Viber |
textIM |
Нет |
String |
Текст сообщения Viber |
validityPeriod |
Нет |
Integer |
Срок жизни сообщения |
sourceAddressSMS |
Нет |
String |
Имя отправителя для отправки смс |
testSMS |
Нет |
String |
Текст смс |
ttl |
Нет |
Integer |
время жизни сообщения в секундах (по умолчанию 7200) |
phones |
Да |
Integer |
Список номеров телефонов получателей |
Ответ:
{"1": {"id": 175}}
Параметр |
Описание |
id |
Идентификатор сообщения |
Пример запроса:
{
"login":"LOGIN",
"pass":"PASSWORD",
"action":"get_service"
}
Название |
Обязательное поле |
Тип данных |
Описание |
login |
Да |
String |
Логин от учетной записи Stream Telecom |
pass |
Да |
String |
Пароль для api (задается в личном кабинете во вкладке Настройка > Безопасность) |
action |
Да |
String |
Совершаемое действие (в данном случае получение списка сервисов) |
Ответ
[{"service": "test_test","group_url": "https://vk.com/test_test"},
{"service": "TEST","group_url": "https://vk.com/TEST"}]
Параметр |
Описание |
service |
Идентификатор группы ВКонтакте (присваивается в рамках заявки) |
group_url |
ULR группы Вконтакте |
Пример запроса:
{
"login":"LOGIN",
"pass":"PASSWORD",
"service":"test_test",
"action":"get_tmpl"
}
Название |
Обязательное поле |
Тип данных |
Описание |
login |
Да |
String |
Логин от учетной записи Stream Telecom |
pass |
Да |
String |
Пароль для api (задается в личном кабинете во вкладке Настройка > Безопасность) |
service |
Да |
String |
Идентификатор группы ВКонтакте (присваивается в рамках заявки), с которого запрашиваются шаблоны |
action |
Да |
String |
Совершаемое действие (в данном случае получение списка шаблонов) |
Ответ
[{"id_tmpl": "1","tmpl": "TEST TEMPLATE! Good day #username#"},
{"id_tmpl": "2","tmpl": "Test Tamplate! Привет #username#. Твой баланс: #balance#"}]
Параметр |
Описание |
id_tmpl |
Идентификатор шаблона |
tmpl |
Текст шаблона |
Пример запроса:
{
"login":"LOGIN",
"pass":"PASSWORD",
"action":"get_status",
"id":"1,139,138,137,136,175"
}
Название |
Обязательное поле |
Тип данных |
Описание |
login |
Да |
String |
Логин от учетной записи Stream Telecom |
pass |
Да |
String |
Пароль для api (задается в личном кабинете во вкладке Настройка > Безопасность) |
action |
Да |
String |
Совершаемое действие (в данном случае получение списка шаблонов) |
id |
Да |
String |
Идентификатор сообщения |
Ответ:
{
"1": {"vk": {"status": null,"status_time": null}},
"136": {"vk": {"status": "READ","status_time": "2018-06-27 16:36:30"}},
"137": {"vk": {"status": "DELIVERED","status_time": "2018-06-27 18:00:06"}},
"138": {"vk": {"status": "EXPIRED","status_time": "2018-06-28 08:39:10"}},
"139": {"vk": {"status": "UNSUPPORTED","status_time": "2018-07-02 18:37:46"},"viber": {"status": "failed","status_time": "2018-07-02 19:00:12"}}
"175": {"vk": {"status": "UNSUPPORTED","status_time": "2018-06-29 17:29:21"},"sms": {"status": "deliver","status_time": "2018-06-29 17:29:24"}}
}
Параметр |
Описание |
status |
Статус сообщения |
vk: {status} |
Статус сообщения ВКонтакте |
viber: {status} |
Статус сообщения Viber |
sms: {status} |
Статус сообщения смс |
status_time |
Время получения статуса |
Статус VK |
Описание |
DELIVERED |
Доставлено |
UNSUPPORTED |
Получателя не существует |
EXPIRED |
Истекло время жизни сообщения |
RATELIMIT |
Превышен лимит сообщений для получателя (не более 5 в
сутки)
|
READ |
Прочитано (статус DELIVERED не изменится на READ, если получатель прочитал сообщение после истечения
времени жизни сообщения)
|
BLOCKED_BY_USER |
Получатель запретил прием сообщений от данного отправителя |
Статус Viber |
Описание |
delivered |
Доставлено |
undelivered |
Не доставлено |
sent |
Отправлено |
read |
Прочитано |
Статус смс |
Описание |
deliver |
Доставлено |
not_deliver |
Не доставлено |
expired |
Истекло время жизни сообщения |
send |
Отправлено |
Ошибка |
Описание |
Missing template parameter |
Один из параметров в шаблоне не указан |
Template does not
match text
|
Текст не соответствует шаблону (в случае, если указан текст) |
The text can't be
longer than 2048 characters
|
В тексте более
2048 символов
|
Template not registered |
Шаблон не зарегистрирован |
Invalid service VKNotify |
Сервис отсутствует / некорректный сервис |
Incorrect phone number |
Неверный номер телефона |
Direction is closed |
Отсутствуют средства на логине |
Data error |
Данные некорректные |
Основные положения
Для подключения возможности отправки сообщений VK, пользователю сначала требуется зарегистрировать официальную группу ВКонтакте.
Для этого, клиент присылает нам доверительное письмо, в котором дает согласие на отправку уведомлений VK от нашего сервиса, указывая ссылку на свою группу ВКонтакте.
Ссылка на шаблон доверительного письма
К данному письму нужно приложить текстовый или табличный файл со списком шаблонов с обязательным выделением динамических переменных, обрамленных символом “#”. (название переменных может быть произвольным, например: #name#, #phone#, #order#, #price# и т.д.). Если регистрируются шаблоны с картинкой, то изображение должно иметь формат .jpg, .png или .gif.
Примеры шаблонов:
- Добрый день #name#! Баланс Вашего аккаунта #account_name#: #balance#.
- Заказ номер #order# отправлен по адресу #address#.
- Заявка #ticket# зарегистрирована. Спасибо за обращение!
Ограничений на количество переменных и их длину нет, однако следует иметь ввиду, что максимальная длина получаемого сообщения ВКонтакте не должна превышать 2048 символов.
Доверительное письмо и список шаблонов отправляются на support@stream-telecom.ru.
После регистрации сервиса, в ответном письме отправляется уникальный идентификатор группы ВКонтакте, который клиент должен использовать в качестве отправителя.