Skip to main content
Examples on this page target source snapshot 7e5c198e, not a crates.io release. Use the current API guide to select the matching dependency.

create

Validate the name with CreateCommunityOptions::new(name)?. Use a typed GroupDescription for the optional description. The options and output DTOs are non-exhaustive; use constructors, then supported field mutation or builders.

Recover partial creation

Creation and description configuration are separate remote operations. CommunityError::ConfigurationFailed { created_jid, step, source } means the community already exists. Resume configuration on that JID; blindly repeating create can create a duplicate. The error preserves the failed step and its GroupError cause. For description recovery use groups().set_description(created_jid, Some(description), PreviousDescription::Resolve) to read the current optimistic concurrency token. This is a returned-error contract, not a cancellation or rollback guarantee.

create_subgroup_with_options

create_subgroup(name, participants, parent) uses default subgroup options. For explicit visibility use CreateSubgroupOptions::new(name, participants, parent).with_visibility(SubgroupVisibility). The result is CreateCommunityResult { metadata, .. }; there is no separate gid output field. link_subgroups(parent, &[Jid]) uses default visibility. link_subgroups_with_options accepts LinkSubgroupOptions::new(jid, visibility). A batch can contain both successes and failures; inspect linked_jids and every SubgroupFailure’s jid and code. Failures are named records, not (Jid, u32) tuples. Inspect unlinked_jids and failed_groups for the same partial-result behavior. Do not retry successful entries merely because another entry failed.

Query and manage

get_subgroup_participant_counts returns Result<Vec<(Jid, u32)>, CommunityError>: each tuple contains a subgroup JID and its participant count. This differs from link/unlink SubgroupFailure records. get_subgroups returns paginated CommunitySubgroup records with typed GroupParticipants. Check has_more before deciding your list is complete. Membership approval is a distinct error for a subgroup join; it does not prove the caller joined. For a community parent picture use the pictures facade with an explicit Community target. Reactions, comments and encrypted edits address announcement posts through their message references; see message actions and the community guide.

Source reference

Community inputs, partial errors and output DTOs

Community creation defaults

CreateCommunityOptions defaults the closed: bool field to true. By default, the Create IQ includes the parent approval attribute and uses the supplied name as its subject. To opt out, set the public closed field to false after construction. The Create IQ then omits the parent approval attribute. Existing partial-configuration results remain authoritative if creation succeeds before a follow-up operation fails.