Community Messages

Community Messages A service for direct dialogue between the user and the VKontakte community..

• •

  Your customers will not have to look for a feedback form, register, respond via email — no unnecessary actions.

• •

  Together with the message, you get all the necessary data about its author, you can automatically process typical applications and instantly respond to messages using a bot.

Community messages work in full and mobile versions of the VKontakte as well as in all official applications: your company can be contacted on any platform. More about community messages — in the article Useful Settings for Community Messages .

Community Message API

This tutorial explains how to use the API to work with community messages.

Access key

To work with the API on behalf of the community, you need to get a special access key. You can do this in two ways — in the community management interface or programmatically, with a special request to our server.

The access key is a string that includes Latin letters and numbers. It needs to be passed in a parameter access_token by referring to API methods on behalf of the community.

Obtaining an Access Key in Community Settings

1. 1.

   Open the vk.com and go to the community where you are an administrator.

2. 2.

   Select the menu on the right.. Management and then Working with API .

3. 3.

   Press Creating a Key . Note the necessary access rights and confirm your choice.

You can create multiple keys with different access rights. Keys should not be posted publicly — after recognizing it, a third party can access the API VKontakte on behalf of your community. If the key has been compromised, it is necessary to remove it from the list - after that it will become invalid.

Obtaining the access key on the oauth.vk.ru

We offer two authorization methods based on the OAuth 2.0 protocol. Use this approach if you need to work with many user communities, for example, when developing a mobile application.

Use the API on the server side Authorization Code Flow .

Use the API on the client side Implicit Flow .

Working with Messages

The community message API uses the same methods as the user’s private messages. If you’ve dealt with messages in API VKontakte before, you’ll be familiar with the layout. It is necessary, however, to take into account some features:

• •
  It is necessary to indicate the read status of the message when communicating with the client;
• •
  If the answer is received by the user, it must be marked as read;
• •
  Special labels are available in community conversations: Important , Unanswered , Unread .

In order for you to be able to send messages to the user on behalf of the community, the user must allow them to be received. If a user has written a message to the community first, this equates to agreeing to receive return messages (without time limits, unless the user has manually banned the messages). To request permission from the user to send messages, use:

• •
  Event VKWebAppAllowMessagesFromGroup Libraries VK Bridge .
• •
  Method messages.allowMessagesFromGroup in standalone applications.
• •
  Widget Allowing the community to write on an external site.

B. Callback API and Bots Longpoll API Events message_allow and message_deny will help track the fact of permission and prohibition of messages from the community.

Available tools and methods

• •
  The Long Poll Server Synchronization of updates;
• •
  Callback API Instant notifications of new messages and other user actions in the community.
• •
  messages.getConversations - method for obtaining a list of conversations;
• •
  messages.markAsRead method for assigning a label to a message Read ;
• •
  messages.markAsImportantConversation , messages.markAsAnsweredConversation - methods for assigning labels to conversations;
• •
  messages.send A method for sending a new message;
• •
  messages.delete , messages.deleteConversation , messages.restore methods for deleting and restoring messages and conversations;
• •
  messages.search A method for searching messages;
• •
  messages.allowMessagesFromGroup , messages.denyMessagesFromGroup methods for subscribing to community messages and prohibiting receiving messages;
• •
  docs.getWallUploadServer A method for loading a document onto a wall.
• •
  groups.getCallbackConfirmationCode , groups.getCallbackServerSettings , groups.getCallbackSettings , groups.setCallbackSettings - methods for working with the Callback API settings.

Getting a list of conversations

Method messages.getConversations .

Parameter start_message_id is used to protect against bias due to new messages when loading old conversations. Don’t pass on the first call start_message_id Remember the meaning id the message in the first conversation and use it as a start_message_id in subsequent calls when loading conversations.

Receiving new conversations

Method messages.getConversations .

Pass the parameter values:

• •
  start_message_id meaning id Messages in the first interview.
• •
  count Maximum number of conversations.
• •
  offset negative meaning.

Receiving Message History in Conversation

Method messages.getHistory .

To get a story of a particular conversation, use the parameter peer_id . Parameter start_message_id is used to protect against bias due to new messages when loading a story. Don’t pass on the first call start_message_id Remember the meaning id the first message from the reply and use it as a start_message_id in subsequent calls.

Receiving new messages using the Callback API

Callback API It allows you to instantly receive information about new messages to the community.

To work with the Callback API, you’ll need a server script to handle notifications. Set up alerts by following documentation Choose among the event types Receiving a new message ( message_new ).

VKontakte will send to your server an alert for each new message with object of a personal communication In the format:

The notification contains comprehensive information about the message — you can immediately respond to it using the method messages.send .

Passing an arbitrary parameter using the vk.me reference

vk.me is a short URL service that redirects users to a specified conversation. The link is http://vk.me/ {group_name}, where group_name Community ID. Take vk.me/apiclub for example.

You can not only create a beautiful link to a conversation with the community, but also transfer arbitrary parameters to such a link ref and ref_source which will return in the message object in event message_new Callback API or Bots Long Poll API if the user starts or continues a conversation at a link of the type vk.me

This is useful for tracking the effectiveness of links placed in different channels, or linking the user to a session or account in an external application. Depending on the parameter transmitted, you can vary the bot's responses in the community.

The reference to the vk.me with additional parameters is as follows:

A reference of the form will also work:

Отправка изображений

To send an image in a message, use the parameter attachments In the method messages.send . You can use the image that is already on the VKontakte website, or loading a new .

Use methods to upload photos and documents to community posts, respectively photos.getMessagesUploadServer and docs.getMessagesUploadServer . This will allow you to download attachments for an unlimited number of interlocutors.