VK API¶

Общие сведения¶

Сервис позволяет отправлять сообщения VK через платформу Devino Telecom с возможностью переотправки по Viber и SMS в случае недоcтавки, а также для получения отчетов о статусах доставки сообщений.

API поддерживает базовую авторизацию через заголовок Authorization.

В заголовке запроса необходимо передать логин и пароль из личного кабинета в формате login:password в base64 кодировке, например:

Authorization: Basic dGVzdGVyOjExMTExMQ==

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

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

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

Внимание

На стороне VK имеются ограничения на отправку:

не более 50 уведомлений в секунду для одного service (для одной группы в VK)
не более 5 уведомлений в сутки для одного пользователя от одного service (одной группы в VK)

Отправка сообщения¶

https://im.devinotele.com/send/vk

В одном запросе может быть информация об отправке только одного сообщения.

Параметры запроса отправки сообщения¶

Параметры объекта VK¶

Поле	Тип данных	Допустимые значения	Описание
subject обязательный	string	Строка от 1 до 11 символов	Имя отправителя
priority обязательный	string	Варианты: 1. `low` 2. `medium` 2. `high` 4. `realtime`	Приоритет сообщения
routes обязательный	array[string]	Варианты: 1. `vk` 2. `ok` 2. `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	Целое число	ID шаблона сообщения
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` 2. `high` 4. `realtime`	Приоритет сообщения
validityPeriod обязательный	Long	Целое число от 15 до 86400	Время жизни сообщения в секундах
comment	string	Произвольный текстовый комментарий
type обязательный	string	`viber`	Тип отправляемого сообщения. Определяет канал, который используется для доставки сообщения на мобильный телефон получателя
contentType обязательный	string	`text` – текстовое сообщение `image` – изображение `button` – гиперссылка в виде кнопки	Тип содержимого сообщения.
dstAddress обязательный	string	Номер телефона в соответствии со стандартом E.164, возможен `+` в начале	Номер телефона получателя сообщения
text обязательный	string		Текст Viber-сообщения
caption	string	Зависит от значения contentType	Текст кнопки
action	string	Зависит от значения contentType	URL для перехода при нажатии на кнопку
imageUrl	string	Зависит от значения contentType	URL изображения, которое размещено на сервере клиента

Параметры объекта SMS¶

Поле	Тип данных	Допустимые значения	Описание
srcAddress обязательный	string		Имя отправителя SMS-сообщения
text обязательный	string		Текст сообщения
validityPeriod обязательный	Long	Число от 60 до 86400	Время жизни сообщения в секундах
dstAddress обязательный	string	Номер телефона в соответствии со стандартом E.164, возможен `+` в начале	Номер телефона получателя сообщения

Пример запроса отправки сообщения¶

{
  "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"
  }
}

Параметры ответа на запрос отправки сообщения¶

Поле	Тип данных	Допустимые значения	Описание
code	string	Возможные значения перечислены в таблице кодов	Код ответа на запрос отправки сообщения
description	string	Возможные значения перечислены в таблице кодов	Описание ошибки отправки сообщения
result	Object		Информация о коде валидации и ID сообщения

Параметры объекта result¶

Поле	Тип данных	Допустимые значения	Описание
code	string	Возможные значения перечислены в таблице кодов валидации	Код валидации сообщения
messageId	Long		Уникальный ID сообщения

Пример ответа на запрос отправки сообщения¶

{
  "code": "ok",
  "description": "",
  "result": {
    "code": "ok",
    "messageId": 3222269333010907000
  }
}

Коды ответа на запрос отправки сообщения¶

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	Недостаточно средств на лицевом счете

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

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

Параметры запроса статусов¶

Поле	Тип данных	Описание
message обязательный	Long	ID сообщения

Пример запроса¶

https:/im.devinotele.com/status/vk?message=<ID Вашего сообщения>

Параметры ответа на запрос статусов¶

Поле	Тип данных	Допустимые значения	Описание
code	string	Возможные значения перечислены в таблице кодов ответа	Код ответа на запрос отправки сообщения
description	string	Возможные значения перечислены в таблице кодов ответа	Описание ошибки обработки запроса отправки сообщения
result	Object		Каждому объекту из массива `messages` запроса соответствует объект в массиве `result` ответа

Параметры объекта result¶

