Skip to content

VK.COM

Sending

To send a VK message it is required to:

  • Pass the sending message template to your account manager or technical support.
  • Get the template ID (for templateId parameter).
  • Call POST /vk/messages, sending message parameters in the body with authorization data in the header.

Attention

Please note the following sending restrictions:
○ No more than 50 notifications per second for one VK-group.
○ No more than 5 notifications per day for one user from one VK-group.

You can send a maximum of 1000 messages in one request.

Request parameters

Parameter Data type Description
callbackData
(optional)
object

An object with the data which will be specified in the callback with the message status.

Any "key" array:
{ "key1": "value1", "key2": "value2" }

delivery_policy
(optional)
string

Possible values: any, mobile_device_required, verified_phone_number

By default any.

If mobile_device_required is specified, then the message will be delivered only if the user has a mobile app and has used it within the last 7 days. In this case, message will be delivered to all available devices, not just the mobile ones.

If verified_phone_number is specified, then the message will be delivered only to those users whose phone number is additionally checked for relevance.

phone string Phone number in international format, according to E.164 standard.
routes array

List of possible transport channels separated by comma
(example: [ VK, OK ]).

VK - delivery on behalf of the official VK group.
OK - delivery on behalf of the official Odnoklassniki group.
VK by default.

Delivery is made before the physical device firstly gets the notification. When specifying several transport channels, only one of the channels will be eventually used.

The sequence and logic of the selected routes is configured when connecting to the system. If the parameter is not specified, all possible delivery methods are used by default.

The delivery will occur only if a certain group in the corresponding social network is specified in the template. For example, if only the VK group is specified in the template, then delivery to Odnoklassniki group using this template will not occur.

service string Approved sender's name in VK.
status_url
(optional)
string

The URL to which the system will send callbacks when the message status changes.

Any valid URL with the HTTP or HTTPS scheme.

templateId
(optional)
integer Message template ID in Devino.
tmpl string Name of the template. Then the message will be formed through the tmpl_data parameter.
tmpl_data object

JSON-object, where keys are the variable names in the template.

For example, for the template:
You have received a package at { address }. Confirmation code - { code }, - the parameter tmpl_data will imply: { "address": "ул. Ленина, д. 6", "code": "485372" }.

ttl
(optional)
integer

Lifetime of the message in seconds.

Minimal value: 60
Maximal value: 86400, 1 day
Default value: 86400

If the message is not delivered within the ttl time, it will not be delivered and charged.

Request example

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

Response parameters

Parameter Data type Description
code string

Shows the result of message processing.

1. OK - processed successfully.
2. REJECTED - an error has occurred while processing the request.

messageId array Message ID. To be given with "code": "OK" only.
reasons array An array of the errors which have occurred while processing the message. To be given with "code": "REJECTED" only.
reasons.key string Error code.

Error codes

Code Description
service.not.found Sending VK messages is not available.
billing.error Payment processing error.
message.contains.invalid.templateId Template ID is incorrect.
is.spam The message has been marked as spam.
too.many.messages The number of messages in the request exceeds the maximum limit. One request may contain up to 1000 messages.
login.must.be.not.null User's login is not specified.

Response examples

{
  "result": [
    {
      "code": "OK",
      "messageId": 2354676865423253
    }
  ]
}
{
  "result": [
    {
      "code": "REJECTED",
      "reasons": [
        {
          "key": "billing.error"
        }
      ]
    }
  ]
}

Incoming messages

How to connect

To enable incoming messages from users, contact your account manager or technical support. You will also need to provide the URL of the web server to process incoming messages.

Parameters

Parameter Data type Description
event_id string Message sending event ID.
group_id string ID of the group in which the event has occurred.
object IncomingMessageObject Object with the client and the incoming message parameters.
type string Event type.
v string API version for which the event was produced.

IncomingMessageObject

Parameter Data type Description
client_info ObjectClientInfo Object with the client parameters.
message ObjectMessage Object with the message parameters.

Important

The message_tag parameter in the incoming message will match the sent message ID in Devino. This ID will be returned in the response to the POST /vk/messages request, in the result.id parameter.

Example

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

Callbacks

How to connect

To set up callbacks with message statuses, please contact your account manager or technical support.

Possible statuses

Status Description
SENT The message delivery request has been sent.
DELIVERED The message has been delivered.
UNDELIVERABLE The message can not be delivered because the recipient does not exist in the system or the recipient has blocked receiving messages from this sender.
EXPIRED The message has not been delivered because the ttl delivery time has been expired.
RATELIMIT Message sending limit has been exceeded.
READ The message has been just read. This status would not come if the message was read after the ttl expired + 24 hours (this does not mean that the message will be deleted).
UNKNOWN Unknown exception.

Callback example

[
    {
          "channel": "VK",
          "messageId": "3721115754893245581",
          "ts": 1672137286244,
          "status": "SENT",
          "errorCode": 0
    }
]