{"id":15133935,"url":"https://github.com/yageorgiy/botman-vk-community-callback-driver","last_synced_at":"2025-10-23T09:31:20.389Z","repository":{"id":56049116,"uuid":"260975275","full_name":"yageorgiy/botman-vk-community-callback-driver","owner":"yageorgiy","description":"A VK community callback API driver for botman.io framework","archived":false,"fork":false,"pushed_at":"2023-07-14T08:32:03.000Z","size":1601,"stargazers_count":12,"open_issues_count":3,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-30T17:38:25.961Z","etag":null,"topics":["botman","botman-driver","botman-studio","laravel","php","receiving-messages","vk","vk-api","vk-bot","vk-bot-api","vkbot","vkbotapi","vkontakte","vkontakte-api","vkontakte-bot-api"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yageorgiy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-03T16:42:47.000Z","updated_at":"2024-05-15T14:31:42.000Z","dependencies_parsed_at":"2024-09-26T05:11:54.683Z","dependency_job_id":null,"html_url":"https://github.com/yageorgiy/botman-vk-community-callback-driver","commit_stats":{"total_commits":55,"total_committers":4,"mean_commits":13.75,"dds":0.07272727272727275,"last_synced_commit":"cd872fd4bb16f6173891c284fc5be4bfcb70d152"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yageorgiy%2Fbotman-vk-community-callback-driver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yageorgiy%2Fbotman-vk-community-callback-driver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yageorgiy%2Fbotman-vk-community-callback-driver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yageorgiy%2Fbotman-vk-community-callback-driver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yageorgiy","download_url":"https://codeload.github.com/yageorgiy/botman-vk-community-callback-driver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237807464,"owners_count":19369596,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["botman","botman-driver","botman-studio","laravel","php","receiving-messages","vk","vk-api","vk-bot","vk-bot-api","vkbot","vkbotapi","vkontakte","vkontakte-api","vkontakte-bot-api"],"created_at":"2024-09-26T05:01:42.637Z","updated_at":"2025-10-23T09:31:19.608Z","avatar_url":"https://github.com/yageorgiy.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BotMan VK Community Callback driver\n\nBotMan driver to connect VK Community with [BotMan](https://github.com/botman/botman) via Callback API.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Packagist](https://img.shields.io/packagist/v/yageorgiy/botman-vk-community-callback-driver.svg)](https://packagist.org/packages/yageorgiy/botman-vk-community-callback-driver)\n\n\n## Contributing\n\nContributions are welcome, I would be glad to accept contributions via Pull Requests. 🙂 See `Contributors` tab for more details.\n\n## Support\nTable of driver's features:\n\n|Feature|Is Supported|\n| --- | --- |\n|Sending text messages|✔ Fully supported|\n|Sending images|✔ Supported (no titles for images provided by VK API, pictures can't be uploaded to external albums with community token)*|\n|Sending videos|⚠ Partially supported (uploading videos with community token is not supported by VK API)*|\n|Sending audio|⚠ Partially supported (uploading audio is restricted by VK API)|\n|Sending voice messages|✔ Fully supported via `Audio` object with `addExtras('vk_as_voice', true)`|\n|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)|\n|Sending links|✔ Supported|\n|Sending locations|✔ Fully supported|\n|Sending stickers|✔ Supported as an additional parameter to reply|\n|Sending wall posts|✔ Supported as an additional parameter to reply|\n|Sending polls|✔ Supported as an additional parameter to reply|\n|Sending market items|✔ Supported as an additional parameter to reply|\n|Sending keyboards|✔ Fully supported|\n|Sending carousels|✔ Supported as an additional parameter to reply|\n|Listening for images|✔ Supported (no titles for images provided by VK API)|\n|Listening for videos|⚠ Partially supported (no video URL provided by VK API, info of copyrighted videos can be unavailable via API)*|\n|Listening for audio|✔ Fully supported|\n|Listening for files|✔ Fully supported|\n|Listening for locations|✔ Fully supported|\n|Listening for voice messages|❌ Not supported yet|\n|Receiving messages with mixed attachments|✔ Fully supported|\n|Typing status|✔ Fully supported (photo or document upload, user call)|\n|Mark seen|⚠ Partially supported (user-created conversations can't be marked via API)|\n|Retrieving user data|✔ Fully supported (use `VK_USER_FIELDS` property for retrieving custom user fields)|\n|Usage in VK conversations|✔ Supported|\n|Multiple communities handling|❌ Not supported yet|\n|VK Speech Recognition Service|❌ Not implemented yet|\n|VK API low-level management|✔ Fully supported|\n|Events listener|✔ Fully supported (as for 14.08.2020)|\n\n\\* \\- uploading feature with user token is under construction\n\n\n\n\n## Setup\n### Getting the Community API key\nFrom the page of your community, go to `Manage -\u003e Settings tab -\u003e API usage -\u003e Access tokens tab`. Click `Create token` button.\n\n![API usage](./docs/1.png)\n\nThen tick all the permissions in the dialog box.\n\n![Dialog box with permissions](./docs/2.png)\n\nCopy your created token by clicking `Show` link.\n\n![Firstly added API token](./docs/3.png)\n\n### Installing the driver\nRequire the driver via composer:\n```bash\ncomposer require yageorgiy/botman-vk-community-callback-driver\n```\n\nIf you're using BotMan Studio, you should define in the `.env` file the following properties:\n\n```dotenv\nVK_ACCESS_TOKEN=\"REPLACE_ME\"                    # User or community token for sending messages (from Access tokens tab, see above)\nVK_SECRET_KEY=\"REPLACE_ME\"                      # Secret phrase for validating the request sender (from Callback API tab, see above)\nVK_API_VERSION=5.103                            # API version to be used for sending an receiving messages (should be 5.103 and higher) (not recommended to change)\nVK_MESSAGES_ENDPOINT=https://api.vk.com/method/ # VK API endpoint (don't change it if unnecessary)\nVK_CONFIRM=                                     # DEPRECATED SINCE v.1.4.2, LEAVE BLANK (EMPTY STRING) - see 'Mounting \u0026 confirming the bot' section. Confirmation phrase for VK\nVK_GROUP_ID=\"REPLACE_ME\"                        # Community or group ID\nVK_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!)\n```\n\nIf you don't use BotMan Studio, the driver should be applied manually:\n```php\n// ...\n\n// Applying driver\nDriverManager::loadDriver(\\BotMan\\Drivers\\VK\\VkCommunityCallbackDriver::class);\n\n// Applying settings for driver\nBotManFactory::create([\n    \"vk\" =\u003e [\n        \"token\" =\u003e \"REPLACE_ME\",                    // User or community token for sending messages (from Access tokens tab, see above)\n        \"secret\" =\u003e \"REPLACE_ME\",                   // Secret phrase for validating the request sender (from Callback API tab, see above)\n        \"version\" =\u003e \"5.103\",                       // API version to be used for sending an receiving messages (should be 5.103 and higher) (not recommended to change)\n        \"endpoint\" =\u003e \"https://api.vk.com/method/\", // VK API endpoint (don't change it if unnecessary)\n        \"confirm\" =\u003e \"\",                            // DEPRECATED SINCE v.1.4.2, LEAVE BLANK (EMPTY STRING) - see 'Mounting \u0026 confirming the bot' section. Confirmation phrase for VK\n        \"group_id\" =\u003e \"REPLACE_ME\",                 // Community or group ID\n        \"user_fields\" =\u003e \"\"                         // Extra user fields (see https://vk.com/dev/fields for custom fields) (leave blank for no extra fields) (note: screen_name is already included!)\n    ]\n]);\n\n// ...\n```\n\n### Mounting \u0026 confirming the bot\n**⚠ \\[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).\n\nFrom the page of your community, go to `Manage -\u003e Settings tab -\u003e API usage -\u003e Callback API tab`:\n\n- Choose `5.103` API version.\n- Fill the required field of URL address of your's bot mount (examples: https://example.com/botman, http://some.mysite.ru/botman).\n- Fill the Secret key field *(required for driver!)*:\n\n![Callback API tab](./docs/4.png)\n\n- Find the string (validation code) in section `String to be returned`:\n\n![Callback API tab](./docs/5.png)\n\n- Add the following code to `routes/botman.php` file, replace `REPLACE_ME` with the validation code (e.g. `1a2b3c4d5e`):\n\n```php\n$botman-\u003eon(\"confirmation\", function($payload, $bot){\n    // Use $payload[\"group_id\"] to get group ID if required for computing the passphrase.\n    echo(\"REPLACE_ME\");\n});\n```\n\n- Click `Confirm` button.\n\n\n\n\n## Quick guide with examples\n*In usage examples, the used file is `routes/botman.php`.*\n\n### Sending simple message\nIf bot receives `Hello` message, it will answer `Hi, \u003cFirst Name\u003e`:\n```php\n$botman-\u003ehears('Hello', function ($bot) {\n    $bot-\u003ereply('Hi, '.$bot-\u003egetUser()-\u003egetFirstName());\n});\n```\n\n![Example image](./docs/6.png)\n\n### Typing activity\nBot will wait 10 seconds before answering the question:\n\n```php\n$botman-\u003ehears(\"What\\'s your favourite colour\\?\", function ($bot) {\n    $bot-\u003ereply('Let me think...');\n    $bot-\u003etypesAndWaits(10);\n    $bot-\u003ereply(\"I guess it's orange! 😄\");\n});\n```\n\n![Example image](./docs/7.png)\n\nAfter all, it will answer:\n\n![Example image](./docs/8.png)\n\n### Attaching image\nIf bot receives `Gimme some image` message, it will answer `Here it is!` with an attached image:\n\n```php\nuse BotMan\\BotMan\\Messages\\Attachments\\Image;\nuse BotMan\\BotMan\\Messages\\Outgoing\\OutgoingMessage;\n\n$botman-\u003ehears('Gimme some image', function ($bot) {\n    // Create attachment\n    $attachment = new Image('https://botman.io/img/logo.png');\n    // $attachment-\u003eaddExtras(\"vk_photo\", \"photo123456_123456\"); // Or send an already uploaded photo (driver will ignore image url)    \n\n    // Build message object\n    $message = OutgoingMessage::create('Here it is!')\n        -\u003ewithAttachment($attachment);\n\n    // Reply message object\n    $bot-\u003ereply($message);\n});\n```\n\n![Example image](./docs/9.png)\n\n### Attaching video\n\nExample of sending an already uploaded video:\n\n**Note**: uploading videos to VK is not supported by the driver yet.\n\n```php\nuse BotMan\\BotMan\\Messages\\Attachments\\Video;\nuse BotMan\\BotMan\\Messages\\Outgoing\\OutgoingMessage;\n\n$botman-\u003ehears('Gimme some video', function ($bot) {\n    // Create attachment\n    $attachment = new Video('http://unused-video-url');\n    // Attaching already uploaded videos is the ONLY way to send them (as for now):\n    $attachment-\u003eaddExtras(\"vk_video\", \"video-2000416976_41416976\"); // Send an already uploaded video (driver will ignore video url)\n\n    // Build message object\n    $message = OutgoingMessage::create('Here it is!')\n        -\u003ewithAttachment($attachment);\n\n    // Reply message object\n    $bot-\u003ereply($message);\n});\n```\n\n![Example image](./docs/10.png)\n\n### Attaching audio\n\nExample of sending an already uploaded audio:\n\n**Note**: uploading audio to VK is restricted by the platform.\n\n```php\nuse BotMan\\BotMan\\Messages\\Attachments\\Audio;\nuse BotMan\\BotMan\\Messages\\Outgoing\\OutgoingMessage;\n\n$botman-\u003ehears('Gimme some audio', function ($bot) {\n    // Create attachment\n                            // URL can be uploaded ONLY as voice message (due to restrictions of VK)\n    $attachment = new Audio('https://unused-audio-url');\n    $attachment-\u003eaddExtras(\"vk_audio\", \"audio371745438_456268888\"); // Send an already uploaded audio (driver will ignore audio url and vk_as_voice parameter)\n\n    // Build message object\n    $message = OutgoingMessage::create('Here it is!')\n        -\u003ewithAttachment($attachment);\n\n    // Reply message object\n    $bot-\u003ereply($message);\n});\n```\n\n![Example image](./docs/11.png)\n\n### Sending voice message\n\nVoice messages can be send using `Audio` with extra parameter `vk_as_voice = true`. \n\nExample of sending a voice message with message text:\n\n**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.\n\n```php\nuse BotMan\\BotMan\\Messages\\Attachments\\Audio;\nuse BotMan\\BotMan\\Messages\\Outgoing\\OutgoingMessage;\n\n$botman-\u003ehears('Sing me a song', function ($bot) {\n    // Create attachment\n                            // URL can be uploaded ONLY as voice message (due to restrictions of VK)\n    $attachment = new Audio('https://url-to-ogg-file');\n//  $attachment-\u003eaddExtras(\"vk_audio\", \"audio371745438_456268888\"); // Send an already uploaded audio (driver will ignore audio url and vk_as_voice parameter)\n    $attachment-\u003eaddExtras(\"vk_as_voice\", true);                    // Send as voice message (better to use *.ogg file)\n\n    // Build message object\n    $message = OutgoingMessage::create('Well...')\n        -\u003ewithAttachment($attachment);\n\n    // Reply message object\n    $bot-\u003ereply($message);\n});\n```\n\nDuring upload, the driver will send \"recording audio\" activity:\n\n![Example image](./docs/12.png)\n\nThe result:\n\n![Example image](./docs/13.png)\n\n### Attaching document (file)\n\nExample of sending file:\n\n**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.\n\n```php\nuse BotMan\\BotMan\\Messages\\Attachments\\File;\nuse BotMan\\BotMan\\Messages\\Outgoing\\OutgoingMessage;\n\n$botman-\u003ehears(\"Any files\\?\", function ($bot) {\n    $attachment = new File('https://url-to-file');\n//  $attachment-\u003eaddExtras(\"vk_doc\", \"doc123456_123456\"); // Send an already uploaded document (driver will ignore audio url and vk_doc_title, vk_doc_tags parameters)\n    $attachment-\u003eaddExtras(\"vk_doc_title\", \"Cool guy.gif\"); // Title\n    $attachment-\u003eaddExtras(\"vk_doc_tags\", \"cool, guy\"); // Document tags\n\n    // Build message object\n    $message = OutgoingMessage::create('Yep!')\n        -\u003ewithAttachment($attachment);\n\n    // Reply message object\n    $bot-\u003ereply($message);\n});\n```\n\nUploading a file will also trigger \"sending message\" activity.\n\n![Example image](./docs/14.png)\n\n### Attaching location\n\nExample of sending location (taken from BotMan docs):\n\n```php\nuse BotMan\\BotMan\\Messages\\Attachments\\Location;\nuse BotMan\\BotMan\\Messages\\Outgoing\\OutgoingMessage;\n\n$botman-\u003ehears('Any locations\\?', function($bot) {\n    // Create attachment\n    $attachment = new Location(61.766130, -6.822510, [\n        'custom_payload' =\u003e true,\n    ]);\n\n    // Build message object\n    $message = OutgoingMessage::create('Locations are also supported!')\n        -\u003ewithAttachment($attachment);\n\n    // Reply message object\n    $bot-\u003ereply($message);\n});\n```\n\nThe result:\n\n![Example image](./docs/15.png)\n\n### Additional parameters\n\nAdditional parameters are used to append or replace message request parameters.\n\n**Note:** `v` and `access_token` fields are ignored to be replaced. Change their parameters in `.env` file or in configuration array.\n\nExample of replacing message text:\n\n```php\n$botman-\u003ehears('Show me the replaced message', function($bot) {\n    $bot-\u003ereply(\"This string will be ignored\", [\n        \"message\" =\u003e \"This message string will be sent\"\n    ]);\n});\n```\n\n![The result](./docs/16.png)\n\nSee [messages.send method](https://vk.com/dev/messages.send) for more info.\n\n### Sending question buttons (simple keyboard)\n\nExample 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.\n\n```php\nuse BotMan\\BotMan\\Messages\\Outgoing\\Actions\\Button;\nuse BotMan\\BotMan\\Messages\\Outgoing\\Question;\n$botman-\u003ehears(\"List of functions\\?\", function ($bot) {\n    $question = Question::create('My list of functions:')\n        -\u003eaddButtons([\n            Button::create('Function 1')-\u003evalue('f1'),\n            Button::create('Function 2')-\u003evalue('f2'),\n            Button::create('Function 3')-\u003evalue('f3'),\n            Button::create('Function 4')-\u003evalue('f4'),\n            Button::create('Function 5')-\u003evalue('f5')\n        ]);\n\n    $bot-\u003eask($question, function ($answer) {\n        // Detect if button was clicked:\n        if ($answer-\u003eisInteractiveMessageReply()) {\n            $selectedValue = $answer-\u003egetValue(); // Contains button value e.g. 'f1', 'f2', ...\n            $selectedText = $answer-\u003egetText(); // Contains title e.g. 'Function 1', 'Function 2', ...\n        }\n    });\n});\n```\n\n![Example image](./docs/17.png)\n\n**Note**: don't use `$answer-\u003egetText()` for validation purposes as it can be changed by the client (user). Use `$answer-\u003egetValue()` instead.\n\n**Note**: better to send keyboards only in Conversation class, asking a question with buttons. See more [here](https://botman.io/2.0/conversations).\n\n### Customizing the question buttons (simple keyboard)\n\n**⚠ \\[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.\n\nYou can also change button's properties via additional parameters such as colour:\n\n```php\n//...\n$botman-\u003ehears(\"List of functions\\?\", function ($bot) {\n    $question = Question::create('My list of functions:')\n        -\u003eaddButtons([\n            Button::create('Function 1')-\u003evalue('f1')-\u003eadditionalParameters([\n                \"color\" =\u003e \"secondary\" // Colour (see available colours here - https://vk.com/dev/bots_docs_3)\n            ]),\n            Button::create('Function 2')-\u003evalue('f2')-\u003eadditionalParameters([\n                \"color\" =\u003e \"negative\"\n            ]),\n            Button::create('Function 3')-\u003evalue('f3')-\u003eadditionalParameters([\n                \"color\" =\u003e \"primary\"\n            ]),\n            Button::create('Function 4')-\u003evalue('f4')-\u003eadditionalParameters([\n                \"color\" =\u003e \"primary\"\n            ]),\n            Button::create('Function 5')-\u003evalue('f5')-\u003eadditionalParameters([\n                \"color\" =\u003e \"primary\"\n            ])\n        ]);\n\n    $bot-\u003eask($question, function ($answer) {\n        //...\n    });\n});\n```\n\n![Example image](./docs/18.png)\n\nSee [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.\n\n\n### Sending native keyboard\n\nNative keyboard can be send as an additional parameter **(works only for VK!)**:\n\n```php\nuse BotMan\\Drivers\\VK\\Extensions\\VKKeyboard;\nuse BotMan\\Drivers\\VK\\Extensions\\VKKeyboardButton;\nuse BotMan\\Drivers\\VK\\Extensions\\VKKeyboardRow;\n\n$botman-\u003ehears('keyboard', function(BotMan $bot) {\n    $keyboard = new VKKeyboard();\n    $keyboard-\u003esetInline(false);    // Setting the inline mode (\"inline\" parameter)\n    $keyboard-\u003esetOneTime(false);   // Setting \"one_time\" parameter\n    \n    $keyboard-\u003eaddRows(\n        // Top row\n        new VKKeyboardRow([\n            // Text example\n            ( new VKKeyboardButton() )-\u003esetColor(\"primary\")-\u003esetText(\"Sample text\")-\u003esetValue(\"button1\"),\n            // UTF-8 text example\n            ( new VKKeyboardButton() )-\u003esetColor(\"primary\")-\u003esetText(\"Текст для примера\")-\u003esetValue(\"button2\"),\n        ]),\n        // Middle row\n        new VKKeyboardRow([\n            // Long text trim example\n            ( new VKKeyboardButton() )\n                // Colour (see available colours here - https://vk.com/dev/bots_docs_3)                \n                -\u003esetColor(\"default\")\n                \n                // Long text will be trimed with ellipsis at the end of the label\n                -\u003esetText(\"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam nec ultrices purus, ut sollicitudin arcu.\")\n\n                // Set button value\n                -\u003esetValue(\"button3\"), \n        ]),\n        // Bottom row\n        new VKKeyboardRow([\n            // Emoji example\n            ( new VKKeyboardButton() )-\u003esetColor(\"negative\")-\u003esetText(\"⛔\")-\u003esetValue(\"button4\"),\n            ( new VKKeyboardButton() )-\u003esetColor(\"primary\")-\u003esetText(\"⚠\")-\u003esetValue(\"button5\"),\n            ( new VKKeyboardButton() )-\u003esetColor(\"positive\")-\u003esetText(\"✅\")-\u003esetValue(\"button6\"),\n        ])\n    );\n\n    $bot-\u003ereply(\"Native keyboard:\", [\n        \"keyboard\" =\u003e $keyboard-\u003etoJSON()\n    ]);\n});\n```\n\n![Example image](./docs/19.png)\n\nYou can also send a Question with additional parameters with keyboard:\n\n```php\n// ...\n$bot-\u003eask($question, function ($answer) {\n    // Detect if button was clicked:\n    if ($answer-\u003eisInteractiveMessageReply()) {\n        $selectedValue = $answer-\u003egetValue(); // Contains button value e.g. 'f1', 'f2', ...\n        $selectedText = $answer-\u003egetText(); // Contains title e.g. 'Function 1', 'Function 2', ...\n    }\n}, [\n    \"keyboard\" =\u003e $keyboard-\u003etoJSON()\n]);\n// ...\n```\n\n### Listening for images\n\nNative way for receiving images.\n\n**Note**: no message text will be provided via `receivesImages()` method.\n\n```php\n$botman-\u003ereceivesImages(function($bot, $images) {\n    foreach ($images as $image) {\n        $url = $image-\u003egetUrl(); // The direct url\n        $title = $image-\u003egetTitle(); // The title (empty string as titles are not supported by VK)\n        $payload = $image-\u003egetPayload(); // The original payload\n\n        $bot-\u003ereply(\"Detected image: {$url}\");\n    }\n});\n```\n\n![Example image](./docs/20.png)\n\n### Listening for videos\n\nNative way for receiving videos.\n\n**Note**: no message text will be provided via `receivesVideos()` method.\n\n```php\n$botman-\u003ereceivesVideos(function($bot, $videos) {\n    foreach ($videos as $video) {\n        $url = $video-\u003egetUrl(); // The direct url\n        $payload = $video-\u003egetPayload(); // The original payload\n\n        // For YouTube videos title can be accessed in the following way:\n        $bot-\u003ereply(\"Detected video: {$payload[\"title\"]}\");\n    }\n});\n```\n\n![Example image](./docs/21.png)\n\n### Listening for audio\n\nNative way for receiving audio.\n\n**Note**: no message text will be provided via `receivesAudio()` method.\n\n```php\n$botman-\u003ereceivesAudio(function($bot, $audios) {\n    foreach ($audios as $audio) {\n        $url = $audio-\u003egetUrl(); // The direct url\n        $payload = $audio-\u003egetPayload(); // The original payload\n\n        $bot-\u003ereply(\"Detected audio: {$url}\");\n    }\n});\n```\n\n![Example image](./docs/22.png)\n\n### Listening for documents (files)\n\nNative way for receiving files.\n\n**Note**: no message text will be provided via `receivesFiles()` method.\n\n```php\n$botman-\u003ereceivesFiles(function($bot, $files) {\n    foreach ($files as $file) {\n        $url = $file-\u003egetUrl(); // The direct url\n        $payload = $file-\u003egetPayload(); // The original payload\n\n        $bot-\u003ereply(\"Detected file (document): {$url}\");\n    }\n});\n```\n\n![Example image](./docs/23.png)\n\n### Listening for location\n\nNative way for receiving location.\n\n**Note**: no message text will be provided via `receivesLocation()` method.\n\n```php\n$botman-\u003ereceivesLocation(function($bot, $location) {\n    $lat = $location-\u003egetLatitude();\n    $lng = $location-\u003egetLongitude();\n\n    $bot-\u003ereply(\"Detected location: $lat $lng\");\n});\n```\n\n![Example image](./docs/24.png)\n\n### Receiving messages with mixed attachments\n\nMessage with mixed attachments can be asked via `hears()`, `ask()` or `fallback()` method (`IncomingMessage` with message text and attachments with all supported types).\n\nExample with video and image attachments:\n\n```php\n$botman-\u003ehears('I have both image and video for you.', function ($bot) {\n    $bot-\u003ereply(\"Cool!\");\n\n    // Scanning for images\n    $images = $bot-\u003egetMessage()-\u003egetImages() ?? [];\n    foreach ($images as $image) {\n\n        $url = $image-\u003egetUrl();\n\n        $bot-\u003ereply(\"Image found: {$url}\");\n    }\n\n    // Scanning for videos\n    $videos = $bot-\u003egetMessage()-\u003egetVideos() ?? [];\n    foreach ($videos as $video) {\n        $payload = $video-\u003egetPayload();\n\n        $bot-\u003ereply(\"Video found: {$payload[\"title\"]}\");\n    }\n});\n```\n\n![Example image](./docs/25.png)\n\n### Retrieving extra user data\n\nExtra user fields should be defined in `.env` file and can be accessed via `getUser()-\u003egetInfo()` method.\n\n**⚠ \\[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-\u003egetUser()-\u003egetUsername()` to get username.\n\nExample contents of `.env`:\n\n```dotenv\n# ...\nVK_USER_FIELDS=\"photo_200_orig\"\n# ...\n```\n\nExample route:\n\n```php\n$botman-\u003ehears('Gimme my photo_200_orig', function ($bot) {\n    $bot-\u003ereply('Here it is: '.$bot-\u003egetUser()-\u003egetInfo()[\"photo_200_orig\"]);\n});\n```\n\n![Example image](./docs/26.png)\n\nMultiple fields should be comma-separated:\n\n```dotenv\n# ...\nVK_USER_FIELDS=\"photo_200_orig, photo_50\"\n# ...\n```\n\nSee [User object](https://vk.com/dev/fields) for available fields.\n\n\n### Retrieving extra client information\n\nInformation about supported features of user's VK client can be accessed via `$bot-\u003egetMessage()-\u003egetExtras(\"client_info\")`:\n\n**Note:** the feature works only with new messages sent (`message_new` event).\n\n```php\n$botman-\u003ehears('my info', function(BotMan $bot) {\n    // Prints raw \"client_info\" array\n    $bot-\u003ereply(print_r($bot-\u003egetMessage()-\u003egetExtras(\"client_info\"), true));\n});\n```\n\n![The reply](./docs/27.png)\n\n\nSee [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.\n\n\n### Mark seen example\n\nEvery message will be marked as seen even if there is no response for it:\n\n```php\n$botman-\u003ehears(\"Don\\'t answer me\", function ($bot) {\n    // Do nothing\n});\n```\n\n![Example image](./docs/28.png)\n\n### Listening to events\n\nList of supported events:\n- `confirmation`\n- `message_allow`\n- `message_deny`\n- `message_typing_state`        *\n- `message_event`               *\n- `photo_new`\n- `photo_comment_new`\n- `photo_comment_edit`\n- `photo_comment_restore`\n- `photo_comment_delete`\n- `audio_new`\n- `video_new`\n- `video_comment_new`\n- `video_comment_edit`\n- `video_comment_restore`\n- `video_comment_delete`\n- `wall_post_new`\n- `wall_repost`\n- `wall_reply_new`\n- `wall_reply_edit`\n- `wall_reply_restore`\n- `wall_reply_delete`\n- `board_post_new`\n- `board_post_edit`\n- `board_post_restore`\n- `board_post_delete`\n- `market_comment_new`\n- `market_comment_edit`\n- `market_comment_restore`\n- `market_comment_delete`\n- `market_order_new`            *\n- `market_order_edit`           *\n- `group_leave`\n- `group_join`\n- `user_block`\n- `user_unblock`\n- `poll_vote_new`\n- `group_officers_edit`\n- `group_change_settings`\n- `group_change_photo`\n- `vkpay_transaction`           *\n- `app_payload`                 *\n- `like_add`                    *\n- `like_remove`                 *\n\n\\* - missing english version in VK docs, but feature exists (as for 14.08.2020)\n\n\\*\\* - missing in VK docs, but feature exists (as for 14.08.2020)\n\n**Note:** events of `message_new`, `message_reply`, `message_edit` are assessable via Hearing Messages functions (e.g. `$botman-\u003ehear()`).\n\n[Full list of events (VK docs)](https://vk.com/dev/groups_events)\n\nExample of sending message when the typing state changed:\n\n```php\n$botman-\u003eon(\"message_typing_state\", function($payload, $bot){\n    // $payload is an array of the event object (\"Object field format\"),\n    // excepting Confirmation event, where $payload contains full root JSON schema.\n    // See https://vk.com/dev/groups_events for more info\n    $bot-\u003esay(\"Hey! You're typing something!\", $payload[\"from_id\"]);\n});\n```\n\n**Note:** `$bot-\u003ereply()` is not supported here, use `$bot-\u003esay(\"...\", $peer_id_from_data)` instead.\n\nThe result:\n\n![The result image](./docs/29.png)\n\nℹ️ Don't forget to enable a `Typing status` event in `Callback API -\u003e Event types` tab. \n\n![Typing status enabled](./docs/30.png)\n\n### Sending low-level API requests\n\nExample of sending a sticker via `$bot-\u003esendRequest()`:\n\n**Note:** it is also possible to send stickers via additional parameters.\n\n```php\n$botman-\u003ehears('sticker', function($bot) {\n    // API method\n    $endpoint = \"messages.send\";\n    \n    // Arguments (\"v\" and \"access_token\" are set by driver, no need to define)\n    $arguments = [\n         \"peer_id\" =\u003e $bot-\u003egetUser()-\u003egetId(), // User ID\n         \"sticker_id\" =\u003e 12, // Sticker ID\n         \"random_id\" =\u003e 0 // required by VK API\n    ];\n\n    $test = $bot-\u003esendRequest($endpoint, $arguments);\n    // $test now equals to [\"response\" =\u003e 1234];\n});\n```\n\nThe result:\n\n![The result of sticker sending](./docs/31.png)\n\n### Sending carousels\n\nThe driver also ships with implemented wrapper for attaching native carousel objects.\n\nFor example:\n\n```php\nuse BotMan\\Drivers\\VK\\Extensions\\VKKeyboardButton;\nuse BotMan\\Drivers\\VK\\Extensions\\VKCarousel;\nuse BotMan\\Drivers\\VK\\Extensions\\VKCarouselActionOpenLink;\nuse BotMan\\Drivers\\VK\\Extensions\\VKCarouselElement;\n\n$botman-\u003ehears('carousel', function($bot) {\n    $carousel = new VKCarousel();\n\n    for($i = 1; $i \u003c= 10; $i++){\n        $carousel-\u003eaddElements(\n            new VKCarouselElement(\n                \"Element {$i}\",\n                \"Description {$i}\",\n                [\n                    ( new VKKeyboardButton() )\n                        -\u003esetColor(\"secondary\")-\u003esetText(\"Button {$i}\")-\u003esetValue(\"button1\")\n                ],\n                \"-00000_11111\", // This is an example icon ID:\n                                // replace `00000` with community ID, the `11111` - with image ID\n                new VKCarouselActionOpenLink(\"https://some-url/\")\n            )\n        );\n    }\n\n    $bot-\u003ereply(\"Native carousel:\", [\n        \"template\" =\u003e $carousel-\u003etoJSON()\n    ]);\n});\n```\n\n![Example result](./docs/32.png)\n\n## See also\n- [VK documentation for developers](https://vk.com/dev/callback_api)\n- [New VK documentation for developers](https://dev.vk.com/)\n- [BotMan documentation](https://botman.io/2.0/welcome)\n\n## License\nVK Community Callback driver is made under the terms of MIT license. BotMan is free software distributed under the terms of the MIT license.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyageorgiy%2Fbotman-vk-community-callback-driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyageorgiy%2Fbotman-vk-community-callback-driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyageorgiy%2Fbotman-vk-community-callback-driver/lists"}