Download the PHP package yageorgiy/botman-vk-community-callback-driver without Composer

BotMan VK Community Callback driver

BotMan driver to connect VK Community with BotMan via Callback API.

Contributing

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

Support

Table of driver's features:

* - uploading feature with user token is under construction

Setup

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.

Then tick all the permissions in the dialog box.

Copy your created token by clicking Show link.

Installing the driver

Require the driver via composer:

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

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

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: https://example.com/botman, http://some.mysite.ru/botman).
• Fill the Secret key field (required for driver!):

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

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

• Click Confirm button.

Quick guide with examples

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

Sending simple message

If bot receives Hello message, it will answer Hi, <First Name>:

Typing activity

Bot will wait 10 seconds before answering the question:

After all, it will answer:

Attaching image

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

Attaching video

Example of sending an already uploaded video:

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

Attaching audio

Example of sending an already uploaded audio:

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

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 for more info.

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

The result:

Attaching document (file)

Example of sending file:

Note: not all files are available to upload. See Uploading documents for more info.

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

Attaching location

Example of sending location (taken from BotMan docs):

The result:

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:

See messages.send method for more info.

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.

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.

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:

See VK documentation page 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

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

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

Listening for images

Native way for receiving images.

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

Listening for videos

Native way for receiving videos.

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

Listening for audio

Native way for receiving audio.

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

Listening for documents (files)

Native way for receiving files.

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

Listening for location

Native way for receiving location.

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

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:

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:

Example route:

Multiple fields should be comma-separated:

See User object for available fields.

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).

See Information about features available to the user for more details.

Mark seen example

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

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)

Example of sending message when the typing state changed:

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

The result:

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

Sending low-level API requests

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

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

The result:

Sending carousels

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

For example:

See also

• VK documentation for developers
• New VK documentation for developers
• BotMan documentation

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.