PHPackages                             yageorgiy/botman-vk-community-callback-driver - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. yageorgiy/botman-vk-community-callback-driver

ActiveLibrary[Framework](/categories/framework)

yageorgiy/botman-vk-community-callback-driver
=============================================

A VK community callback driver for botman.io framework

1.7.8(3y ago)111.6k↑486.7%4[2 issues](https://github.com/yageorgiy/botman-vk-community-callback-driver/issues)[1 PRs](https://github.com/yageorgiy/botman-vk-community-callback-driver/pulls)MITPHPPHP >=7.0CI failing

Since May 3Pushed 2y ago4 watchersCompare

[ Source](https://github.com/yageorgiy/botman-vk-community-callback-driver)[ Packagist](https://packagist.org/packages/yageorgiy/botman-vk-community-callback-driver)[ Docs](https://github.com/yageorgiy/botman-vk-community-callback-driver)[ RSS](/packages/yageorgiy-botman-vk-community-callback-driver/feed)WikiDiscussions master Synced yesterday

READMEChangelog (10)Dependencies (6)Versions (29)Used By (0)

BotMan VK Community Callback driver
===================================

[](#botman-vk-community-callback-driver)

BotMan driver to connect VK Community with [BotMan](https://github.com/botman/botman) via Callback API.

[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![Packagist](https://camo.githubusercontent.com/eb8e01fcf557750f0362616e0e1635a7f696d3d23c72fec998cde14049b5ad42/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f796167656f726769792f626f746d616e2d766b2d636f6d6d756e6974792d63616c6c6261636b2d6472697665722e737667)](https://packagist.org/packages/yageorgiy/botman-vk-community-callback-driver)

Contributing
------------

[](#contributing)

Contributions are welcome, I would be glad to accept contributions via Pull Requests. 🙂 See `Contributors` tab for more details.

Support
-------

[](#support)

Table of driver's features:

FeatureIs SupportedSending text messages✔ Fully supportedSending images✔ Supported (no titles for images provided by VK API, pictures can't be uploaded to external albums with community token)\*Sending videos⚠ Partially supported (uploading videos with community token is not supported by VK API)\*Sending audio⚠ Partially supported (uploading audio is restricted by VK API)Sending voice messages✔ Fully supported via `Audio` object with `addExtras('vk_as_voice', true)`Sending documents (files)✔ Supported (some files might be restricted by the platform to be uploaded, the updated criteria list is no longer public in VK docs)Sending links✔ SupportedSending locations✔ Fully supportedSending stickers✔ Supported as an additional parameter to replySending wall posts✔ Supported as an additional parameter to replySending polls✔ Supported as an additional parameter to replySending market items✔ Supported as an additional parameter to replySending keyboards✔ Fully supportedSending carousels✔ Supported as an additional parameter to replyListening for images✔ Supported (no titles for images provided by VK API)Listening for videos⚠ Partially supported (no video URL provided by VK API, info of copyrighted videos can be unavailable via API)\*Listening for audio✔ Fully supportedListening for files✔ Fully supportedListening for locations✔ Fully supportedListening for voice messages❌ Not supported yetReceiving messages with mixed attachments✔ Fully supportedTyping status✔ Fully supported (photo or document upload, user call)Mark seen⚠ Partially supported (user-created conversations can't be marked via API)Retrieving user data✔ Fully supported (use `VK_USER_FIELDS` property for retrieving custom user fields)Usage in VK conversations✔ SupportedMultiple communities handling❌ Not supported yetVK Speech Recognition Service❌ Not implemented yetVK API low-level management✔ Fully supportedEvents listener✔ Fully supported (as for 14.08.2020)\* - uploading feature with user token is under construction

Setup
-----

[](#setup)

### Getting the Community API key

[](#getting-the-community-api-key)

From the page of your community, go to `Manage -> Settings tab -> API usage -> Access tokens tab`. Click `Create token` button.

[![API usage](./docs/1.png)](./docs/1.png)

Then tick all the permissions in the dialog box.

[![Dialog box with permissions](./docs/2.png)](./docs/2.png)

Copy your created token by clicking `Show` link.

[![Firstly added API token](./docs/3.png)](./docs/3.png)

### Installing the driver

[](#installing-the-driver)

Require the driver via composer:

```
composer require yageorgiy/botman-vk-community-callback-driver
```

If you're using BotMan Studio, you should define in the `.env` file the following properties:

```
VK_ACCESS_TOKEN="REPLACE_ME"                    # User or community token for sending messages (from Access tokens tab, see above)
VK_SECRET_KEY="REPLACE_ME"                      # Secret phrase for validating the request sender (from Callback API tab, see above)
VK_API_VERSION=5.103                            # API version to be used for sending an receiving messages (should be 5.103 and higher) (not recommended to change)
VK_MESSAGES_ENDPOINT=https://api.vk.com/method/ # VK API endpoint (don't change it if unnecessary)
VK_CONFIRM=                                     # DEPRECATED SINCE v.1.4.2, LEAVE BLANK (EMPTY STRING) - see 'Mounting & confirming the bot' section. Confirmation phrase for VK
VK_GROUP_ID="REPLACE_ME"                        # Community or group ID
VK_USER_FIELDS=                                 # Extra user fields (see https://vk.com/dev/fields for custom fields) (leave blank for no extra fields) (note: screen_name is already included!)
```

If you don't use BotMan Studio, the driver should be applied manually:

```
// ...

// Applying driver
DriverManager::loadDriver(\BotMan\Drivers\VK\VkCommunityCallbackDriver::class);

// Applying settings for driver
BotManFactory::create([
    "vk" => [
        "token" => "REPLACE_ME",                    // User or community token for sending messages (from Access tokens tab, see above)
        "secret" => "REPLACE_ME",                   // Secret phrase for validating the request sender (from Callback API tab, see above)
        "version" => "5.103",                       // API version to be used for sending an receiving messages (should be 5.103 and higher) (not recommended to change)
        "endpoint" => "https://api.vk.com/method/", // VK API endpoint (don't change it if unnecessary)
        "confirm" => "",                            // DEPRECATED SINCE v.1.4.2, LEAVE BLANK (EMPTY STRING) - see 'Mounting & confirming the bot' section. Confirmation phrase for VK
        "group_id" => "REPLACE_ME",                 // Community or group ID
        "user_fields" => ""                         // Extra user fields (see https://vk.com/dev/fields for custom fields) (leave blank for no extra fields) (note: screen_name is already included!)
    ]
]);

// ...
```

### Mounting & confirming the bot

[](#mounting--confirming-the-bot)

**⚠ \[Migrating from v.1.4.1 and older\]** Method of confirming the bot has changed since driver version 1.4.2: validation should be managed by using events listener, `VK_SECRET_KEY` (or `$botmanSettings["vk"]["confirm"]`) should be blank (empty string).

From the page of your community, go to `Manage -> Settings tab -> API usage -> Callback API tab`:

- Choose `5.103` API version.
- Fill the required field of URL address of your's bot mount (examples: , ).
- Fill the Secret key field *(required for driver!)*:

[![Callback API tab](./docs/4.png)](./docs/4.png)

- Find the string (validation code) in section `String to be returned`:

[![Callback API tab](./docs/5.png)](./docs/5.png)

- Add the following code to `routes/botman.php` file, replace `REPLACE_ME` with the validation code (e.g. `1a2b3c4d5e`):

```
$botman->on("confirmation", function($payload, $bot){
    // Use $payload["group_id"] to get group ID if required for computing the passphrase.
    echo("REPLACE_ME");
});
```

- Click `Confirm` button.

Quick guide with examples
-------------------------

[](#quick-guide-with-examples)

*In usage examples, the used file is `routes/botman.php`.*

### Sending simple message

[](#sending-simple-message)

If bot receives `Hello` message, it will answer `Hi, `:

```
$botman->hears('Hello', function ($bot) {
    $bot->reply('Hi, '.$bot->getUser()->getFirstName());
});
```

[![Example image](./docs/6.png)](./docs/6.png)

### Typing activity

[](#typing-activity)

Bot will wait 10 seconds before answering the question:

```
$botman->hears("What\'s your favourite colour\?", function ($bot) {
    $bot->reply('Let me think...');
    $bot->typesAndWaits(10);
    $bot->reply("I guess it's orange! 😄");
});
```

[![Example image](./docs/7.png)](./docs/7.png)

After all, it will answer:

[![Example image](./docs/8.png)](./docs/8.png)

### Attaching image

[](#attaching-image)

If bot receives `Gimme some image` message, it will answer `Here it is!` with an attached image:

```
use BotMan\BotMan\Messages\Attachments\Image;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

$botman->hears('Gimme some image', function ($bot) {
    // Create attachment
    $attachment = new Image('https://botman.io/img/logo.png');
    // $attachment->addExtras("vk_photo", "photo123456_123456"); // Or send an already uploaded photo (driver will ignore image url)

    // Build message object
    $message = OutgoingMessage::create('Here it is!')
        ->withAttachment($attachment);

    // Reply message object
    $bot->reply($message);
});
```

[![Example image](./docs/9.png)](./docs/9.png)

### Attaching video

[](#attaching-video)

Example of sending an already uploaded video:

**Note**: uploading videos to VK is not supported by the driver yet.

```
use BotMan\BotMan\Messages\Attachments\Video;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

$botman->hears('Gimme some video', function ($bot) {
    // Create attachment
    $attachment = new Video('http://unused-video-url');
    // Attaching already uploaded videos is the ONLY way to send them (as for now):
    $attachment->addExtras("vk_video", "video-2000416976_41416976"); // Send an already uploaded video (driver will ignore video url)

    // Build message object
    $message = OutgoingMessage::create('Here it is!')
        ->withAttachment($attachment);

    // Reply message object
    $bot->reply($message);
});
```

[![Example image](./docs/10.png)](./docs/10.png)

### Attaching audio

[](#attaching-audio)

Example of sending an already uploaded audio:

**Note**: uploading audio to VK is restricted by the platform.

```
use BotMan\BotMan\Messages\Attachments\Audio;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

$botman->hears('Gimme some audio', function ($bot) {
    // Create attachment
                            // URL can be uploaded ONLY as voice message (due to restrictions of VK)
    $attachment = new Audio('https://unused-audio-url');
    $attachment->addExtras("vk_audio", "audio371745438_456268888"); // Send an already uploaded audio (driver will ignore audio url and vk_as_voice parameter)

    // Build message object
    $message = OutgoingMessage::create('Here it is!')
        ->withAttachment($attachment);

    // Reply message object
    $bot->reply($message);
});
```

[![Example image](./docs/11.png)](./docs/11.png)

### Sending voice message

[](#sending-voice-message)

Voice messages can be send using `Audio` with extra parameter `vk_as_voice = true`.

Example of sending a voice message with message text:

**Note**: better to upload an \*.ogg file rather than \*.mp3, \*.wav and others. See [Uploading Voice Message](https://vk.com/dev/upload_files_3) for more info.

```
use BotMan\BotMan\Messages\Attachments\Audio;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

$botman->hears('Sing me a song', function ($bot) {
    // Create attachment
                            // URL can be uploaded ONLY as voice message (due to restrictions of VK)
    $attachment = new Audio('https://url-to-ogg-file');
//  $attachment->addExtras("vk_audio", "audio371745438_456268888"); // Send an already uploaded audio (driver will ignore audio url and vk_as_voice parameter)
    $attachment->addExtras("vk_as_voice", true);                    // Send as voice message (better to use *.ogg file)

    // Build message object
    $message = OutgoingMessage::create('Well...')
        ->withAttachment($attachment);

    // Reply message object
    $bot->reply($message);
});
```

During upload, the driver will send "recording audio" activity:

[![Example image](./docs/12.png)](./docs/12.png)

The result:

[![Example image](./docs/13.png)](./docs/13.png)

### Attaching document (file)

[](#attaching-document-file)

Example of sending file:

**Note**: not all files are available to upload. See [Uploading documents](https://vk.com/dev/upload_files_2?f=10.%2BUploading%2BDocuments) for more info.

```
use BotMan\BotMan\Messages\Attachments\File;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

$botman->hears("Any files\?", function ($bot) {
    $attachment = new File('https://url-to-file');
//  $attachment->addExtras("vk_doc", "doc123456_123456"); // Send an already uploaded document (driver will ignore audio url and vk_doc_title, vk_doc_tags parameters)
    $attachment->addExtras("vk_doc_title", "Cool guy.gif"); // Title
    $attachment->addExtras("vk_doc_tags", "cool, guy"); // Document tags

    // Build message object
    $message = OutgoingMessage::create('Yep!')
        ->withAttachment($attachment);

    // Reply message object
    $bot->reply($message);
});
```

Uploading a file will also trigger "sending message" activity.

[![Example image](./docs/14.png)](./docs/14.png)

### Attaching location

[](#attaching-location)

Example of sending location (taken from BotMan docs):

```
use BotMan\BotMan\Messages\Attachments\Location;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

$botman->hears('Any locations\?', function($bot) {
    // Create attachment
    $attachment = new Location(61.766130, -6.822510, [
        'custom_payload' => true,
    ]);

    // Build message object
    $message = OutgoingMessage::create('Locations are also supported!')
        ->withAttachment($attachment);

    // Reply message object
    $bot->reply($message);
});
```

The result:

[![Example image](./docs/15.png)](./docs/15.png)

### Additional parameters

[](#additional-parameters)

Additional parameters are used to append or replace message request parameters.

**Note:** `v` and `access_token` fields are ignored to be replaced. Change their parameters in `.env` file or in configuration array.

Example of replacing message text:

```
$botman->hears('Show me the replaced message', function($bot) {
    $bot->reply("This string will be ignored", [
        "message" => "This message string will be sent"
    ]);
});
```

[![The result](./docs/16.png)](./docs/16.png)

See [messages.send method](https://vk.com/dev/messages.send) for more info.

### Sending question buttons (simple keyboard)

[](#sending-question-buttons-simple-keyboard)

Example of sending simple keyboard via adding buttons to question. Keyboard will be shown as **`one_time = true`** (shown once) and **`inline = false`** (default non-inline keyboard), one button in a row. See `Sending full-supported keyboard` section for in-depth setup.

```
use BotMan\BotMan\Messages\Outgoing\Actions\Button;
use BotMan\BotMan\Messages\Outgoing\Question;
$botman->hears("List of functions\?", function ($bot) {
    $question = Question::create('My list of functions:')
        ->addButtons([
            Button::create('Function 1')->value('f1'),
            Button::create('Function 2')->value('f2'),
            Button::create('Function 3')->value('f3'),
            Button::create('Function 4')->value('f4'),
            Button::create('Function 5')->value('f5')
        ]);

    $bot->ask($question, function ($answer) {
        // Detect if button was clicked:
        if ($answer->isInteractiveMessageReply()) {
            $selectedValue = $answer->getValue(); // Contains button value e.g. 'f1', 'f2', ...
            $selectedText = $answer->getText(); // Contains title e.g. 'Function 1', 'Function 2', ...
        }
    });
});
```

[![Example image](./docs/17.png)](./docs/17.png)

**Note**: don't use `$answer->getText()` for validation purposes as it can be changed by the client (user). Use `$answer->getValue()` instead.

**Note**: better to send keyboards only in Conversation class, asking a question with buttons. See more [here](https://botman.io/2.0/conversations).

### Customizing the question buttons (simple keyboard)

[](#customizing-the-question-buttons-simple-keyboard)

**⚠ \[Migrating from v.1.4.x and older\]** Fields of `__x` and `__y` are now ignored by the driver. Use `VKKeyboard` serializing class to build a keyboard and add it to `$additionalParameters` of your outcoming message.

You can also change button's properties via additional parameters such as colour:

```
//...
$botman->hears("List of functions\?", function ($bot) {
    $question = Question::create('My list of functions:')
        ->addButtons([
            Button::create('Function 1')->value('f1')->additionalParameters([
                "color" => "secondary" // Colour (see available colours here - https://vk.com/dev/bots_docs_3)
            ]),
            Button::create('Function 2')->value('f2')->additionalParameters([
                "color" => "negative"
            ]),
            Button::create('Function 3')->value('f3')->additionalParameters([
                "color" => "primary"
            ]),
            Button::create('Function 4')->value('f4')->additionalParameters([
                "color" => "primary"
            ]),
            Button::create('Function 5')->value('f5')->additionalParameters([
                "color" => "primary"
            ])
        ]);

    $bot->ask($question, function ($answer) {
        //...
    });
});
```

[![Example image](./docs/18.png)](./docs/18.png)

See [VK documentation page](https://vk.com/dev/bots_docs_3) for available colours, types and other features. Just add new fields in array of additional parameters as it is shown in the example above.

### Sending native keyboard

[](#sending-native-keyboard)

Native keyboard can be send as an additional parameter **(works only for VK!)**:

```
use BotMan\Drivers\VK\Extensions\VKKeyboard;
use BotMan\Drivers\VK\Extensions\VKKeyboardButton;
use BotMan\Drivers\VK\Extensions\VKKeyboardRow;

$botman->hears('keyboard', function(BotMan $bot) {
    $keyboard = new VKKeyboard();
    $keyboard->setInline(false);    // Setting the inline mode ("inline" parameter)
    $keyboard->setOneTime(false);   // Setting "one_time" parameter

    $keyboard->addRows(
        // Top row
        new VKKeyboardRow([
            // Text example
            ( new VKKeyboardButton() )->setColor("primary")->setText("Sample text")->setValue("button1"),
            // UTF-8 text example
            ( new VKKeyboardButton() )->setColor("primary")->setText("Текст для примера")->setValue("button2"),
        ]),
        // Middle row
        new VKKeyboardRow([
            // Long text trim example
            ( new VKKeyboardButton() )
                // Colour (see available colours here - https://vk.com/dev/bots_docs_3)
                ->setColor("default")

                // Long text will be trimed with ellipsis at the end of the label
                ->setText("Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam nec ultrices purus, ut sollicitudin arcu.")

                // Set button value
                ->setValue("button3"),
        ]),
        // Bottom row
        new VKKeyboardRow([
            // Emoji example
            ( new VKKeyboardButton() )->setColor("negative")->setText("⛔")->setValue("button4"),
            ( new VKKeyboardButton() )->setColor("primary")->setText("⚠")->setValue("button5"),
            ( new VKKeyboardButton() )->setColor("positive")->setText("✅")->setValue("button6"),
        ])
    );

    $bot->reply("Native keyboard:", [
        "keyboard" => $keyboard->toJSON()
    ]);
});
```

[![Example image](./docs/19.png)](./docs/19.png)

You can also send a Question with additional parameters with keyboard:

```
// ...
$bot->ask($question, function ($answer) {
    // Detect if button was clicked:
    if ($answer->isInteractiveMessageReply()) {
        $selectedValue = $answer->getValue(); // Contains button value e.g. 'f1', 'f2', ...
        $selectedText = $answer->getText(); // Contains title e.g. 'Function 1', 'Function 2', ...
    }
}, [
    "keyboard" => $keyboard->toJSON()
]);
// ...
```

### Listening for images

[](#listening-for-images)

Native way for receiving images.

**Note**: no message text will be provided via `receivesImages()` method.

```
$botman->receivesImages(function($bot, $images) {
    foreach ($images as $image) {
        $url = $image->getUrl(); // The direct url
        $title = $image->getTitle(); // The title (empty string as titles are not supported by VK)
        $payload = $image->getPayload(); // The original payload

        $bot->reply("Detected image: {$url}");
    }
});
```

[![Example image](./docs/20.png)](./docs/20.png)

### Listening for videos

[](#listening-for-videos)

Native way for receiving videos.

**Note**: no message text will be provided via `receivesVideos()` method.

```
$botman->receivesVideos(function($bot, $videos) {
    foreach ($videos as $video) {
        $url = $video->getUrl(); // The direct url
        $payload = $video->getPayload(); // The original payload

        // For YouTube videos title can be accessed in the following way:
        $bot->reply("Detected video: {$payload["title"]}");
    }
});
```

[![Example image](./docs/21.png)](./docs/21.png)

### Listening for audio

[](#listening-for-audio)

Native way for receiving audio.

**Note**: no message text will be provided via `receivesAudio()` method.

```
$botman->receivesAudio(function($bot, $audios) {
    foreach ($audios as $audio) {
        $url = $audio->getUrl(); // The direct url
        $payload = $audio->getPayload(); // The original payload

        $bot->reply("Detected audio: {$url}");
    }
});
```

[![Example image](./docs/22.png)](./docs/22.png)

### Listening for documents (files)

[](#listening-for-documents-files)

Native way for receiving files.

**Note**: no message text will be provided via `receivesFiles()` method.

```
$botman->receivesFiles(function($bot, $files) {
    foreach ($files as $file) {
        $url = $file->getUrl(); // The direct url
        $payload = $file->getPayload(); // The original payload

        $bot->reply("Detected file (document): {$url}");
    }
});
```

[![Example image](./docs/23.png)](./docs/23.png)

### Listening for location

[](#listening-for-location)

Native way for receiving location.

**Note**: no message text will be provided via `receivesLocation()` method.

```
$botman->receivesLocation(function($bot, $location) {
    $lat = $location->getLatitude();
    $lng = $location->getLongitude();

    $bot->reply("Detected location: $lat $lng");
});
```

[![Example image](./docs/24.png)](./docs/24.png)

### Receiving messages with mixed attachments

[](#receiving-messages-with-mixed-attachments)

Message with mixed attachments can be asked via `hears()`, `ask()` or `fallback()` method (`IncomingMessage` with message text and attachments with all supported types).

Example with video and image attachments:

```
$botman->hears('I have both image and video for you.', function ($bot) {
    $bot->reply("Cool!");

    // Scanning for images
    $images = $bot->getMessage()->getImages() ?? [];
    foreach ($images as $image) {

        $url = $image->getUrl();

        $bot->reply("Image found: {$url}");
    }

    // Scanning for videos
    $videos = $bot->getMessage()->getVideos() ?? [];
    foreach ($videos as $video) {
        $payload = $video->getPayload();

        $bot->reply("Video found: {$payload["title"]}");
    }
});
```

[![Example image](./docs/25.png)](./docs/25.png)

### Retrieving extra user data

[](#retrieving-extra-user-data)

Extra user fields should be defined in `.env` file and can be accessed via `getUser()->getInfo()` method.

**⚠ \[Migrating from v.1.5.x and older\]** screen\_name is now used by the driver too. Remove `screen_name` value from `user_fields` parameter to prevent sending `screen_name` twice. Use `$bot->getUser()->getUsername()` to get username.

Example contents of `.env`:

```
# ...
VK_USER_FIELDS="photo_200_orig"
# ...
```

Example route:

```
$botman->hears('Gimme my photo_200_orig', function ($bot) {
    $bot->reply('Here it is: '.$bot->getUser()->getInfo()["photo_200_orig"]);
});
```

[![Example image](./docs/26.png)](./docs/26.png)

Multiple fields should be comma-separated:

```
# ...
VK_USER_FIELDS="photo_200_orig, photo_50"
# ...
```

See [User object](https://vk.com/dev/fields) for available fields.

### Retrieving extra client information

[](#retrieving-extra-client-information)

Information about supported features of user's VK client can be accessed via `$bot->getMessage()->getExtras("client_info")`:

**Note:** the feature works only with new messages sent (`message_new` event).

```
$botman->hears('my info', function(BotMan $bot) {
    // Prints raw "client_info" array
    $bot->reply(print_r($bot->getMessage()->getExtras("client_info"), true));
});
```

[![The reply](./docs/27.png)](./docs/27.png)

See [Information about features available to the user](https://vk.com/dev/bots_docs?f=2.3.%20Information%20about%20features%20available%20to%20the%20user) for more details.

### Mark seen example

[](#mark-seen-example)

Every message will be marked as seen even if there is no response for it:

```
$botman->hears("Don\'t answer me", function ($bot) {
    // Do nothing
});
```

[![Example image](./docs/28.png)](./docs/28.png)

### Listening to events

[](#listening-to-events)

List of supported events:

- `confirmation`
- `message_allow`
- `message_deny`
- `message_typing_state` \*
- `message_event` \*
- `photo_new`
- `photo_comment_new`
- `photo_comment_edit`
- `photo_comment_restore`
- `photo_comment_delete`
- `audio_new`
- `video_new`
- `video_comment_new`
- `video_comment_edit`
- `video_comment_restore`
- `video_comment_delete`
- `wall_post_new`
- `wall_repost`
- `wall_reply_new`
- `wall_reply_edit`
- `wall_reply_restore`
- `wall_reply_delete`
- `board_post_new`
- `board_post_edit`
- `board_post_restore`
- `board_post_delete`
- `market_comment_new`
- `market_comment_edit`
- `market_comment_restore`
- `market_comment_delete`
- `market_order_new` \*
- `market_order_edit` \*
- `group_leave`
- `group_join`
- `user_block`
- `user_unblock`
- `poll_vote_new`
- `group_officers_edit`
- `group_change_settings`
- `group_change_photo`
- `vkpay_transaction` \*
- `app_payload` \*
- `like_add` \*
- `like_remove` \*

\* - missing english version in VK docs, but feature exists (as for 14.08.2020)

\*\* - missing in VK docs, but feature exists (as for 14.08.2020)

**Note:** events of `message_new`, `message_reply`, `message_edit` are assessable via Hearing Messages functions (e.g. `$botman->hear()`).

[Full list of events (VK docs)](https://vk.com/dev/groups_events)

Example of sending message when the typing state changed:

```
$botman->on("message_typing_state", function($payload, $bot){
    // $payload is an array of the event object ("Object field format"),
    // excepting Confirmation event, where $payload contains full root JSON schema.
    // See https://vk.com/dev/groups_events for more info
    $bot->say("Hey! You're typing something!", $payload["from_id"]);
});
```

**Note:** `$bot->reply()` is not supported here, use `$bot->say("...", $peer_id_from_data)` instead.

The result:

[![The result image](./docs/29.png)](./docs/29.png)

ℹ️ Don't forget to enable a `Typing status` event in `Callback API -> Event types` tab.

[![Typing status enabled](./docs/30.png)](./docs/30.png)

### Sending low-level API requests

[](#sending-low-level-api-requests)

Example of sending a sticker via `$bot->sendRequest()`:

**Note:** it is also possible to send stickers via additional parameters.

```
$botman->hears('sticker', function($bot) {
    // API method
    $endpoint = "messages.send";

    // Arguments ("v" and "access_token" are set by driver, no need to define)
    $arguments = [
         "peer_id" => $bot->getUser()->getId(), // User ID
         "sticker_id" => 12, // Sticker ID
         "random_id" => 0 // required by VK API
    ];

    $test = $bot->sendRequest($endpoint, $arguments);
    // $test now equals to ["response" => 1234];
});
```

The result:

[![The result of sticker sending](./docs/31.png)](./docs/31.png)

### Sending carousels

[](#sending-carousels)

The driver also ships with implemented wrapper for attaching native carousel objects.

For example:

```
use BotMan\Drivers\VK\Extensions\VKKeyboardButton;
use BotMan\Drivers\VK\Extensions\VKCarousel;
use BotMan\Drivers\VK\Extensions\VKCarouselActionOpenLink;
use BotMan\Drivers\VK\Extensions\VKCarouselElement;

$botman->hears('carousel', function($bot) {
    $carousel = new VKCarousel();

    for($i = 1; $i addElements(
            new VKCarouselElement(
                "Element {$i}",
                "Description {$i}",
                [
                    ( new VKKeyboardButton() )
                        ->setColor("secondary")->setText("Button {$i}")->setValue("button1")
                ],
                "-00000_11111", // This is an example icon ID:
                                // replace `00000` with community ID, the `11111` - with image ID
                new VKCarouselActionOpenLink("https://some-url/")
            )
        );
    }

    $bot->reply("Native carousel:", [
        "template" => $carousel->toJSON()
    ]);
});
```

[![Example result](./docs/32.png)](./docs/32.png)

See also
--------

[](#see-also)

- [VK documentation for developers](https://vk.com/dev/callback_api)
- [New VK documentation for developers](https://dev.vk.com/)
- [BotMan documentation](https://botman.io/2.0/welcome)

License
-------

[](#license)

VK Community Callback driver is made under the terms of MIT license. BotMan is free software distributed under the terms of the MIT license.

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance16

Infrequent updates — may be unmaintained

Popularity29

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 96.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~38 days

Recently: every ~204 days

Total

28

Last Release

1224d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/52546287?v=4)[Yankovskiy Georgiy](/maintainers/yageorgiy)[@yageorgiy](https://github.com/yageorgiy)

---

Top Contributors

[![yageorgiy](https://avatars.githubusercontent.com/u/52546287?v=4)](https://github.com/yageorgiy "yageorgiy (57 commits)")[![Yui-Ezic](https://avatars.githubusercontent.com/u/21062493?v=4)](https://github.com/Yui-Ezic "Yui-Ezic (2 commits)")

---

Tags

botmanbotman-driverbotman-studiolaravelphpreceiving-messagesvkvk-apivk-botvk-bot-apivkbotvkbotapivkontaktevkontakte-apivkontakte-bot-apibotvkvkontakteVK apiBotmanVK CommunityVK MessagesVK CallbackVkontakte BotVkontakte Community Bot

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/yageorgiy-botman-vk-community-callback-driver/health.svg)

```
[![Health](https://phpackages.com/badges/yageorgiy-botman-vk-community-callback-driver/health.svg)](https://phpackages.com/packages/yageorgiy-botman-vk-community-callback-driver)
```

###  Alternatives

[ccxt/ccxt

A cryptocurrency trading API with more than 100 exchanges in JavaScript / TypeScript / Python / C# / PHP / Go

43.2k341.0k1](/packages/ccxt-ccxt)[digitalstars/simplevk

Powerful PHP library/framework for VK API bots, supporting LongPoll & Callback & OAuth

924.4k3](/packages/digitalstars-simplevk)[nutgram/nutgram

The Telegram bot library that doesn't drive you nuts

737290.3k8](/packages/nutgram-nutgram)[botman/studio

BotMan Chatbot framework.

33327.8k](/packages/botman-studio)[botman/driver-web

Web driver for BotMan

86690.6k7](/packages/botman-driver-web)[mpociot/botman-laravel-starter

BotMan Chatbot framework.

3325.4k](/packages/mpociot-botman-laravel-starter)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)