Протокол интеграции HTTP(s) (POST) для отправки уведомлений в VK

Для использования данного вида интеграции, Вам необходимо зарегистрироваться на серверной платформе STREAM TELECOM по адресу https://web.szk-info.ru.

Варианты:

1) Регистрация в личном кабинете

2) Регистрация через менеджера компании Stream Telecom

Общие положения

Серверная платформа Stream-Telecom и клиент компании (далее ЗАКАЗЧИК) обмениваются HTTPS URL- encoded запросами, используя форматы передач данных JSON, параметры запроса включаются в текст запроса в кодировке UTF-8. Обмен данными построен по схеме запрос/ответ с использованием метода POST и не требует постоянного TCP/IP соединения.

Пароль для интеграции задается отдельно через вкладку Настройка > Безопасность.

Точка доступа

Запросы ЗАКАЗЧИКА должны передаваться на сервер ИСПОЛНИТЕЛЯ по URL: http://gateway.api.sc/rest/Send/SendIM/VKNotify/

(ssl: https://gateway.api.sc/rest/Send/SendIM/VKNotify/)

stream_telecom_integrationl_sms_vk.pdf stream_telecom_vk_registration_guide.pdf

Функции

Пример простого запроса:

{

"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# и т.д.)

Примеры шаблонов:

  • Добрый день #name#! Баланс Вашего аккаунта #account_name#: #balance#.
  • Заказ номер #order# отправлен по адресу #address#.
  • Заявка #ticket# зарегистрирована. Спасибо за обращение!

Ограничений на количество переменных и их длину нет, однако следует иметь ввиду, что максимальная длина получаемого сообщения ВКонтакте не должна превышать 2048 символов.

Доверительное письмо и список шаблонов отправляются на support@stream-telecom.ru.

После регистрации сервиса, в ответном письме отправляется уникальный идентификатор группы ВКонтакте, который клиент должен использовать в качестве отправителя.

* Все функции могут быть доработаны на усмотрение разработчиков, внедряющих службы SMS в систему 1С.