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¶

OK

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

REJECTED

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