Events

An event is a map with a type key. Subscriptions to the events in the table are set in contributes.events.

Subscription events

Event	Permission	When it arrives	Chat-bound
message.new	messages.read	a new message	yes
message.edited	messages.read	a message was edited	yes
message.deleted	messages.read	a message was deleted	yes
message.reaction	messages.read	a reaction on a message	yes
message.pinned	messages.read	a message was pinned/unpinned (`pinned: true	false`)
chat.opened	chats.active	the user opened a chat: chat, chat_title, optional topic	yes
chat.typing	chats.activity	chat, user, action, cancelled	yes
chat.read	chats.activity	chat, read_till, outbox	yes
chat.member	chats.activity	chat, user, joined	yes
chat.title_changed	chats.activity	chat, title, old_title	yes
user.status	users.presence	user, status, last_seen	no
story.new	stories.read	chat, story_id, date (the content is not passed)	yes
call.incoming	calls.activity	chat, user (the same id), incoming	yes
call.ended	calls.activity	chat, user, incoming, reason, duration	yes
app.focus / app.blur	app.activity	the window gained/lost focus	no

Chat-bound events arrive within the scope the user chose and never come from secret chats.

call.ended.reason: ended, busy, failed, other_device. Statuses a user hides, bots and your own status are not reported through user.status.

Events that need no subscription

They arrive in response to user actions or your requests:

Event	Source
command	a /name command (name, args, chat, optional topic and reply_to)
menu.click	a menu item (id, surface)
badge.click	a badge click (id, user, surface; on the message surface also chat and message)
timer	a timer fired (id)
plugin.message	from, data from another plugin
settings.open, settings.*	the settings page
dialog.*, window.*	dialogs and windows, including *.long_click
toast.click, toast.close	a toast button (id, reason)
translate.request	ticket, items, to, format (always "plain")
ai.request	ticket, text and parameters
message.outgoing, message.incoming	message hooks
call.result	result of an async call (ticket)

Payload details

The exact keys of every event are in Event payloads; the shapes of query results are in Data shapes. Per-operation details: messages, chats, users and more, system, network, files and media.

Message fields

message.* events carry at least chat (the chat id). The other fields (message id, text, entities in UTF-16, author, media and so on) depend on the event; to see the exact set, print(event) in your plugin or use the host’s development mode.