Mobile Chatbot Development for VKontakte

VKontakte Chatbot Mobile Development

VK Bot API is one of the most advanced in CIS countries: Callback API, Long Poll, Keyboard, Carousel, VK Mini Apps. VKontakte audience is 100M+ users in Russia and CIS. For Russian businesses, it's a primary messenger channel alongside Telegram.

Two Ways to Receive Messages: Callback vs Long Poll

Callback API — VK sends a POST to your HTTPS server on each event. Similar to webhooks. Suitable for production.

Long Poll — your server makes a GET request that "hangs" until a new event appears. Works without HTTPS, convenient for development.

Callback API is configured in the VKontakte group's Management → API Settings → Callback API section. When you add it, VK sends a confirmation event — return the string from group settings:

from fastapi import FastAPI, Request

app = FastAPI()
CONFIRMATION_TOKEN = "abc123xyz"  # From group settings
SECRET_KEY = "your_secret"        # For signature verification

@app.post("/vk/webhook")
async def vk_webhook(request: Request):
    data = await request.json()

    # Signature verification
    if data.get("secret") != SECRET_KEY:
        return "forbidden"

    if data["type"] == "confirmation":
        return CONFIRMATION_TOKEN

    if data["type"] == "message_new":
        message = data["object"]["message"]
        await handle_message(message)

    return "ok"  # VK requires exactly the string "ok"

If you don't return "ok", VK will retry the event up to 3 times, then mark delivery as failed.

Sending Messages: Messages API

import vk_api
from vk_api.bot_longpoll import VkBotLongPoll, VkBotEventType

# Via vk_api library
vk_session = vk_api.VkApi(token=GROUP_TOKEN)
vk = vk_session.get_api()

def send_message(peer_id: int, text: str, keyboard=None):
    params = {
        "peer_id": peer_id,
        "message": text,
        "random_id": 0  # 0 = auto random_id for duplicate protection
    }
    if keyboard:
        params["keyboard"] = json.dumps(keyboard)
    vk.messages.send(**params)

random_id is important: VK deduplicates messages by (peer_id, random_id). With random_id=0, it's automatic. With a fixed value, a retry won't create a duplicate message — protection against double-sending.

Keyboard and Carousel

VK Keyboard is similar to Telegram InlineKeyboard but with two modes: regular keyboard (inline: false) replaces the system keyboard, inline (inline: true) attaches to a specific message.

keyboard = {
    "inline": False,
    "one_time": False,  # Don't hide after clicking
    "buttons": [
        [
            {
                "action": {
                    "type": "text",
                    "label": "Catalog",
                    "payload": json.dumps({"command": "catalog"})
                },
                "color": "primary"
            },
            {
                "action": {
                    "type": "text",
                    "label": "Cart",
                    "payload": json.dumps({"command": "cart"})
                },
                "color": "secondary"
            }
        ]
    ]
}

Button colors: primary (blue), secondary (white), positive (green), negative (red). Maximum 4 buttons per row, 10 rows.

Carousel (template carousel) is a horizontal card carousel, similar to Generic Template in Messenger. Up to 10 elements, each with image, title, description, and buttons.

VK Mini Apps

VK Mini Apps are web applications inside VKontakte, analogous to Telegram Mini App. SDK: @vkontakte/vk-bridge.

import bridge from '@vkontakte/vk-bridge';

bridge.subscribe((e) => {
    if (e.detail.type === 'VKWebAppUpdateConfig') {
        // Theme (light/dark), color scheme
        const scheme = e.detail.data.scheme;
        document.body.setAttribute('scheme', scheme);
    }
});

// Get user data
const userInfo = await bridge.send('VKWebAppGetUserInfo');
// { id, first_name, last_name, photo_200, ... }

vk-bridge enables: getting user data, opening payment dialog (VKWebAppOpenPayForm), requesting geolocation, copying to clipboard, opening QR scanner.

Mini App authorization: launch_params in the URL contain signed data (the sign field). Server-side verification via HMAC-SHA256 with the API Secret from app settings is mandatory.

Getting User Information

On an incoming message, from_id is the VK user ID. To get name and photo:

users = vk.users.get(user_ids=from_id, fields="photo_50,city")
user = users[0]
# {'id': 12345, 'first_name': 'Ivan', 'last_name': 'Ivanov', 'photo_50': 'https://...'}

Important: the bot sees only public information. Private profiles show first_name as "DELETED" or are unavailable.

Development Process

Creating a group and configuring the API. Choosing Callback or Long Poll. Implementing webhook with verification. Dialog flows, Keyboard. For VK Mini Apps: development with vk-bridge, server-side verification. Analytics via VK Business. Deployment and monitoring.

Timeline Estimates

A bot with keyboard and command handling — 1–2 weeks. A VK Mini App with authentication, full UI, and API integration — 4–8 weeks.