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 withCreateCommunityOptions::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
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.
unlink_subgroups
Inspectunlinked_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 DTOsCommunity 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.