Перейти к содержанию

VK.COM

Отправка

Для отправки VK-сообщения необходимо:

  • Передать шаблон сообщений отправки вашему менеджеру или в техническую поддержку.
  • Получить ID шаблона (для параметра templateId).
  • Вызвать POST /vk/messages, передавая в теле запроса параметры сообщения с указанием данных авторизации в заголовке.

Внимание

Пожалуйста, учтите следующие ограничения на отправку:
○ Не более 50 уведомлений в секунду для одной группы в VK.
○ Не более 5 уведомлений в сутки для одного пользователя от одной группы в VK.

Параметры запроса

Параметр Тип данных Описание
callbackData
(optional)
object

Данные, которые будут указаны в коллбэке со статусом сообщения.

Любой массив вида "key":
{ "key1": "value1", "key2": "value2" }

delivery_policy
(optional)
string

Возможные значения: any, mobile_device_required, verified_phone_number

По умолчанию any.

Если указано mobile_device_required, то доставка производится только в случае наличия у пользователя мобильного приложения и его использования в течение последних 7 дней. Доставка при этом производится во все имеющиеся устройства, а не только мобильные.

Если указано verified_phone_number, то доставка производится только тем пользователям, чей номер телефона дополнительно проверен на актуальность.

phone string Номер телефона в международном формате, согласно стандарту E.164.
routes array

Cписок возможных каналов доставки через запятую
(пример: [ VK, OK ]).

VK - доставка от имени официальной группы VK.
OK - доставка от имени официальной группы в Одноклассники.
По умолчанию VK.

Доставка производится до первого получения уведомления на физическое устройство. При указании нескольких каналов доставки в итоге использован и тарифицирован будет только один из каналов.

Последовательность и логика выбора маршрутов из данного списка конфигурируется при подключении к системе. Если параметр не задан, по умолчанию используются все возможные способы доставки.

Доставка будет происходить только в том случае, если в шаблоне будет указана группа в соответствующей социальной сети. Например в шаблоне может быть указана только группа VK, тогда доставка в Одноклассники по данному шаблону осуществляться не будет.

service string Согласованное имя отправителя в VK.
status_url
(optional)
string

URL, на который система будет отправлять коллбэки при изменении статуса сообщения.

Любой валидный URL со схемой HTTP или HTTPS.

templateId
(optional)
integer ID шаблона сообщения в Devino.
tmpl string Название шаблона сообщения. Далее сообщение формируется через параметр tmpl_data.
tmpl_data object

JSON-объект, где ключи - имена переменных в шаблоне.

Например, для шаблона:
Вам доставлена посылка по адресу { address }. Код получения - { code }, - параметр tmpl_data будет: { "address": "ул. Ленина, д. 6", "code": "485372" }.

ttl
(optional)
integer

Срок жизни сообщения в секундах.

Минимальное значение: 60
Максимальное значение: 86400, 1 день
По умолчанию: 86400

Если сообщение не было доставлено за время ttl, оно не будет доставлено и тарифицировано.

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

[
  {
    "delivery_policy": "ANY",
    "phone": "79999999999",
    "routes": [
      "VK", "OK"
    ],
    "service": "Group_name",
    "status_url": "http://your.website.com/",
    "templateId": 4,
    "tmpl": "base_template",
    "tmpl_data": {
      "name": "Anna",
      "pizza": "Margarita",
    },
    "ttl": 60
  }
]

Параметры ответа

Параметр Тип данных Описание
code string

Указывает на результат обработки сообщения.

1. OK - успешно обработано.
2. REJECTED - произошла ошибка во время обработки запроса.

reasons array Массив ошибок, произошедших во время обработки сообщения. Указывается только при "code": "REJECTED".
reasons.key string Код ошибки.
reasons.ref string Ссылка на параметр, в котором произошла ошибка.
reasons.defaultMessage string Сообщение с описанием ошибки.
result array Массив с данными сообщения. Указывается только при "code": "OK".
result.id string ID сообщения.
result.validationCode string Код результата обработки сообщения.

Примеры ответов

{
  "code": "ok",
  "description": "",
  "result": [
    {
      "id": 3691204444204621000,
      "validationCode": "ok"
    }
  ]
}
{
  "result": [
    {
      "code": "REJECTED",
      "reasons": [
        {
          "key": "userip.invalid.format",
          "ref": "validUserIp",
          "defaultMessage": "#userip.invalid.format;"
        },
        {
          "key": "validity.size.invalid",
          "ref": "validity",
          "defaultMessage": "must be greater than or equal to 60"
        }
      ]
    }
  ]
}

Входящие сообщения

Как подключить

Для получения входящих VK-сообщений от пользователей обратитесь к менеджеру компании или в техническую поддержку. Также будет необходимо сообщить URL веб-сервера для обработки входящих сообщений.

Параметры

Параметр Тип данных Описание
event_id string ID события отправки сообщения.
group_id string ID сообщества, в котором произошло событие.
object IncomingMessageObject Объект с параметрами клиента и входящего сообщения.
type string Тип события.
v string Версия API, для которой сформировано событие.

IncomingMessageObject

Параметр Тип данных Описание
client_info ObjectClientInfo Объект с параметрами клиента.
message ObjectMessage Объект с параметрами сообщения.

Важно

Параметр message_tag во входящем сообщении будет соответствовать ID отправленного сообщения в Devino. Данный ID возвращается в ответе на запрос POST /vk/messages, в параметре result.id.

Пример

    {
        "group_id": 213243638,
        "type": "message_new",
        "event_id": "07c0da23123148715ab13e97823adc1bb0eadcf9",
        "v": "5.131",
        "object": {
            "message": {
                "id": 1,
                "date": 1657543344,
                "peer_id": 37119444,
                "from_id": 666666,
                "text": "text",
                "random_id": 123,
                "ref": "ref",
                "ref_source": "ref_source",
                "attachments": [
                    {
                        "type": "photo",
                        "photo": {
                            "id": 1,
                            "album_id": 2,
                            "owner_id": 3,
                            "user_id": 4,
                            "text": "phooto_text",
                            "width": 100,
                            "height": 100
                        }
                    }
                ],
                "important": true,
                "out": 0,
                "conversation_message_id": 1,
                "fwd_messages": [],
                "is_hidden": false,
                "message_tag": "3690837110063289472"
            },
            "client_info": {
                "button_actions": [
                    "text",
                    "vkpay",
                    "open_app",
                    "location",
                    "open_link",
                    "callback",
                    "intent_subscribe",
                    "intent_unsubscribe"
                ],
                "keyboard": true,
                "inline_keyboard": true,
                "carousel": true,
                "lang_id": 0
            }
        }
    }

Коллбэки

Как подключить

Для настройки коллбэков со статусами сообщений необходимо обратиться к менеджеру компании или в техническую поддержку.

Возможные статусы сообщений

Статус Описание
SENT Отправлен запрос на доставку сообщения.
DELIVERED Сообщение доставлено.
UNDELIVERABLE Сообщение не может быть доставлено, так как пользователя не существует в системе поставщика, либо же пользователь запретил прием сообщений от данного отправителя.
EXPIRED Уведомление не доставлено, так как вышло время ttl на доставку до устройства пользователя.
REJECTED Превышен лимит отправки сообщений.
SEEN Сообщение было прочитано только что. Данный статус не придет, если сообщение было прочитано после истечения ttl + 24 часа (это не значит, что сообщение будет удалено).
UNKNOWN Неизвестная ошибка.