MlsGroup - LibXMTP

MlsGroup Struct

MlsGroup<Context> is the primary interface for group conversations in LibXMTP.

pub struct MlsGroup<Context> {
    pub group_id: Vec<u8>,
    pub dm_id: Option<String>,
    pub conversation_type: ConversationType,
    pub created_at_ns: i64,
    pub context: Context,
    // Private fields
}

Fields

Field	Type	Description
`group_id`	`Vec<u8>`	Unique identifier for the group
`dm_id`	`Option<String>`	DM identifier (for DM conversations only)
`conversation_type`	`ConversationType`	Type of conversation (Group, DM, etc.)
`created_at_ns`	`i64`	Creation timestamp in nanoseconds
`context`	`Context`	Shared context providing dependencies

Traits

Clone - Groups can be cloned (shares underlying context)
PartialEq, Eq - Equality based on group_id
Hash - Hashing based on group_id
Debug - Formatted debug output

Constructor Methods

new

pub fn new(
    context: Context,
    group_id: Vec<u8>,
    dm_id: Option<String>,
    conversation_type: ConversationType,
    created_at_ns: i64,
) -> Self

Creates a new group instance without database validation. Parameters:

context - Shared context
group_id - Group identifier
dm_id - Optional DM identifier
conversation_type - Conversation type
created_at_ns - Creation timestamp

Returns: New MlsGroup instance

new_cached

pub fn new_cached(
    context: Context,
    group_id: &[u8],
) -> Result<(Self, StoredGroup), StorageError>

Creates a group instance from the database with validation. Parameters:

context - Shared context
group_id - Group identifier

Returns: Tuple of (MlsGroup, StoredGroup) Errors:

NotFound::GroupById - Group not found in database

create_and_insert

pub(crate) fn create_and_insert(
    context: Context,
    conversation_type: ConversationType,
    permissions_policy_set: PolicySet,
    opts: GroupMetadataOptions,
    oneshot_message: Option<OneshotMessage>,
) -> Result<Self, GroupError>

Creates a new group and saves it to the database. Parameters:

context - Shared context
conversation_type - Must not be ConversationType::Dm
permissions_policy_set - Permission policies for the group
opts - Metadata options (name, description, etc.)
oneshot_message - Optional oneshot message

Returns: New MlsGroup instance Side Effects:

Creates OpenMLS group
Stores group in database
Sets consent state to Allowed

create_dm_and_insert

pub(crate) fn create_dm_and_insert(
    context: &Context,
    membership_state: GroupMembershipState,
    dm_target_inbox_id: InboxId,
    opts: DMMetadataOptions,
    existing_group_id: Option<&[u8]>,
) -> Result<Self, GroupError>

Creates a new DM conversation and saves it to the database. Parameters:

context - Shared context
membership_state - Initial membership state
dm_target_inbox_id - Target inbox ID for the DM
opts - DM metadata options
existing_group_id - Optional existing group ID (for backup restoration)

Returns: New MlsGroup instance

Messaging Methods

send_message

pub async fn send_message(
    &self,
    message: &[u8],
    opts: SendMessageOpts,
) -> Result<Vec<u8>, GroupError>

Sends a message and waits for publishing to complete. Parameters:

message - Message content bytes (typically encoded EncodedContent)
opts - Send options (includes should_push flag)

Returns: Message ID bytes Errors:

GroupError::GroupInactive - Group is not active

Side Effects:

Updates installations if needed
Publishes all pending intents
Sets group consent state to Allowed

send_message_optimistic

pub fn send_message_optimistic(
    &self,
    message: &[u8],
    opts: SendMessageOpts,
) -> Result<Vec<u8>, GroupError>

Sends a message optimistically, returning immediately without waiting for publishing. Parameters:

message - Message content bytes
opts - Send options

Returns: Message ID bytes Note: Message is queued locally but not published. Call publish_messages() to publish.

prepare_message_for_later_publish

pub fn prepare_message_for_later_publish(
    &self,
    message: &[u8],
    should_push: bool,
) -> Result<Vec<u8>, GroupError>

Prepares a message for later publishing without creating an intent. Parameters:

message - Message content bytes
should_push - Whether to send push notification when publishing

Returns: Message ID bytes Note: Message is stored with Unpublished status. Use publish_stored_message to publish.

publish_stored_message

pub async fn publish_stored_message(
    &self,
    message_id: &[u8],
) -> Result<(), GroupError>

Publishes a previously stored message by ID. Parameters:

message_id - ID of the message to publish

Errors:

GroupError::GroupInactive - Group is not active
NotFound::MessageById - Message not found

Note: No-op if message is already published.

publish_messages

pub async fn publish_messages(&self) -> Result<(), GroupError>

Publishes all unpublished messages by syncing until all intents are resolved. Side Effects:

Updates installations if needed
Sets group consent state to Allowed

delete_message

pub fn delete_message(&self, message_id: Vec<u8>) -> Result<Vec<u8>, GroupError>

Deletes a message by its ID. Parameters:

message_id - Raw bytes of the message ID

Returns: ID of the deletion message Authorization:

Only the original sender or a super admin can delete messages

Wire Protocol: The message ID is hex-encoded for wire transmission. When processing incoming deletions, the hex string is decoded back to bytes for database lookups. Errors:

DeleteMessageError::MessageNotFound - Message not found
DeleteMessageError::NotAuthorized - Not the sender or super admin
DeleteMessageError::MessageAlreadyDeleted - Message already deleted
DeleteMessageError::NonDeletableMessage - Message type cannot be deleted

Query Methods

find_messages

