VK.COM¶

Отправка¶

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

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

Внимание

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

В одном запросе можно отправить не более 1000 сообщений.

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

Параметр	Тип данных	Описание
phone	string	Номер телефона в международном формате, согласно стандарту E.164.
routes	array	Список возможных каналов доставки через запятую (пример: `[ VK, OK ]`). ○ `VK` - доставка от имени официальной группы VK. ○ `OK` - доставка от имени официальной группы в Одноклассники. По умолчанию `VK`. Доставка производится до первого получения уведомления на физическое устройство. При указании нескольких каналов доставки в итоге использован и тарифицирован будет только один из каналов. Последовательность и логика выбора маршрутов из данного списка конфигурируется при подключении к системе. Если параметр не задан, по умолчанию используются все возможные способы доставки. Доставка будет происходить только в том случае, если в шаблоне будет указана группа в соответствующей социальной сети. Например в шаблоне может быть указана только группа VK, тогда доставка в Одноклассники по данному шаблону осуществляться не будет.
service	string	Согласованное имя отправителя в VK.
tmpl	string	Название шаблона сообщения. Далее сообщение формируется через параметр `tmpl_data`.
tmplData	object	JSON-объект, где ключи - имена переменных в шаблоне. Например, для шаблона: Вам доставлена посылка по адресу `{ address }`. Код получения - `{ code }`, - параметр `tmpl_data` будет: `{ "address": "ул. Ленина, д. 6", "code": "485372" }`.
text	string	UTF-8 текст, не более 2048 символов. Если текст сообщения не соответствует ни одному шаблону, в ответ на запрос вернется ошибка. В случае использования параметров `tmpl` и `tmpl_data` данный параметр использовать не нужно. Если указаны `vk_text` или `ok_text`, они имеют больший приоритет, чем `text`.
vkText (optional)	string	Аналогично `text`, но используется только для доставки в `VK`.
okText (optional)	string	Аналогично `text`, но используется только для доставки в `OK`.
ttl (optional)	integer	Срок жизни сообщения в секундах. Минимальное значение: 60 Максимальное значение: 86400, 1 день По умолчанию: 86400 Если сообщение не было доставлено за время `ttl`, оно не будет доставлено и тарифицировано.
deliveryPolicy (optional)	string	Возможные значения: `any`, `mobile_device_required`, `verified_phone_number` По умолчанию `any`. Если указано `mobile_device_required`, то доставка производится только в случае наличия у пользователя мобильного приложения и его использования в течение последних 7 дней. Доставка при этом производится во все имеющиеся устройства, а не только мобильные. Если указано `verified_phone_number`, то доставка производится только тем пользователям, чей номер телефона дополнительно проверен на актуальность.
statusUrl (optional)	string	URL, на который система будет отправлять коллбэки при изменении статуса сообщения. Любой валидный URL со схемой `HTTP` или `HTTPS`.
callbackData (optional)	object	Данные, которые будут указаны в коллбэке со статусом сообщения. Любой массив вида `"key"`: `{ "key1": "value1", "key2": "value 2" }`

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

[
  {
    "deliveryPolicy": "ANY",
    "phone": "79999999999",
    "routes": [
      "VK", "OK"
    ],
    "service": "Group_name",
    "statusUrl": "http://your.website.com/",
    "tmpl": "base_template",
    "tmplData": {
      "name": "Anna",
      "pizza": "Margarita",
    },
    "ttl": 60
  }
]

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

Параметр	Тип данных	Описание
result	array	Результат обработки сообщения.
result.code	string	Указывает на результат обработки сообщения. 1. `OK` - успешно обработано. 2. `REJECTED` - произошла ошибка во время обработки запроса.
result.messageId	string	ID сообщения. Указывается только при `"code": "OK"`.
reasons	array	Массив ошибок, произошедших во время обработки сообщения. Указывается только при `"code": "REJECTED"`.
reasons.key	string	Код ошибки.
description	string	Сообщение с описанием ошибки.

