API Reference

Bot

Message

Event Reference

This page outlines the different types of events listened by Bot.

There are two ways to register an event, the first way is through the use of Bot.listen(). The second way is through subclassing Bot and overriding the specific events. For example:

import vk_botting

class MyBot(vk_botting.Bot):
    async def on_message_new(self, message):
        if message.from_id == self.group.id:
            return

        if message.text.startswith('$hello'):
            await message.send('Hello World!')

If an event handler raises an exception, on_error() will be called to handle it, which defaults to print a traceback and ignoring the exception.

Warning

All the events must be a |coroutine_link|_. If they aren’t, then you might get unexpected errors. In order to turn a function into a coroutine they must be async def functions.

on_ready(): Called when the bot is done preparing the data received from VK. Usually after login is successful and the Bot.group and co. are filled up.

on_error(event, \*args, \*\*kwargs)

Usually when an event raises an uncaught exception, a traceback is printed to stderr and the exception is ignored. If you want to change this behaviour and handle the exception for whatever reason yourself, this event can be overridden. Which, when done, will suppress the default action of printing the traceback.

The information of the exception raised and the exception itself can be retrieved with a standard call to sys.exc_info().

If you want exception to propagate out of the Bot class you can define an on_error handler consisting of a single empty py:raise. Exceptions raised by on_error will not be handled in any way by Bot.

Parameters:

event (str) – The name of the event that raised the exception.
args – The positional arguments for the event that raised the exception.
kwargs – The keyword arguments for the event that raised the exception.

on_command_error(ctx, error)

An error handler that is called when an error is raised inside a command either through user input error, check failure, or an error in your own code.

A default one is provided (Bot.on_command_error()).

Parameters:

ctx (Context) – The invocation context.
error (CommandError derived) – The error that was raised.

on_command(ctx)

An event that is called when a command is found and is about to be invoked.

This event is called regardless of whether the command itself succeeds via error or completes.

Parameters:: ctx (Context) – The invocation context.

on_command_completion(ctx)

An event that is called when a command has completed its invocation.

This event is called only if the command succeeded, i.e. all checks have passed and the user input it correctly.

Parameters:: ctx (Context) – The invocation context.

on_message_new(message)

Called when bot receives a message.

Parameters:: message (message.Message) – Received message.

on_message_event(event)

Called when a callback button is pressed.

Parameters:: event – Received event.

on_message_reply(message)

Called when bot replies with a message.

Parameters:: message (message.Message) – Sent message.

on_message_edit(message)

Called when message is edited.

Parameters:: message (message.Message) – Edited message.

on_message_typing_state(state)

Called when typing state is changed (e.g. someone starts typing).

Parameters:: state (states.State) – New state.

on_conversation_start(message)

Called when user starts conversation using special button.

Parameters:: message (message.Message) – Message sent when conversation is started.

on_chat_kick_user(message)

Called when user is kicked from the chat.

Parameters:: message (message.Message) – Message sent when user is kicked.

on_chat_invite_user(message)

Called when user is invited to the chat.

Parameters:: message (message.Message) – Message sent when user is invited.

on_chat_invite_user_by_link(message)

Called when user is invited to the chat by link.

Parameters:: message (message.Message) – Message sent when user is invited.

on_chat_photo_update(message)

Called when chat photo is updated.

Parameters:: message (message.Message) – Message sent when photo is updated.

on_chat_photo_remove(message)

Called when chat photo is removed.

Parameters:: message (message.Message) – Message sent when photo is removed.

on_chat_create(message)

Called when chat is created.

Parameters:: message (message.Message) – Message sent when chat is created.

on_chat_title_update(message)

Called when chat title is updated.

Parameters:: message (message.Message) – Message sent when chat title is updated.

on_chat_pin_message(message)

Called when message is pinned in chat.

Parameters:: message (message.Message) – Message sent when message is pinned in chat.

on_chat_unpin_message(message)

Called when message is unpinned in chat.

Parameters:: message (message.Message) – Message sent when message is unpinned in chat.

on_message_allow(user)

Called when user allows getting messages from bot.

Parameters:: user (user.User) – User who allowed messages.

on_message_deny(user)

Called when user denies getting messages from bot.

Parameters:: user (user.User) – User who denied messages.

on_photo_new(photo)

Called when new photo is uploaded to bot group.

Parameters:: photo (attachments.Photo) – Photo that got uploaded.

on_audio_new(audio)

Called when new audio is uploaded to bot group.

Parameters:: audio (attachments.Audio) – Audio that got uploaded.

on_video_new(video)

Called when new video is uploaded to bot group.

Parameters:: video (attachments.Video) – Video that got uploaded.

on_photo_comment_new(comment)

Called when new comment is added to photo.

Parameters:: comment (group.PhotoComment) – Comment that got send.

on_photo_comment_edit(comment)