pub fn find_messages(
    &self,
    args: &MsgQueryArgs,
) -> Result<Vec<StoredGroupMessage>, GroupError>

Queries the database for stored messages. Parameters:

args - Query arguments (time range, kind, delivery status, limit)

Returns: Vector of StoredGroupMessage

count_messages

pub fn count_messages(
    &self,
    args: &MsgQueryArgs,
) -> Result<i64, GroupError>

Counts the number of stored messages matching the criteria. Parameters:

args - Query arguments

Returns: Message count

find_messages_with_reactions

pub fn find_messages_with_reactions(
    &self,
    args: &MsgQueryArgs,
) -> Result<Vec<StoredGroupMessageWithReactions>, GroupError>

Queries messages with their associated reactions. Parameters:

args - Query arguments

Returns: Vector of StoredGroupMessageWithReactions

find_enriched_messages

pub fn find_enriched_messages(
    &self,
    args: &MsgQueryArgs,
) -> Result<Vec<DecodedMessage>, EnrichMessageError>

Queries enriched messages with reactions, replies, and deletion status. Parameters:

args - Query arguments

Returns: Vector of DecodedMessage

get_last_read_times

pub fn get_last_read_times(
    &self,
) -> Result<LatestMessageTimeBySender, GroupError>

Gets the last read receipt times by sender. Returns: Map of latest message times by sender

Membership Methods

add_members_by_identity

pub async fn add_members_by_identity(
    &self,
    account_identifiers: &[Identifier],
) -> Result<UpdateGroupMembershipResult, GroupError>

Adds members to the group by account address. Parameters:

account_identifiers - Vector of account identifiers to add

Returns: UpdateGroupMembershipResult with added/removed members and errors Errors:

GroupError::UserLimitExceeded - Would exceed MAX_GROUP_SIZE
GroupError::AddressNotFound - Some addresses not found

Note: Also updates existing members’ installations.

add_members

pub async fn add_members<S: AsIdRef>(
    &self,
    inbox_ids: impl AsRef<[S]>,
) -> Result<UpdateGroupMembershipResult, GroupError>

Adds members to the group by inbox IDs. Parameters:

inbox_ids - Vector of inbox IDs to add

Returns: UpdateGroupMembershipResult

remove_members_by_identity

pub async fn remove_members_by_identity(
    &self,
    account_addresses_to_remove: &[Identifier],
) -> Result<(), GroupError>

Removes members from the group by account addresses. Parameters:

account_addresses_to_remove - Vector of account identifiers to remove

remove_members

pub async fn remove_members(
    &self,
    inbox_ids: &[InboxIdRef<'_>],
) -> Result<(), GroupError>

Removes members from the group by inbox IDs. Parameters:

inbox_ids - Slice of inbox ID references to remove

update_installations

pub async fn update_installations(&self) -> Result<(), GroupError>

Checks the network for identity updates and adds/removes installations accordingly. Note: This is automatically called periodically during send_message.

leave_group

pub async fn leave_group(&self) -> Result<(), GroupError>

Leaves the group (sends a leave request). Errors:

GroupLeaveValidationError::NotAGroupMember - Not a member
GroupLeaveValidationError::SingleMemberLeaveRejected - Only member
GroupLeaveValidationError::DmLeaveForbidden - Cannot leave DMs
GroupLeaveValidationError::SuperAdminLeaveForbidden - Super admins must be demoted first

remove_members_pending_removal

pub async fn remove_members_pending_removal(&self) -> Result<(), GroupError>

Removes all members from the pending removal list. Authorization: Only admins and super admins can call this.

cleanup_pending_removal_list

pub async fn cleanup_pending_removal_list(&self) -> Result<(), GroupError>

Removes members from the pending removal list who are no longer in the group.

Utility Methods

load

pub fn load(&self) -> Result<StoredGroup, StorageError>

Loads the group reference from the local database. Returns: StoredGroup with database fields Errors:

NotFound::GroupById - Group not found

SendMessageOpts

pub struct SendMessageOpts {
    pub should_push: bool,
}

Options for sending messages.

UpdateGroupMembershipResult

pub struct UpdateGroupMembershipResult {
    pub added_members: Vec<Installation>,
    pub removed_members: Vec<Installation>,
    pub members_with_errors: Vec<MemberError>,
}

Result of membership update operations.

MsgQueryArgs

Arguments for querying messages:

Time range filtering
Message kind filtering
Delivery status filtering
Limit and offset

Source References

Definition: crates/xmtp_mls/src/groups/mod.rs:122
Constructor: crates/xmtp_mls/src/groups/mod.rs:290
Messaging: crates/xmtp_mls/src/groups/mod.rs:588
Membership: crates/xmtp_mls/src/groups/mod.rs:970

Core Crates

API Clients

Client

Groups

Messages

Identity

​MlsGroup Struct

​Fields

​Traits

​Constructor Methods

​new

​new_cached

​create_and_insert

​create_dm_and_insert

​Messaging Methods

​send_message

​send_message_optimistic

​prepare_message_for_later_publish

​publish_stored_message

​publish_messages

​delete_message

​Query Methods

​find_messages

​count_messages

​find_messages_with_reactions

​find_enriched_messages

​get_last_read_times

​Membership Methods

​add_members_by_identity

​add_members

​remove_members_by_identity

​remove_members

​update_installations

​leave_group

​remove_members_pending_removal

​cleanup_pending_removal_list

​Utility Methods

​load

​Related Types

​SendMessageOpts

​UpdateGroupMembershipResult

​MsgQueryArgs

​Source References

Build docs developers (and LLMs) love