Коды ошибок¶

Код	Описание
service.not.found	Отправка сообщений через VK недоступна.
billing.error	Ошибка оплаты.
is.spam	Сообщение помечено как спам.
too.many.messages	Превышен лимит по количеству сообщений в запросе. Один запрос может содержать не более 1000 сообщений.
login.must.be.not.null	Не указан логин пользователя.

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

OK

{
  "result": [
    {
      "code": "OK",
      "messageId": 2354676865423253
    }
  ]
}

REJECTED

{
  "result": null,
  "reasons": [
    {
      "key": "login.must.be.not.null"
    }
  ],
  "description": "Ошибка валидации: login must be not null"
}

Коллбэки¶

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

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

Возможные статусы¶

Статус	Код статуса	Описание
SENT	SENT	Отправлен запрос на доставку сообщения.
DELIVERED	DELIVERED	Сообщение доставлено.
UNDELIVERABLE	UNDELIVERABLE	Невозможно доставить сообщение.
	UNSUPPORTED	Сообщение не может быть доставлено, так как пользователя не существует в системе поставщика.
	BLOCKED_BY_USER	Пользователь запретил прием сообщений от данного отправителя.
	RATELIMIT	Превышен лимит отправки сообщений.
EXPIRED	VP_EXPIRED_AFTER_SEND	Уведомление не доставлено, так как вышло время `ttl` на доставку до устройства пользователя.
REJECTED	FAILED	Провалилась попытка доставить сообщение, ошибка со стороны поставщика.
	NOT_ENOUGH_DATA	Недостаточно данных в запросе.
	INCORRECT_SIGNATURE	Некорректная подпись запроса.
	UNSUPPORTED_NUMBER	Не поддерживается номер телефона (страна или оператор).
	NUMBER_IN_BLACK_LIST	Номер телефона получателя занесен в черный список.
	NUMBER_TYPE_NOT_ALLOWED	Номер телефона получателя виртуальный или замечен в спаме.
	ERROR	Ошибка общего характера, подробности указаны в параметре коллбэка `detailStatus`.
	NOT_ALLOWED_IP	IP адрес, с которого осуществляется запрос, не разрешен в настройках доступа.
	UNSUPPORTED_TEMPLATE	Не поддерживается шаблон сообщения.
	NOT_VALID_TEMPLATE_DATA	Неправильно сформирован параметр `tmpl_data`.
SEEN	READ	Сообщение было прочитано только что. Данный статус не придет, если сообщение было прочитано после истечения `ttl` + 24 часа (это не значит, что сообщение будет удалено).
UNKNOWN	UNKNOWN	Неизвестная ошибка.

Пример коллбэка¶

[
    {
        "messageId": "3721115754893245581",
        "eventTime": "2023-06-28 13:34:25",
        "statusInfo": {
            "status": "EXPIRED",
            "errorCode": "VP_EXPIRED_AFTER_SEND",
            "detailStatus": "EXPIRED: null"
        }
    }
]

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

Внимание

Devino.Telecom отправляет данные только по первому входящему сообщению в диалоге. Уведомления про последующие сообщения не отправляются, в связи с особенностями получения некоторых параметров от поставщика.

Подключение¶

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

Важно

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

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

Перейти в сообщество VK, для которого вы хотите получать уведомления, и выбрать раздел Управление в правом боковом меню.

VK-group

В разделе Настройки перейти во вкладку Работа с API в правом боковом меню.
Перейти во вторую вкладку Callback API и заполнить поля:
- В поле Версия API выбрать последнюю версию.
- В поле Адрес ввести https://integrationapi.net/vk/incoming.
Далее необходимо сообщить код подтверждения VK (из подсказки Строка, которую должен вернуть сервер: ... над кнопкой Подтвердить) персональному менеджеру или технической поддержке для регистрации вашего сообщества.
После того, как Devino.Telecom зарегистрирует код, который он должен отдать VK, у себя в системе, вы можете нажать Подтвердить в той же вкладке. У подтвержденного сервера рядом с полем Адрес появится зеленая иконка с галочкой.