Called when comment on photo gets edited.

Parameters:: comment (group.PhotoComment) – Comment that got edited.

on_photo_comment_restore(comment)

Called when comment on photo is restored.

Parameters:: comment (group.PhotoComment) – Comment that got restored.

on_photo_comment_delete(comment)

Called when comment on photo is deleted.

Parameters:: comment (group.DeletedPhotoComment) – Comment that got deleted.

on_video_comment_new(comment)

Called when new comment is added to video.

Parameters:: comment (group.VideoComment) – Comment that got send.

on_video_comment_edit(comment)

Called when comment on video gets edited.

Parameters:: comment (group.VideoComment) – Comment that got edited.

on_video_comment_restore(comment)

Called when comment on video is restored.

Parameters:: comment (group.VideoComment) – Comment that got restored.

on_video_comment_delete(comment)

Called when comment on video is deleted.

Parameters:: comment (group.DeletedVideoComment) – Comment that got deleted.

on_market_comment_new(comment)

Called when new comment is added to market.

Parameters:: comment (group.MarketComment) – Comment that got send.

on_market_comment_edit(comment)

Called when comment on market gets edited.

Parameters:: comment (group.MarketComment) – Comment that got edited.

on_market_comment_restore(comment)

Called when comment on market is restored.

Parameters:: comment (group.MarketComment) – Comment that got restored.

on_market_comment_delete(comment)

Called when comment on market is deleted.

Parameters:: comment (group.DeletedMarketComment) – Comment that got deleted.

on_board_post_new(comment)

Called when new post is added to board.

Parameters:: comment (group.BoardComment) – New post on the board.

on_board_post_edit(comment)

Called when post on board gets edited.

Parameters:: comment (group.BoardComment) – Post that got edited.

on_board_post_restore(comment)

Called when post on board is restored.

Parameters:: comment (group.BoardComment) – Post that got restored.

on_board_post_delete(comment)

Called when post on board is deleted.

Parameters:: comment (group.DeletedBoardComment) – Post that got deleted.

on_wall_post_new(post)

Called when new post in added to wall.

Parameters:: post (group.Post) – Post that got added.

on_wall_repost(post)

Called when wall post is reposted.

Parameters:: post (group.Post) – Post that got reposted.

on_wall_reply_new(comment)

Called when new comment is added to wall.

Parameters:: comment (group.WallComment) – Comment that got send.

on_wall_reply_edit(comment)

Called when comment on wall gets edited.

Parameters:: comment (group.WallComment) – Comment that got edited.

on_wall_reply_restore(comment)

Called when comment on wall is restored.

Parameters:: comment (group.WallComment) – Comment that got restored.

on_wall_reply_delete(comment)

Called when comment on wall is deleted.

Parameters:: comment (group.DeletedWallComment) – Comment that got deleted.

on_group_join(user, join_type)

Called when user joins bot group.

Parameters:

user (user.User) – User that joined the group.
join_type (str) – User join type. Can be ‘join’ if user just joined, ‘unsure’ for events, ‘accepted’ if user was invited, ‘approved’ if user join request was approved or ‘request’ if user requested to join

on_group_leave(user, self)

Called when user leaves bot group.

Parameters:

user (user.User) – User that left the group.
self (bool) – If user left on their own (True) or was kicked (False).

on_user_block(user)

Called when user is blocked in bot group.

Parameters:: user (user.BlockedUser) – User that was blocked.

on_user_unblock(user)

Called when user is unblocked in bot group.

Parameters:: user (user.UnblockedUser) – User that was unblocked.

on_poll_vote_new(vote)

Called when new poll vote is received.

Parameters:: vote (group.PollVote) – New vote.

on_group_officers_edit(edit)

Called when group officers are edited.

Parameters:: edit (group.OfficersEdit) – New edit.

on_unknown(payload)

Called when unknown event is received.

Parameters:: payload (dict) – Json payload of the event.

Cogs

Cog

CogMeta

Abstract Base Classes

An py:abstract base class (also known as an abc) is a class that models can inherit to get their behaviour. The Python implementation of an abc is slightly different in that you can register them at run-time. Abstract base classes cannot be instantiated. They are mainly there for usage with py:isinstance() and py:issubclass().

This library has a module related to abstract base classes, some of which are actually from the abc standard module, others which are not.

Utility Classes

Attachment

Keyboard

Cooldown

VK Models

Models are classes that are received from VK and are not meant to be created by the user of the library.

Danger

The classes listed below are not intended to be created by users and are also read-only.

For example, this means that you should not make your own User instances nor should you modify the User instance yourself.

API Reference

Bot

Message

Event Reference

Cogs

Cog

CogMeta

Abstract Base Classes

Utility Classes

Attachment

Keyboard

Cooldown

VK Models

User

Group

Message

MessageEvent

Exceptions

Additional Classes