Skip to main content

ChatRef

A polymorphic reference to any type of chat (user DM, channel, group, or self).

Usage

ChatRef is used throughout the protocol as input to specify which chat an operation targets. It allows methods to work uniformly across different chat types (DMs, channels, groups).

Protocol Definition

message ChatRef {
  oneof ref {
    UserRef user = 1;
    ChannelRef channel = 2;
    GroupRef group = 3;
    RefSelf self = 4;
  }
}

UserRef

Reference to a direct message conversation with a user.

Example Usage

Use UserRef when sending a direct message to another user:
{
  "chat_ref": {
    "user": {
      "user_id": 123456789012345678
    }
  }
}

Protocol Definition

message UserRef {
  fixed64 user_id = 1;  // @snowflake<User>
}

ChannelRef

Reference to a channel within a community.

Example Usage

Use ChannelRef when sending a message to a community channel:
{
  "chat_ref": {
    "channel": {
      "community_id": 123456789012345678,
      "channel_id": 987654321098765432
    }
  }
}

Protocol Definition

message ChannelRef {
  fixed64 community_id = 1; // @snowflake<Community>
  fixed64 channel_id = 2;   // @snowflake<Channel>
}

GroupRef

Reference to a group chat.

Example Usage

Use GroupRef when sending a message to a group chat:
{
  "chat_ref": {
    "group": {
      "group_id": 123456789012345678
    }
  }
}

Protocol Definition

message GroupRef {
  fixed64 group_id = 1;  // @snowflake<Chat>
}

RefSelf

Reference to the user’s own saved messages / notes to self. This is an empty message type used as a marker in the ChatRef oneof.

Example Usage

Use RefSelf when sending a message to your own saved messages:
{
  "chat_ref": {
    "self": {}
  }
}

Protocol Definition

message RefSelf {}

StickerPackRef

Reference to a sticker pack.

Usage

Used to reference sticker packs when retrieving, adding, or removing stickers.

Protocol Definition

message StickerPackRef {
  fixed64 id = 1;  // @snowflake<StickerPack>
  // TODO auth
}

Notes

Snowflake IDs

All ID fields use the fixed64 type and are snowflake IDs. Snowflakes are 64-bit integers that encode:
  • Timestamp (milliseconds since epoch)
  • Worker ID
  • Sequence number
This provides chronological ordering and distributed ID generation.

Oneof Semantics

The ChatRef message uses Protocol Buffers’ oneof feature, meaning exactly one of the four reference types must be set. Setting multiple fields or none will result in invalid messages.

Input vs Output

The comment in refs.proto notes that ChatRef is “only meant to be used for input.” In practice:
  • Input: Use ChatRef when specifying which chat to target in requests
  • Output: Server responses typically include the full Message/Channel/Group object with embedded IDs rather than ChatRef

Build docs developers (and LLMs) love