Events & Permissions

Robots interact with your server through events and permissions. Events are notifications about things that happen. Permissions control what data the robot can access and what actions it can perform.

Event Types

There are 12 event types that robots can subscribe to:

Message Events

Event	Description	Payload includes
`room.message`	A message was sent in a room	Room ID, sender, content, timestamp
`room.message.edited`	A message was edited	Room ID, message ID, new content, editor
`room.message.deleted`	A message was deleted	Room ID, message ID, deleter

Voice Events

Event	Description	Payload includes
`voice.join`	A user joined a voice room	Room ID, user ID, username
`voice.leave`	A user left a voice room	Room ID, user ID, username, duration

Member Events

Event	Description	Payload includes
`member.join`	A new member joined the server	User ID, username, join timestamp
`member.leave`	A member left the server	User ID, username
`member.role_changed`	A member’s role was updated	User ID, old role, new role

Room Events

Event	Description	Payload includes
`room.created`	A new room was created	Room ID, name, creator
`room.deleted`	A room was deleted	Room ID, name

Other Events

Event	Description	Payload includes
`presence.update`	A member’s online status changed	User ID, status (online/offline/idle)
`server.updated`	Server settings were changed	Changed fields, updater

Permissions

There are 6 permission levels that control what a robot can access:

Permission	Description
`read_messages`	Read message content from rooms. Required to receive message events with full content.
`send_messages`	Send, edit, and delete the robot’s own messages in rooms.
`read_members`	Access the server member list and receive member join/leave events.
`read_voice`	Receive voice room join and leave events.
`read_rooms`	Access the room list and receive room created/deleted events.
`read_presence`	Receive member presence (online/offline/idle) updates.

Event-to-Permission Mapping

Each event requires a specific permission. If a robot does not have the required permission, the event will not be delivered even if the robot has subscribed to it.

Event	Required Permission
`room.message`	`read_messages`
`room.message.edited`	`read_messages`
`room.message.deleted`	`read_messages`
`voice.join`	`read_voice`
`voice.leave`	`read_voice`
`member.join`	`read_members`
`member.leave`	`read_members`
`member.role_changed`	`read_members`
`room.created`	`read_rooms`
`room.deleted`	`read_rooms`
`presence.update`	`read_presence`
`server.updated`	`read_rooms`

How Event Subscriptions Work

When you create or update a robot, you select which events the robot should receive. This is a two-layer system:

Permissions determine what the robot is allowed to access
Subscriptions determine which events are actually delivered

Both must be in place for an event to reach your robot. For example, if a robot has the read_messages permission but is not subscribed to room.message, it will not receive message events. Conversely, if it is subscribed to room.message but lacks the read_messages permission, the event will be filtered out.

This design lets you grant broad permissions while receiving only the specific events you care about, reducing noise in your event stream.

Event Payload Format

All events follow a consistent JSON structure:

{
  "id": "evt_01H1234567890",
  "type": "room.message",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "serverId": "srv_abc123",
  "data": {
    "roomId": "room_xyz",
    "senderId": "usr_456",
    "senderName": "Alice",
    "content": "Hello from the room!",
    "messageId": "msg_789"
  }
}

The id field is globally unique and can be used for deduplication. The timestamp is in ISO 8601 format. The data field contains event-specific information that varies by event type.

Best Practices

Subscribe only to events you need. Unnecessary subscriptions increase noise and consume your rate limit quota on webhook deliveries.
Grant minimal permissions. A notification bot that only sends messages needs send_messages and nothing else.
Use event IDs for deduplication. In rare cases (webhook retries, SSE reconnection), you may receive the same event twice. Use the id field to detect and skip duplicates.
Handle unknown event types gracefully. New event types may be added in the future. Your handler should ignore events it does not recognize rather than crashing.