Event types

message.created

Emitted for direct messages, @botname mentions in groups, and replies to bot messages. data includes chat_id, chat_type, session_id, message, and a limited actor.

button.clicked

Emitted for callback buttons. In groups actor identifies only the user who clicked; responses may be scoped to that user. Repeated clicks are allowed unless single_use is enabled.

Lifecycle events

Install, restart, removal, and availability changes may use dedicated system events. Persist UUIDs rather than mutable display names or usernames.

SDK practice

Route by type and keep a safe fallback for unknown events. This lets the platform add compatible event types without breaking the bot.

Treat actor in button.clicked as bot-scoped. Do not correlate it with a global account without an explicit verification flow.

const handlers = {
  'message.created': async event => {
    const { chat_id, session_id, message, actor } = event.data;
    console.log(event.id, chat_id, session_id, message.text, actor.id);
    return {};
  }
};