Skip to main content
Group chats allow multiple users to communicate together in a single conversation. Unlike communities, group chats are simpler structures with a flat participant list and basic ownership model.

​
Group Type

Group chats are represented by the Group type: 
message Group {
  // @snowflake<Chat>
  fixed64 id = 1;
  string name = 2;
  bool owner = 3;
  // @snowflake<User>
  repeated fixed64 participant_ids = 4;
}

​
Fields

​
id
fixed64
Snowflake Chat ID - Unique identifier for this group chat
​
name
string
Display name of the group chat
​
owner
bool
Whether the current user is the owner of this group. Only the owner can update settings and remove members
​
participant_ids
fixed64[]
Array of Snowflake User IDs representing all members of the group chat

​
CreateChat

Create a new group chat with specified users and a name. 
message CreateChat {
  repeated refs.UserRef users = 1;
  string name = 2;
}

​
Parameters

​
users
UserRef[]
required
Array of user references to add as initial participants in the group chat. You can specify users by ID or username
​
name
string
required
Display name for the group chat

​
Response

Returns a types.Group object representing the newly created group chat. The creator automatically becomes the owner.

​
Notes

  • The creating user is automatically added as a participant and becomes the owner
  • All specified users are added immediately without requiring acceptance
  • Group chat IDs are Snowflakes generated server-side

​
UpdateChat

Update settings for an existing group chat. Only the owner can update group settings. 
message UpdateChat {
  refs.ChatRef chat_ref = 1;
  optional string name = 2;
}

​
Parameters

​
chat_ref
ChatRef
required
Reference to the group chat to update
​
name
string
New display name for the group chat. If not provided, the name remains unchanged

​
Response

Returns a chats.Chat object with the updated group information: 
message Chat {
  types.Conversation chat = 1;
  optional types.Message message = 2;
  repeated types.User users = 3;
  optional types.Group group = 4;
  optional types.Channel channel = 5;
}

​
Permissions

  • Only the group owner (owner = true) can update the group chat
  • Attempting to update a group you don’t own will result in an error

​
RemoveChatMember

Remove a participant from a group chat. Only the owner can remove members. 
message RemoveChatMember {
  refs.ChatRef chat_ref = 1;
  // @snowflake<User>
  fixed64 user_id = 2;
}

​
Parameters

​
chat_ref
ChatRef
required
Reference to the group chat
​
user_id
fixed64
required
Snowflake User ID of the member to remove from the group

​
Response

Returns empty on success.

​
Permissions

  • Only the group owner can remove members
  • Users can remove themselves (leave the group) regardless of ownership
  • Removing the last member may delete the group

​
Adding Members

Members can be added to an existing group chat through invites. See the Conversations page for information on creating and managing chat invites.

​
Group Chat Workflow

​
Creating a Group

  1. Call CreateChat with initial participants and a name
  2. Server creates the group and assigns you as owner
  3. Receive the Group object with the new group ID
  4. All participants receive a notification about the new group

​
Managing Participants

  1. Add members: Create a chat invite with CreateChatInvite
  2. Remove members: Call RemoveChatMember with the user’s ID
  3. Leave group: Call RemoveChatMember with your own user ID
  4. View members: Access participant_ids in the Group object

​
Updating Settings

  1. Call UpdateChat with the group’s ChatRef
  2. Provide new values for fields you want to change
  3. Omit fields that should remain unchanged
  4. Only the owner can perform updates

​
Group vs Direct Messages

FeatureDirect MessageGroup Chat
Participants2 users2+ users
NameDerived from participantsCustom name
OwnershipNo ownerHas owner
Member managementN/AOwner can add/remove
SettingsPer-user onlyGroup-level settings
InvitesNot neededCan create invites

Build docs developers (and LLMs) love

Get started for freeTalk to us