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==

Подключение услуги

Предупреждение

Для подключения услуги необходимо предоставить следующую информацию Вашему персональному менеджеру:

  • Название и адрес группы ВКонтакте
  • Описание Вашей компании и вида ее деятельности
  • Ссылку на Ваш сайт или мобильное приложение.
  • Шаблоны которые будут использоваться для отправки сообщений.

Используемые типы данных

Тип данных Описание
Long Положительные числа больше нуля
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://vk.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 Число от 30 до 86400
Время жизни Viber-сообщения
в секундах
Да
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
Описание полей объекта 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-сообщения

Получение статуса сообщения

(/status/vk)

Платформа Devino возвращает статус доставки ранее отправленного VK-сообщения, messageId которого был ранее передан в теле GET-запроса:

https://vk.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 (если есть) Да