VK-confirmation

Также нужно перейти во вторую вкладку Типы событий раздела Callback API и отметить первый чекбокс Входящее сообщение. Настройка обновится автоматически.

VK-checkbox

Параметры¶

Параметр	Тип данных	Описание
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
            }
        }
    }

Детализация¶

Для получения детальных сведений об отправленных сообщениях необходимо вызвать GET /vk-stat/detail, передавая параметры фильтров и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
limit	integer	Количество сообщений в результатах поиска.
offset	integer	Смещение результатов поиска. То есть, к примеру, если в параметре будет указано число `5`, полученный массив сообщений будет отображаться, начиная с 5 позиции.
taskId (optional)	integer	ID рассылки, по которой нужно получить детализацию. Можно узнать при создании сценария рассылки. Используется в обязательной комбинации параметров.
triggerId (optional)	integer	ID триггера рассылки. Можно узнать при получении сценария рассылки. Используется в обязательной комбинации параметров.
dateTimeFrom (optional)	datetime	Дата начала поиска сообщений. Используется в обязательной комбинации параметров. Формат - `YYYY-MM-DDThh%3Amm%3Ass`.
dateTimeTo (optional)	datetime	Дата окончания поиска сообщений. Используется в обязательной комбинации параметров. Формат - `YYYY-MM-DDThh%3Amm%3Ass`.
messageIds (optional)	array[integer]	ID сообщений, по которым нужно получить детализацию. Используется в обязательной комбинации параметров.
companyId (optional)	integer	ID компании. К данной компании принадлежит пользователь, который совершал рассылку.
order (optional)	string	В каком порядке выводить результаты запроса. Возможные значения: ○ `ASC` - в возрастающем порядке. ○ `DESC` - в убывающем порядке.
orderField (optional)	string	Поле, по которому будут отсортированы результаты запроса.
outFields (optional)	array[string]	Поля в результатах поиска. Неуказанные в этом параметре поля будут исключены.
recipient (optional)	string	Номер телефона получателя.
searchText (optional)	string	Поиск ключевого слова в текстах сообщений. Доступен поиск одного слова на английском языке.
status (optional)	string	Статус сообщений в результатах поиска. Возможные значения: ○ `DELIVERED` - сообщение доставлено получателю. ○ `IN_PROGRESS` - сообщение находится в процессе отправки. ○ `READ` - сообщение было прочитано получателем. ○ `REDIRECT` - получатель перешел по ссылке в сообщении. ○ `REJECTED` - сообщение было отклонено оператором или Devino. ○ `UNDELIVERED` - сообщение не доставлено.
timeOffset (optional)	integer	Часовой пояс получателя. Формат - смещение в минутах, например, `180` для Москвы (GMT+3).

Комбинации параметров¶

Для корректной работы метода в запросе необходимо использовать одну из этих комбинаций параметров в соответствии со списком:

ID рассылки: taskId
ID рассылки и триггера: taskId, triggerId
Даты начала и окончания поиска сообщений: dateTimeFrom, dateTimeTo
ID рассылки, триггера; даты начала и окончания поиска сообщений: taskId, triggerId, dateTimeFrom, dateTimeTo
ID сообщений: messageIds

Поля для параметров `orderField` и `outFields`¶

Используются в параметрах orderField для сортировки результатов поиска и outFields для отбора полей.

