picoclaw/docs/channels/vk/README.md

VK (VKontakte)

The VK channel uses Bots Long Poll API for bot-based communication with VK social network. It supports text messages, media attachments (photos, videos, audio, documents, stickers), and group chat interactions.

Configuration

{
  "channels": {
    "vk": {
      "enabled": true,
      "token": "NOT_HERE",
      "group_id": 123456789,
      "allow_from": ["123456789"],
      "group_trigger": {
        "mention_only": false,
        "prefixes": ["/bot", "!bot"]
      }
    }
  }
}

Field	Type	Required	Description
enabled	bool	Yes	Whether to enable the VK channel
token	string	Yes	Set to NOT_HERE - token is stored securely (see Token Storage)
group_id	int	Yes	VK Community ID (Group ID)
allow_from	array	No	Allowlist of user IDs; empty means all users are allowed
group_trigger	object	No	Configuration for group chat triggers

Token Storage

For security reasons, the VK access token should not be stored directly in the configuration file. Instead:

1. Set token to "NOT_HERE" in the configuration
2. Store the actual token using one of these methods:
   • Environment variable: Set PICOCLAW_CHANNELS_VK_TOKEN environment variable
   • Secure storage: Use PicoClaw's secure token storage mechanism

Example using environment variable:

export PICOCLAW_CHANNELS_VK_TOKEN="vk1.a.abc123..."

Group Trigger Configuration

Field	Type	Description
mention_only	bool	Only respond when bot is mentioned in group chats
prefixes	[]string	List of prefixes that trigger bot response in group chats

Setup

1. Create a VK Community

1. Go to VK and log in
2. Create a new community or use an existing one
3. Note your Community ID (found in the community URL, e.g., public123456789)

2. Enable Messages

1. Go to your community page
2. Click "Manage" → "Messages" → "Community Messages"
3. Enable community messages

3. Create Access Token

1. Go to "Manage" → "API usage" → "Access tokens"
2. Click "Create token"
3. Select the following permissions:
   • messages - Access to messages
   • photos - Access to photos (optional)
   • docs - Access to documents (optional)
4. Copy the generated access token
5. Store the token securely (see Token Storage section below)

4. Configure PicoClaw

1. Add the token to your PicoClaw configuration
2. Set the group_id to your community ID (numeric value)
3. (Optional) Configure allow_from to restrict which user IDs can interact

Features

Supported Message Types

• Text messages: Full support for text messages
• Photos: Photos are displayed as [photo] placeholder
• Videos: Videos are displayed as [video] placeholder
• Audio: Audio files are displayed as [audio] placeholder
• Voice messages: Voice messages are displayed as [voice] placeholder and support transcription
• Documents: Documents are displayed as [document: filename]
• Stickers: Stickers are displayed as [sticker] placeholder

Voice Support

The VK channel supports both voice message reception and text-to-speech capabilities:

• ASR (Automatic Speech Recognition): Voice messages can be transcribed to text using configured voice models
• TTS (Text-to-Speech): Text responses can be converted to voice messages

To enable voice transcription, configure a voice model in your providers setup. See Voice Transcription for details.

Group Chat Support

The VK channel supports group chats with configurable triggers:

• Mention-only mode: Bot only responds when mentioned
• Prefix mode: Bot responds to messages starting with specified prefixes
• Permissive mode: Bot responds to all messages (default)

Message Length

VK has a maximum message length of 4000 characters. PicoClaw automatically splits longer messages into multiple parts.

Example Configuration

Basic Configuration

{
  "channels": {
    "vk": {
      "enabled": true,
      "token": "NOT_HERE",
      "group_id": 123456789
    }
  }
}

With User Whitelist

{
  "channels": {
    "vk": {
      "enabled": true,
      "token": "NOT_HERE",
      "group_id": 123456789,
      "allow_from": ["123456789", "987654321"]
    }
  }
}

With Group Chat Triggers

{
  "channels": {
    "vk": {
      "enabled": true,
      "token": "NOT_HERE",
      "group_id": 123456789,
      "group_trigger": {
        "prefixes": ["/bot", "!bot"]
      }
    }
  }
}

Troubleshooting

Bot Not Responding

1. Check that the access token is valid
2. Verify that the group_id is correct
3. Ensure the user ID is in allow_from if configured
4. Check PicoClaw logs for error messages

Permission Errors

Make sure the access token has the necessary permissions:

• messages - Required for sending and receiving messages
• photos - Optional, for handling photo attachments
• docs - Optional, for handling document attachments

Group Chat Issues

If the bot doesn't respond in group chats:

1. Check group_trigger configuration
2. Try using a prefix to trigger the bot
3. Check if the bot has permission to read group messages

API Reference

The VK channel uses the VK SDK for Go library, which supports VK API version 5.199.

For more information about VK API, see:

• VK API Documentation
• VK Bots Long Poll API