Поле	Тип данных	Допустимые значения	Описание
providerId	Long		ID сообщения
code	string	Возможные значения перечислены в таблице кодов валидации ID сообщений	Код валидации ID
status	string	`enqueued` – сообщение добавлено в очередь на отправку `sent` – сообщение отправлено `delivered` – сообщение доставлено `undelivered` – сообщение отправлено, но не доставлено `failed` – сообщение не доставлено в результате сбоя `vp_expired` – сообщение не доставлено в течение validityPeriod `read` – сообщение просмотрено получателем	Статус доставки сообщения VK
statusAt	DateTime		Время обновления статуса доставки сообщения VK
error	string		Информация об ошибке, произошедшей при отправке сообщения
viberStatus	Object		Информация о статусе Viber-сообщения
smsStates	Object		Статусы доставки SMS-сообщения

Параметры объекта viberStatus¶

Поле	Тип данных	Допустимые значения	Описание
id	Long		Уникальный ID сообщения на платформе
statusAt	timestamp		Дата и время получения статуса
Status	string	`enqueued` – сообщение находится в очереди на отправку `sent` – сообщение отправлено получателю `delivered` – сообщение доставлено получателю `read` – сообщение просмотрено получателем `visited` - получатель перешел по ссылке в сообщении `undelivered` – сообщение отправлено, но не доставлено получателю `failed` – сообщение не было отправлено в результате сбоя `cancelled` – отправка сообщения отменена `vp_expired` – сообщение просрочено. финальный статус не получен в рамках заданного validityPeriod	Код статуса доставки Viber-сообщения
Code	string	`user-blocked` – получатель заблокирован `not-viber-user` – получатель не является пользователем Viber	Причина, по которой сообщение не было доставлено получателю при `status=undelivered`

Параметры объекта smsStates¶

Поле	Тип данных	Допустимые значения	Описание
id	Long		ID SMS-сообщения
status	string	`enqueued` – сообщение находится в очереди на отправку `sent` – сообщение отправлено получателю `delivered` – сообщение доставлено получателю `undelivered` – сообщение отправлено, но не доставлено получателю	Статус SMS-сообщения

Пример ответа¶

{
  "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	description
ok
validation_error	`message_not_specified`
system_error	Описание внутренней ошибки сервера

Коды валидации ID сообщений¶

code	description
ok
unknown_message_id	Неизвестный ID сообщения

Коды возврата обработки Viber-сообщения в рамках запроса (code)¶

Код	Описание
ok	Сообщение принято на отправку
error-system	Системная ошибка
error-instant-message-client-id-not-unique	Клиентский ID сообщения не уникален в рамках взаимодействия между клиентом и провайдером
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	Неправильный формат ID провайдера
error-instant-message-provider-id-duplicate	ID провайдера исходящего сообщения неуникален в рамках запроса проверки статуса
error-instant-message-provider-id-unknown	Исходящее сообщение с данным ID провайдера не найдено на платформе провайдера
error-resend-sms-error	Указаны поля для переотправки SMS, но переотправка не включена
error-resend-sms-validity-period-error	Неверное время жизни для SMS

Получение статуса сообщения с помощью Callback-запросов¶

Для получения статуса сообщения могут использоваться callback-запросы. В таком случае платформа Devino Telecom будет отправлять POST-запрос на выбранный URL каждый раз, когда у отправленного вами сообщения будет меняться статус.

Запрос считается доставленным, если в ответ на него был получен статус HTTP 200. В противном случае будут совершаться повторные попытки доставки в течение 24 часов. По истечению этого срока статус сообщения можно будет получить только с помощью GET-запроса, описанного выше.

Важно

Обратите внимание, что информация о переотправке по SMS в callback-запросе не предоставляется.

Внимание

Для получения callback-запросов от сервиса необходимо передать менеджеру компании либо в техническую поддержку информацию об URL, на который будут отправляться запросы.

Параметры callback-запроса¶

Поле	Тип данных	Описание
id	Long	Уникальный ID сообщения в Devino Telecom
status	string	Статус доставки сообщения VK
time	DateTime	Время получения статуса по часовому поясу UTC+3
error	string	Ошибка доставки сообщения VK

Пример callback-запроса¶

[
  {
    "messageId":1343343,
    "status": "DELIVERED",
    "receivedAt": "2017-05-31 14:51:12",
    "error":"Доставлено"
  }
]