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 |
delivery_policy (optional) |
string | Possible values: By default If If |
phone | string | Phone number in international format, according to E.164 standard. |
routes | array | List of possible transport channels separated by comma ○ 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 |
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: |
ttl (optional) |
integer | Lifetime of the message in seconds. Minimal value: 60 If the message is not delivered within the |
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. |
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
}
]