Название поля	Описание
DELIVERY_POLICY	Возможные значения: `any`, `mobile_device_required`, `verified_phone_number` По умолчанию `any`. Если указано `mobile_device_required`, то доставка сообщения происходила только в случае наличия у пользователя мобильного приложения и его использования в течение последних 7 дней. Если указано `verified_phone_number`, то доставка сообщения происходила только тем пользователям, чей номер телефона дополнительно был проверен на актуальность.
ERROR_CODE	Код ошибки.
EVENT_DATE_TIME	Дата и время последнего обновления статуса сообщения.
MESSAGE_ID	ID сообщения.
RECIPIENT	Номер телефона получателя.
ROUTE	Маршрут, по которому было отправлено сообщение.
SENT_DATE_TIME	Дата и время отправки.
SERVICE	Согласованное имя отправителя VK.
STATUS	Статус сообщения.
TASK_ID	ID рассылки.
TASK_NAME	Название рассылки.
TASK_TYPE	Тип рассылки.
TEMPLATE_ID	ID шаблона сообщения.
TEMPLATE_NAME	Название шаблона сообщения.
TEXT	Текст сообщения.
TEXT_OK	Текст сообщения, отправленного VK.
TEXT_VK	Текст сообщения, отправленного в Одноклассниках.
TRIGGER_ID	ID триггера рассылки.
USER_LOGIN	Логин пользователя, отправившего сообщения.
VALIDITY	Срок жизни сообщения в секундах.

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

С датами

curl -X GET https://api.devino.online/vk-stat/detail?dateTimeFrom=2022-10-06T13%3A45%3A30&dateTimeTo=2023-02-06T13%3A45%3A30&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

С ID рассылки и триггера

curl -X GET https://api.devino.online/vk-stat/detail?taskId=8742&triggerId=2312&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

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

Параметр	Тип данных	Описание
data	array[object]	Массив объектов с детальной информацией по каждому сообщению. Параметры определяются полями, которые были заданы в изначальном запросе.
size	integer	Количество элементов на странице и сообщений в результатах поиска. Задается параметром `limit`.
offset	integer	Смещение результатов поиска. То есть, к примеру, если в параметре будет указано число `5`, полученный массив сообщений будет отображаться, начиная с 5 позиции.
number	integer	Номер полученной страницы. Определяется параметром `offset`. ○ Если значение параметра `offset` будет `0` при любом значении параметра `limit`, то номер полученной страницы будет `1`. ○ Если `offset` будет больше `0`, но меньше, чем значение параметра `limit`, номер страницы будет `2`. Например, при `"offset": 5` и `"limit": 10`, значение параметра `number` будет `2`. ○ Если `offset` будет больше чем `limit`, то номер страницы будет определяться целочисленным делением `offset` на `limit` плюс 1 (`offset` / `limit` + 1). Например, при `"offset": 1000` и `"limit": 50`, значение параметра `number` будет `21` (`1000` / `50` + 1 = `21`).
pageExists	boolean	Существует ли отображаемая страница.
total	integer	Общее количество сообщений, по которым можно получить детализацию.
pages	integer	Общее количество страниц, по которым можно получить детализацию. Определяется целочисленным делением параметра `total` на `limit` (`total` / `limit`).
more	boolean	Индикатор: существуют ли страницы после текущей, указанной в параметре `number`.

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

{
  "result": {
    "offset": 1000,
    "number": 21,
    "size": 50,
    "pageExists": true,
    "data": [
      {
        "messageId":"23452453412344",
        "userLogin":"vk_user",
        "service":"vk_group_name",
        "sentDateTime":"2023-08-01 00:00:03",
        "recipient":"79112223344",
        "status":"DELIVERED",
        "eventDateTime":"2023-08-01 00:00:03",
        "templateId":"123432445234",
        "templateName":"vk_template_name",
        "validity":602,
        "errorCode":9
      },
      {
        "messageId":"23452453412345",
        "userLogin":"vk_user",
        "service":"vk_group_name",
        "sentDateTime":"2023-08-01 00:00:08",
        "recipient":"79112223344",
        "status":"UNDELIVERED",
        "eventDateTime":"2023-08-01 00:00:09",
        "text":"Ваш заказ прибыл на пункт выдачи.",
        "validity":86400,
        "errorCode":12
      },
      ...
    ],
    "more": true,
    "pages": 100,
    "total": 1000
  }
}

