VK API¶
Общие сведения¶
Сервис предоставляет REST API для отправки VK-сообщений через платформу. Devino Telecom с возможностью переотправки по Viber и SMS в случае недоcтавки, а также для получения отчетов о статусах доставки сообщений.
Работа с API осуществляется с использованием протокола HTTP.
Тела запроса клиента и ответа сервера представлены в формате JSON. Данные должны быть в кодировке UTF-8.
API поддерживает базовую авторизацию через заголовок Authorization (https://en.wikipedia.org/wiki/Basic_access_authentication).
В заголовке запроса необходимо передать логин и пароль из Личного Кабинета в формате login:password в base64 кодировке, например:
Authorization: Basic dGVzdGVyOjExMTExMQ==
Подключение услуги¶
Предупреждение
Для подключения услуги необходимо предоставить следующую информацию Вашему персональному менеджеру:
- Название и адрес группы ВКонтакте
- Описание Вашей компании и вида ее деятельности
- Ссылку на Ваш сайт или мобильное приложение.
- Шаблоны которые будут использоваться для отправки сообщений.
Используемые типы данных¶
| Тип данных | Описание |
|---|---|
| Integer | Положительные числа больше нуля |
| DateTime | Значение, обозначающее дату и время, представляются в пакетах в формате «yyyy-MMdd hh:mm:ss», например, 1999-05-31 13:20:00 |
| Address | Адрес абонента. Номер мобильного телефона абонента в международном формате (в формате E.164). Например, 79031112233, для России или 491791112233 для Германии |
| String | Строка символов в формате UTF-8 |
| Object | Объект (включает в себя несколько полей других типов) |
Ограничения и допустимые значения описаны далее в разделе описания пакетов протокола.
Предупреждение
На стороне VK имеются ограничения на отпарвку:
- не более 50 уведомлений в секунду для одного service (для одной группы в VK)
- не более 5 уведомлений в сутки для одного пользователя от одного service (одной группы в VK)
Методы работы с API¶
Отправка сообщения¶
(/send/vk)
Платформа Devino инициирует отправку VK-сообщения абоненту в соответствии с данными,переданными в теле POST-запроса:
https://im.devinotele.com/send/vk
В одном запросе может быть информация об отправке только одного сообщения.
Пример тела запроса отправки сообщения
{
"vk":{
"subject":"TEST",
"priority":"high",
"routes":[
"vk"
],
"validityPeriod":180,
"phone":"79999999999",
"templateId":"123456",
"templateData":{
"param1":"value1",
"param2":"value2"
}
},
"viber":{
"subject":"TEST",
"priority":"high",
"validityPeriodSec":30,
"type":"viber",
"comment":"comment",
"contentType":"button",
"text":"text",
"caption":"caption",
"action":"http://company.com/resource",
"imageUrl":"http://company.com/image.jpg",
"dstAddress":"79999999999"
},
"sms":{
"srcAddress":"TESTSMS",
"text":"тест сообщения",
"validityPeriod":60,
"dstAddress":"79999999999"
}
}
Описание полей тела запроса отправки сообщения¶
| Поле | Тип данных | Допустимые занчения | Описание | Обязательное поле |
|---|---|---|---|---|
| Описание полей объекта VK | ||||
| subject | String | Строка от 1 до 11 символов | Адрес отправителя | Да |
| priority | String | Варианты: 1) «low» 2) «medium» 3) «high» 4) «realtime» | Приоритет сообщения | Да |
| routes | массив String | Варианты: 1) «vk» 2) «ok» 3) «ok»,»vk» 4) «vk»,»ok» | Массив маршрутов VK в порядке использования, пример «routes»:[«ok»,»vk»] | Да |
| validityPeriod | Long | Целое число от 15 до 86400 | Время жизни сообщения в секундах | Да |
| deliveryPolicy | String | Варианты: 1) «any» 2) «mobile_device_required» | По умолчанию any. Если указано mobile_device_required, то доставка производитсятолько в случае наличия у пользователямобильного приложения и его использования в течение последних 7 дней. Доставка при этом производится во все имеющиеся устройства, а не только мобильные. в секундах. | Да |
| phone | String | Номер телефона в соответствии со стандартом E.164, возможен + в начале | Номер телефона получателя сообщения | Да |
| templateId | Long | Целое число | Идентификатор шаблона | Да |
| templateData | Object | Значения параметров шаблона - например если шаблон «Уважаемый #abonent# с #startTime# по #endTime# сервис будет недоступен», то пример templateData может быть такой: «templateData»: { «abonent»: «Иванов А.Б.», «startTime»: «10.01.2017 15.15», «endTime»: «10.01.2017 15.30» } Шаблон должен быть согласован VK | Да | |
| Описание полей объекта Viber | ||||
| subject | String | Имя отправителя Viber-сообщения | Да | |
| priority | String | Варианты: 1) «low» 2) «medium» 3) «high» 4) «realtime» | Приоритет сообщения | Да |
| validityPeriod | Long | Целое число от 15 до 86400 | Время жизни сообщения в секундах | Да |
| comment | String | Произвольный текстовый комментарий. | Нет | |
| type | String | Тип отправляемого сообщения. Определяет канал, которые используется для доставки сообщения на мобильный телефон абонента | viber | Да |
| contentType | String | Тип содержимого сообщения. | text – текстовое сообщение image – изображение button – гиперссылка в виде кнопки | Да |
| dstAddress | String | Номер телефона в соответствии со стандартом E.164, возможен + в начале | Номер телефона получателя сообщения | Да |
| text | String | Текст viber-сообщения | Зависит от значения contentType | |
| caption | String | Текст кнопки | Зависит от значения contentType | |
| action | String | Ссылка кнопки | Зависит от значения contentType | |
| imageUrl | String | Ссылка на картинку | Зависит от значения contentType | |
| text | String | Текст viber-сообщения | Да | |
| Описание полей объекта SMS | ||||
| srcAddress | String | Имя отправителя SMS-сообщения | Да | |
| text | String | Текст SMS-сообщения | Да | |
| validityPeriod | Long | Число от 60 до 86400 | Время жизни SMS-сообщения в секундах | Да |
| dstAddress | String | Номер телефона в соответствии со стандартом E.164, возможен + в начале | Номер телефона получателя сообщения | Да |
Пример ответа на запрос отправки сообщения
{
"code": "ok",
"description": "",
"result": {
"code": "ok",
"messageId": 3222269333010907000
}
}
Описание полей тела ответа на запрос отправки сообщения¶
| Поле | Тип данных | Допустимые занчения | Описание | Обязательное поле |
|---|---|---|---|---|
| code | String | Возможные значения перечислены в таблице кодов ответа на запрос отправки сообщения | Код ответа на запрос отправки сообщения | Да |
| description | String | Возможные значения перечислены в таблице кодов ответа на запрос отправки сообщения | Описание ошибки обработки запроса отправки сообщения (если была) | Да |
| result | Object | Информация о коде валидации и ID сообщения | Да, если code=»ok» | |
| Описание полей объекта result | ||||
| code | String | Возможные значения перечислены в таблице кодов валидации сообщения | Код валидации сообщения | Да |
| messageId | Long | Уникальный идентификатор сообщения | Да, если code=»ok» | |
Коды ответа на запрос отправки сообщения¶
| code | description |
|---|---|
| ok | |
| validation_error | login_not_specified |
| validation_error | messages_not_specified |
| validation_error | invalid_json |
| queue_full | login_send_queue_overflow |
| system_error | Описание внутренней ошибки сервера |
Коды валидации сообщения¶
| code | Описание |
|---|---|
| ok | Сообщение добавлено в очередь на отправку |
| subject_not_specified | Не указан адрес отправителя |
| subject_invalid | Недопустимый адрес отправителя |
| priority_not_specified | Не указан приоритет сообщения |
| priority_invalid | Недопустимый приоритет сообщения |
| routes_not_specified | Не указаны маршруты доставки |
| routes_invalid | Недопустимый набор маршрутов доставки |
| vp_invalid | Недопустимый validityPeriod |
| phone_not_specified | Не указан номер телефона |
| phone_invalid | Недопустимый номер телефона |
| text_not_specified | Не указан текст сообщения |
| text_invalid | Недопустимый текст сообщения |
| sms_text_not_specified | Не указан текст SMS-сообщения |
| sms_subject_not_specified | Не указан номер отправителя SMS-сообщения |
| sms_validity_period_not_specified | Не указано время жизни SMS-сообщения |
| invalid_sms_validity_period | Недопустимое время жизни SMS-сообщения |
| not-enough-credits | Недостаточно средств на лицевом счете |
Получение статуса сообщения¶
(/status/vk)
Платформа Devino возвращает статус доставки ранее отправленного VK-сообщения, messageId которого был ранее передан в теле GET-запроса:
https:/im.devinotele.com/status/vk?message=<ID Вашего сообщения>
Описание параметров запроса статусов
| Поле | Тип данных | Допустимые занчения | Описание | Обязательное поле |
|---|---|---|---|---|
| message | Long | Идентификатор сообщения | Да |
Пример ответа на запрос статусов
{
"code": "ok",
"description": "",
"result": {
"providerId": 3287014702114144256,
"code": "ok",
"status": "failed",
"statusAt": "2018-07-03 16:31:40",
"smsStates": [
{
"id": 711869146186383364,
"status": "delivered"
}
],
"viberStatus": {
"id": 3287014702114144256,
"status": "undelivered",
"statusAt": "2018-07-03 16:31:41",
"code": "not-viber-user"
}
}
}
Описание полей тела ответа на запрос статусов¶
| Поле | Тип данных | Допустимые занчения | Описание | Обяз-ое поле |
|---|---|---|---|---|
| code | String | Возможные значения перечислены в таблице кодов ответа на запрос статусов | Код ответа на запрос отправки сообщения | Да |
| description | String | Возможные значения перечислены в таблице кодов ответа на запрос статусов | Описание ошибки обработки запроса запроса статусов (если была) | Да |
| result | Object | Каждому объекту из массива messages запроса соответствует объект в массиве result ответа | Да, если code=»ok | |
| Описание полей объекта result | ||||
| providerId | Long | Идентификатор сообщения | Да | |
| code | String | Возможные значения перечислены в таблице кодов валидациисообщения идентификаторов сообщений | Код валидации идентификатора | Да |
| status | String | enqueued – сообщение добавлено в очередь на отправки, sent – сообщение отправлено, delivered – сообщение доставлено, undelivered – сообщение отправлено, но не доставлено, failed – сообщение не доставлено в результате сбоя, vp_expired – сообщение не доставлено в течение validityPeriod, read – сообщение просмотрено абонентом. | Статус доставки сообщения VK | Да |
| statusAt | DateTime | Возможные значения перечислены в таблице | Время обновления статуса доставки сообщения VK | Да |
| error | String | Набор всех возможных ошибок заранее не предопределен | Информация о статусе сообщения | Нет |
| viberStatus | Object | Информация о статусе сообщения | Да, если code=»ok» | |
| smsStates | Object | Статусы доставки SMS-сообщения | Нет | |
| Описание полей объекта viberStatus | ||||
| id | Long | Уникальный идентификатор сообщения на платформе | Да | |
| statusAt | timestamp | Дата и время получения статуса | Да | |
| Status | String | enqueued – сообщение находится в очереди на отправку. sent – сообщение отправлено абоненту delivered – сообщение доставлено абоненту. read – сообщение просмотрено абонентом. visited абонент перешел по ссылке в сообщении. undelivered – сообщение отправлено, но не доставлено абоненту. failed – сообщение не было отправлено в результат сбоя. cancelled –отправка сообщения отменена. vp_expired – сообщение просрочено, финальный статус не получен в рамках заданного validity period | Код статуса доставки Viber сообщения. | Да |
| Code | String | user-blocked – абонент заблокирован not-viber-user – абонент не является пользователем Viber. | Причина, по которой сообщение не было доставлено абоненту (status=undelivered) | Нет |
| Описание полей объекта smsStates | ||||
| id | Long | Идентификатор SMS-сообщения | Да | |
| status | String | enqueued – сообщение находится в очереди на отправку, sent – сообщение отправлено абоненту, delivered – сообщение доставлено абоненту, undelivered – сообщение отправлено, но не доставлено абоненту | Статус SMS-сообщения | Да |
Коды ответа на запрос статусов¶
| code | description |
|---|---|
| ok | |
| validation_error | message_not_specified |
| system_error | Описание внутренней ошибки сервера |
Коды валидации идентификаторов сообщений¶
| code | description |
|---|---|
| ok | Известный идентификатор сообщения |
| unknown_message_id | Неизвестный идентификатор сообщения |
Коды возврата обработки viber сообщения в рамках запроса (code)
| Код | Описание |
|---|---|
| ok | исходящее сообщение успешно принято на отправку |
| error-system | системная ошибка |
| error-instant-message-client-id-not-unique | клиентский идентификатор сообщения не уникален в рамках всего взаимодействия между клиентом и провайдером. |
| error-subject-format | неправильный формат подписи |
| error-subject-unknown | указанная подпись не разрешена клиенту в конфигурации платформы провайдера |
| error-subject-not-specified | подпись не указана |
| error-address-format | неправильный формат номера абонента |
| error-address-unknown | отправка на номерную емкость, к которой относится номер абонента не разрешена клиенту в конфигурации платформы провайдера |
| error-address-not-specified | номер абонента не указан |
| error-priority-format | неправильный формат значения приоритета |
| error-comment-format | неправильный формат значения комментария |
| error-instant-message-type-format | неправильный формат типа сообщения |
| error-instant-message-type-not-specified | неправильный формат типа содержимого сообщения |
| error-content-type-format | неправильный формат содержимого сообщения |
| error-content-not-specified | содержимое сообщения не указано |
| error-validity-period-seconds-format | неправильно указано значение времени ожидания доставки |
| error-instant-message-provider-id-format | неправильный формат провайдерского идентификатора |
| error-instant-message-provider-id-duplicate | провайдерский идентификатор исходящего сообщения неуникален в рамках запроса проверки статуса |
| error-instant-message-provider-id-unknown | исходящее сообщение с данным провайдерским идентификатором не найдено на платформе провайдера |
| error-resend-sms-error | указаны поля для переотправки смс но переотправка не включена |
| error-resend-sms-validity-period-error | неверное время жизни для смс |
Получение статуса сообщения с помощью Callback-запросов¶
Для получения статуса сообщения могут использоваться callback-запросы. В таком случае Платформа Devino будет отправлять POST-запрос на выбранный Вами URL каждый раз, когда у отправленного Вами сообщения будет меняться статус. Запрос считается доставленным, если в ответ на него был получен статус HTTP(200). В противном случае будут совершаться повторные попытки доставки в течение 24 часов и по истечению этого срока статус сообщения можно будет получить только с помощью GET-запроса, описанного выше.
Предупреждение
Обратите внимание, что информация о переотправке по SMS в callback-запросе не предоставляется.
Предупреждение
Для получения callback-запросов от сервиса необходимо передать Вашему персональному менеджеру или в техническую поддержку (support@devinotele.com) информацию об URL, на который будут отправляться запросы.
Пример тела callback-запроса
[
{
"messageId":1343343,
"status": "DELIVERED",
"receivedAt": "2017-05-31 14:51:12",
"error":"Доставлено"
}
]
Описание полей запроса¶
| Поле | Тип данных | Описание | Обязательное поле |
|---|---|---|---|
| id | Long | Уникальный идентификатор сообщения в Платформе Devino | Да |
| status | String | Статус доставки сообщения VK | Да |
| time | DateTime | Время получения статуса (по Москве, UTC+3) | Да |
| error | String | Ошибка доставки сообщения VK (если есть) | Да |