Статистика сообщений¶

Для получения общей статистики по статусам сообщений необходимо вызвать GET /vk-stat/statistics/of-group, передавая параметры фильтров и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
groupBy	string	Группировка результатов: ○ `NONE` - без группировки ○ `YEAR` - по годам ○ `MONTH` - по месяцам ○ `WEEK` - по неделям ○ `DAY` - по дням ○ `HOUR` - по часам
startDate	datetime	Дата начала периода сбора статистики. Формат - `YYYY-MM-DDThh%3Amm%3Ass`.
endDate	datetime	Дата окончания периода сбора статистики. Формат - `YYYY-MM-DDThh%3Amm%3Ass`.
taskId (optional)	integer	ID рассылки, по которой нужно получить статистику.
triggerId (optional)	integer	ID триггера рассылки, по которому нужно получить статистику.
timeOffset (optional)	integer	Часовой пояс получателя. Формат - смещение в минутах, например, `180` для Москвы (GMT +3).

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

curl -X GET https://api.devino.online/vk-stat/statistics/of-group?startDate=2022-10-06T13%3A45%3A30&endDate=2023-02-06T13%3A45%3A30&groupBy=MONTH
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

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

Параметр	Тип данных	Описание
messages	array[MessageStatusObject]	Количество сообщений по выбранному периоду, сгруппированных по статусам.
segments	array[MessageStatusObject]	Количество сегментов сообщений по выбранному периоду, сгруппированных по статусам.

MessageStatusObject¶

Объект содержит информацию о количестве сообщений со статусами:

Код	Описание
accepted	Сообщение было принято.
scheduled	Сообщение запланировано к отправке.
enrouted	Сообщение находится в процессе отправки оператору.
sent	Сообщение было отправлено в сеть оператора.
deleted	Сообщение было удалено.
delivered	Сообщение доставлено абоненту.
expired	Истек срок жизни сообщения.
seen	Сообщение было прочитано получателем.
clicked	Получатель перешел по ссылке в сообщении.
rejected	Сообщение было отклонено оператором или Devino.
undeliverable	Сообщение невозможно доставить.
unknown	Произошла неизвестная ошибка.

Каждый статус включает в себя параметры:

Параметр	Тип данных	Описание
date	string	Дата сбора статистики в зависимости от значения параметра `groupBy`.
amount	integer	Количество сообщений.

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

{
  "result": {
    "messages": {
      "accepted": [
        {
          "date": "2023-01-01 00:00:00",
          "amount": 100
        }
      ],
      "sent": [
        {
          "date": "2022-12-01 00:00:00",
          "amount": 2
        }
      ],
      "deleted": [],
      "delivered": [
        {
          "date": "2023-01-01 00:00:00",
          "amount": 67
        },
        {
          "date": "2022-10-01 00:00:00",
          "amount": 1
        },
        {
          "date": "2022-12-01 00:00:00",
          "amount": 72
        },
        {
          "date": "2023-02-01 00:00:00",
          "amount": 3
        }
      ],
      "enrouted": [],
      "expired": [],
      "seen": [],
      "clicked": [],
      "rejected": [],
      "scheduled": [],
      "undeliverable": [],
      "unknown": []
    },
    "segments": {
      "accepted": [
        {
          "date": "2023-01-01 00:00:00",
          "amount": 2
        },
        {
          "date": "2023-02-01 00:00:00",
          "amount": 4
        }
      ]
      ...
    }
  }
}

VK.COM¶

Отправка¶

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

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

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

Коды ошибок¶

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

Коллбэки¶

Возможные статусы¶

Пример коллбэка¶

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

Подключение¶

Параметры¶

IncomingMessageObject¶

Пример¶

Детализация¶

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

Комбинации параметров¶

Поля для параметров orderField и outFields¶

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

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

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

Статистика сообщений¶

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

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

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

MessageStatusObject¶

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

Поля для параметров `orderField` и `outFields`¶