Struct Bot 

pub struct Bot<C> { /* private fields */ }

A cheaply cloneable handle to initialized SimpleX bot.

Implementations

impl<C> Bot<C>

pub fn client(&self) -> &C

pub fn user_id(&self) -> UserId

impl<C: ClientApi> Bot<C>

pub async fn init(client: C, settings: BotSettings) -> Result<Self, C::Error>

pub fn wrap_client<W, F>(self, wrap: F) -> Bot<W>

where W: ClientApi, F: FnOnce(C) -> W,

This method allows ot wrap or replace the underlying bot client.

You can define your own clients implementing the ClientApi trait and then you can extend the bot functionalitty by implementing extension methods on Bot<YourCustomClient> type.

pub fn default_preferences() -> Preferences

Conservative bot preferences: full-delete on, everything else off.

pub fn default_profile(name: impl Into<String>) -> Profile

Minimal bot profile with Self::default_preferences and Bot peer type.

pub fn info( &self, ) -> impl Future<Output = Result<Arc<ActiveUserResponse>, C::Error>>

Get full bot user info

pub fn initiate_connection( &self, link: impl Into<String>, ) -> impl Future<Output = Result<UndocumentedResponse<ConnectResponse>, C::Error>>

Initiates the connection sequence.

• If contact is already connected returns either UndocumentedResponse::Documented with ConnectResponse::ContactAlreadyExists or UndocumentedResponse::Undocumented with some other responses(this is an upstream mistake, SimpleX docs don’t list all possible responses for this method).

• If contact is not connected returns UndocumentedResponse::Documented with one of the remaining ConnectResponse variants. The implementation must listen for crate::events::ContactConnected or crate::events::UserJoinedGroup to confirm the connection.

pub fn check_connection_plan( &self, target: impl Into<String>, ) -> impl Future<Output = Result<Arc<ConnectionPlanResponse>, C::Error>>

Inspect a SimpleX target before connecting: resolves its type (name, contact address, group link, or 1-time invitation) and reports whether the bot is already connected via it.

pub async fn initiate_connection_if<F: FnOnce(&ConnectionPlan) -> bool>( &self, link: impl Into<String>, predicate: F, ) -> Result<Connection, C::Error>

Initiate a connection only if ConnectionPlan satisfies the predicate. For example, this can be used to connect strictly via one-time links:

let conn = bot.initiate_connection_if(
    link,
    |plan| matches!(plan, ConnectionPlan::InvitationLink { .. })
).await?;

if conn.is_rejected() {
    return Err("not a one-time link");
}

pub fn create_invitation_link( &self, ) -> impl Future<Output = Result<(String, Arc<InvitationResponse>), C::Error>>

Create one-time-invitation link. Can be used for admin-access or for private connections with other bots. The connection.pcc_conn_id can be matched with crate::types::Connection::conn_id to recognize the user connected by this link when handling the crate::events::ContactConnected event(see crate::events::ContactConnected::contact)

pub fn create_address(&self) -> impl Future<Output = Result<String, C::Error>>

pub fn address(&self) -> impl Future<Output = Result<String, C::Error>>

Throws crate::types::errors::StoreError::UserContactLinkNotFound if bot doesn’t have an address. Use Self::get_or_create_address to ensure that address is available

pub async fn get_or_create_address(&self) -> Result<String, C::Error>

pub fn configure_address( &self, settings: AddressSettings, ) -> impl Future<Output = Result<(), C::Error>>

pub fn publish_address( &self, ) -> impl Future<Output = Result<Arc<UserProfileUpdatedResponse>, C::Error>>

Make address visible in bot/user profile

pub fn hide_address( &self, ) -> impl Future<Output = Result<Arc<UserProfileUpdatedResponse>, C::Error>>

Hide address from bot/user profile

pub fn delete_address(&self) -> impl Future<Output = Result<(), C::Error>>

pub fn profile(&self) -> impl Future<Output = Result<Profile, C::Error>>

pub async fn update_profile<F>( &self, updater: F, ) -> Result<ApiUpdateProfileResponse, C::Error>

where F: 'static + Send + FnOnce(&mut Profile),

Fetches the current profile and applies updater to it before saving.

pub fn set_display_name( &self, name: impl Into<String>, ) -> impl Future<Output = Result<ApiUpdateProfileResponse, C::Error>>

pub fn set_full_name( &self, full_name: impl Into<String>, ) -> impl Future<Output = Result<ApiUpdateProfileResponse, C::Error>>

pub fn set_bio( &self, bio: impl Into<String>, ) -> impl Future<Output = Result<ApiUpdateProfileResponse, C::Error>>

pub fn set_description( &self, description: impl Into<String>, ) -> impl Future<Output = Result<ApiUpdateProfileResponse, C::Error>>

pub async fn set_avatar( &self, avatar: ImagePreview, ) -> Result<ApiUpdateProfileResponse, C::Error>

Set the bot/user avatar

pub fn set_peer_type( &self, peer_type: ChatPeerType, ) -> impl Future<Output = Result<ApiUpdateProfileResponse, C::Error>>

Set account type Bot or Person

pub fn set_badge( &self, badge: BadgeProof, ) -> impl Future<Output = Result<ApiUpdateProfileResponse, C::Error>>

pub fn set_contact_domain( &self, domain: SimplexDomainClaim, ) -> impl Future<Output = Result<ApiUpdateProfileResponse, C::Error>>

pub fn clear_contact_domain( &self, ) -> impl Future<Output = Result<ApiUpdateProfileResponse, C::Error>>

pub fn set_preferences( &self, preferences: Preferences, ) -> impl Future<Output = Result<ApiUpdateProfileResponse, C::Error>>

Set global preferences

pub async fn update_preferences<F>( &self, updater: F, ) -> Result<ApiUpdateProfileResponse, C::Error>

where F: 'static + Send + FnOnce(&mut Preferences),

Update global preferences via closure accepting current preferences

pub fn set_contact_preferences<CID: Into<ContactId>>( &self, contact_id: CID, preferences: Preferences, ) -> impl Future<Output = Result<Arc<ContactPrefsUpdatedResponse>, C::Error>>

Set preferences for particular contact

pub async fn tweak_preferences_for_contact<CID: Into<ContactId>, F>( &self, contact_id: CID, updater: F, ) -> Result<Arc<ContactPrefsUpdatedResponse>, C::Error>

where F: 'static + Send + FnOnce(&mut Preferences),

Tweak global preferences for particular contact via closure accepting current global preferences

pub fn contacts(&self) -> impl Future<Output = Result<Vec<Contact>, C::Error>>

Get all contacts known to the bot(connected or not)

pub fn groups(&self) -> impl Future<Output = Result<Vec<GroupInfo>, C::Error>>

Get all groups known to the bot

pub fn accept_contact<CRID: Into<ContactRequestId>>( &self, contact_request_id: CRID, ) -> impl Future<Output = Result<Arc<AcceptingContactRequestResponse>, C::Error>>

Accept contact request

pub fn reject_contact<CRID: Into<ContactRequestId>>( &self, contact_request_id: CRID, ) -> impl Future<Output = Result<Arc<ContactRequestRejectedResponse>, C::Error>>

Reject contact request

pub fn send_msg<CID: Into<ChatId>, M: MessageLike>( &self, chat_id: CID, msg: M, ) -> MessageBuilder<'_, C, M::Kind>

Send a message. See the messages module for details

pub fn multicast<I, M>( &self, chat_ids: I, msg: M, ) -> MulticastBuilder<'_, I, C, M::Kind>

where I: IntoIterator<Item = ChatId>, M: MessageLike,

Send the same message to multiple recepients

pub fn chat_ids( &self, ) -> impl Future<Output = Result<impl Iterator<Item = ChatId>, C::Error>>

Returns a list of all known chat IDs

pub async fn chat_ids_with<F>( &self, f: F, ) -> Result<impl 'static + Send + Iterator<Item = ChatId>, C::Error>

where F: 'static + Send + FnMut(&ChatId) -> bool,

Returns a list of all known chat IDs matching the filter f.

pub fn prepare_broadcast<M: MessageLike>( &self, msg: M, ) -> impl Future<Output = Result<MulticastBuilder<'_, impl 'static + Send + Iterator<Item = ChatId>, C, M::Kind>, C::Error>>

Generate a MulticastBuilder that is ready to send messages to all known chats

bot.prepare_broadcast("Hey, what's up?!")
   .await
   .deliver()
   .await?;

pub fn prepare_broadcast_with<M, F>( &self, msg: M, f: F, ) -> impl Future<Output = Result<MulticastBuilder<'_, impl 'static + Send + Iterator<Item = ChatId>, C, M::Kind>, C::Error>>

where F: 'static + Send + FnMut(&ChatId) -> bool, M: MessageLike,

Generate a MulticastBuilder that is ready to send messages to chats matching the filter

bot.prepare_broadcast_with("What do you think about this logo?", |chat| chat.is_direct())
   .await
   .with_image(Image::new("logo.jpg"))
   .deliver()
   .await?;

pub fn update_msg<CID: Into<ChatId>, MID: Into<MessageId>>( &self, chat_id: CID, message_id: MID, new_content: MsgContent, ) -> impl Future<Output = Result<ApiUpdateChatItemResponse, C::Error>>

pub fn delete_msg<CID: Into<ChatId>, MID: Into<MessageId>>( &self, chat_id: CID, message_id: MID, mode: CIDeleteMode, ) -> impl Future<Output = Result<Arc<ChatItemsDeletedResponse>, C::Error>>

pub fn batch_delete_msgs<CID: Into<ChatId>, I: IntoIterator<Item = MessageId>>( &self, chat_id: CID, message_ids: I, mode: CIDeleteMode, ) -> impl Future<Output = Result<Arc<ChatItemsDeletedResponse>, C::Error>>

pub fn batch_msg_reactions<CID: Into<ChatId>, MID: Into<MessageId>, I: IntoIterator<Item = Reaction>>( &self, chat_id: CID, message_id: MID, reactions: I, ) -> impl Future<Output = Vec<Result<Arc<ChatItemReactionResponse>, C::Error>>>

Applies multiple reactions to a message. Returns one result per reaction.

pub fn update_msg_reaction<CID: Into<ChatId>, MID: Into<MessageId>>( &self, chat_id: CID, message_id: MID, reaction: Reaction, ) -> impl Future<Output = Vec<Result<Arc<ChatItemReactionResponse>, C::Error>>>

pub fn accept_file<FID: Into<FileId>>( &self, file_id: FID, ) -> AcceptFileBuilder<'_, C>

Starts background file download. Catch RcvFile* events to track the progress

pub fn reject_file<FID: Into<FileId>>( &self, file_id: FID, ) -> impl Future<Output = Result<CancelFileResponse, C::Error>>

pub fn delete_chat<CID: Into<ChatId>>( &self, chat_id: CID, mode: DeleteMode, ) -> impl Future<Output = Result<ApiDeleteChatResponse, C::Error>>

pub fn create_group( &self, profile: GroupProfile, ) -> impl Future<Output = Result<Arc<GroupCreatedResponse>, C::Error>>

Create a new group. The bot’s user becomes the owner.

pub fn create_public_group<I: IntoIterator<Item = RelayId>>( &self, relay_ids: I, profile: GroupProfile, ) -> impl Future<Output = Result<ApiNewPublicGroupResponse, C::Error>>

Create a new public group with relay members. The bot’s user becomes the owner. Relay IDs can be obtained from Bot::default_relays

pub fn set_auto_accept_member_contacts( &self, on: bool, ) -> impl Future<Output = Result<Arc<CmdOkResponse>, C::Error>>

Enable or disable automatically accepting contacts from group members.

pub fn add_member<GID: Into<GroupId>, CID: Into<ContactId>>( &self, group_id: GID, contact_id: CID, role: GroupMemberRole, ) -> impl Future<Output = Result<Arc<SentGroupInvitationResponse>, C::Error>>

Sends a group invitation to a contact.

pub fn join_group<GID: Into<GroupId>>( &self, group_id: GID, ) -> impl Future<Output = Result<Arc<UserAcceptedGroupSentResponse>, C::Error>>

Accepts a pending group invitation.

pub fn accept_member<GID: Into<GroupId>, MID: Into<MemberId>>( &self, group_id: GID, member_id: MID, role: GroupMemberRole, ) -> impl Future<Output = Result<Arc<MemberAcceptedResponse>, C::Error>>

Confirms a pending group membership request.

pub fn set_members_role<GID: Into<GroupId>, I: IntoIterator<Item = MemberId>>( &self, group_id: GID, member_ids: I, role: GroupMemberRole, ) -> impl Future<Output = Result<Arc<MembersRoleUserResponse>, C::Error>>

pub fn set_member_role<GID: Into<GroupId>, MID: Into<MemberId>>( &self, group_id: GID, member_id: MID, role: GroupMemberRole, ) -> impl Future<Output = Result<Arc<MembersRoleUserResponse>, C::Error>>

pub fn block_members_for_all<GID: Into<GroupId>, I: IntoIterator<Item = MemberId>>( &self, group_id: GID, member_ids: I, ) -> impl Future<Output = Result<Arc<MembersBlockedForAllUserResponse>, C::Error>>

Blocks members so their messages are hidden for everyone in the group.

pub fn unblock_members_for_all<GID: Into<GroupId>, I: IntoIterator<Item = MemberId>>( &self, group_id: GID, member_ids: I, ) -> impl Future<Output = Result<Arc<MembersBlockedForAllUserResponse>, C::Error>>

Reverses a previous block_members_for_all.

pub fn block_member_for_all<GID: Into<GroupId>, MID: Into<MemberId>>( &self, group_id: GID, member_id: MID, ) -> impl Future<Output = Result<Arc<MembersBlockedForAllUserResponse>, C::Error>>

Blocks a member so their messages are hidden for everyone in the group.

pub fn unblock_member_for_all<GID: Into<GroupId>, MID: Into<MemberId>>( &self, group_id: GID, member_id: MID, ) -> impl Future<Output = Result<Arc<MembersBlockedForAllUserResponse>, C::Error>>

Reverses a previous block_member_for_all.

pub fn remove_members<GID: Into<GroupId>, I: IntoIterator<Item = MemberId>>( &self, group_id: GID, member_ids: I, ) -> impl Future<Output = Result<Arc<UserDeletedMembersResponse>, C::Error>>

Removes members from the group, preserving their past messages.

pub fn remove_members_with_messages<GID: Into<GroupId>, I: IntoIterator<Item = MemberId>>( &self, group_id: GID, member_ids: I, ) -> impl Future<Output = Result<Arc<UserDeletedMembersResponse>, C::Error>>

Removes members from the group and deletes their messages.

pub fn remove_member<GID: Into<GroupId>, MID: Into<MemberId>>( &self, group_id: GID, member_id: MID, ) -> impl Future<Output = Result<Arc<UserDeletedMembersResponse>, C::Error>>

Removes a member from the group, preserving their past messages.

pub fn remove_member_with_messages<GID: Into<GroupId>, MID: Into<MemberId>>( &self, group_id: GID, member_id: MID, ) -> impl Future<Output = Result<Arc<UserDeletedMembersResponse>, C::Error>>

Removes a member from the group and deletes their messages.

pub fn leave_group<GID: Into<GroupId>>( &self, group_id: GID, ) -> impl Future<Output = Result<Arc<LeftMemberUserResponse>, C::Error>>

pub fn list_members<GID: Into<GroupId>>( &self, group_id: GID, ) -> impl Future<Output = Result<Vec<GroupMember>, C::Error>>

pub fn moderate_messages<GID: Into<GroupId>, I: IntoIterator<Item = MessageId>>( &self, group_id: GID, message_ids: I, ) -> impl Future<Output = Result<Arc<ChatItemsDeletedResponse>, C::Error>>

Deletes messages for all group members. Requires admin or owner role.

pub fn moderate_message<GID: Into<GroupId>, MID: Into<MessageId>>( &self, group_id: GID, message_id: MID, ) -> impl Future<Output = Result<Arc<ChatItemsDeletedResponse>, C::Error>>

Deletes a message for all group members. Requires admin or owner role.

pub fn update_group_profile<GID: Into<GroupId>>( &self, group_id: GID, profile: GroupProfile, ) -> impl Future<Output = Result<Arc<GroupUpdatedResponse>, C::Error>>

pub async fn update_group_profile_with<GID, F>( &self, group_id: GID, updater: F, ) -> Result<Arc<GroupUpdatedResponse>, C::Error>

where GID: Into<GroupId>, F: FnOnce(&mut GroupProfile),

WARN: the current impl does full group scan because the Bot API doesn’t expose a method to get gropu by ID.

pub fn update_group_preferences<GID, F>( &self, group_id: GID, updater: F, ) -> impl Future<Output = Result<Arc<GroupUpdatedResponse>, C::Error>>

where GID: Into<GroupId>, F: FnOnce(&mut GroupPreferences),

pub fn set_group_sign_messages<GID: Into<GroupId>>( &self, group_id: GID, on: bool, ) -> impl Future<Output = Result<Arc<GroupUpdatedResponse>, C::Error>>

pub fn set_group_custom_data<GID: Into<GroupId>>( &self, group_id: GID, data: Option<JsonObject>, ) -> impl Future<Output = Result<Arc<CmdOkResponse>, C::Error>>

Stores arbitrary app-defined JSON on the group. Pass None to clear it.

pub fn set_contact_custom_data<CID: Into<ContactId>>( &self, contact_id: CID, data: Option<JsonObject>, ) -> impl Future<Output = Result<Arc<CmdOkResponse>, C::Error>>

Stores arbitrary app-defined JSON on the contact. Pass None to clear it.

pub fn create_group_link<GID: Into<GroupId>>( &self, group_id: GID, role: GroupMemberRole, ) -> impl Future<Output = Result<Arc<GroupLinkCreatedResponse>, C::Error>>

pub fn set_group_link_role<GID: Into<GroupId>>( &self, group_id: GID, role: GroupMemberRole, ) -> impl Future<Output = GroupLinkResult<C>>

Changes the default role assigned to members who join via the group link.

pub fn delete_group_link<GID: Into<GroupId>>( &self, group_id: GID, ) -> impl Future<Output = Result<Arc<GroupLinkDeletedResponse>, C::Error>>

pub fn get_group_link<GID: Into<GroupId>>( &self, group_id: GID, ) -> impl Future<Output = GroupLinkResult<C>>

pub fn get_group_relays<GID: Into<GroupId>>( &self, group_id: GID, ) -> impl Future<Output = GetGroupRelaysResponse<C>>

pub fn add_group_relays<GID: Into<GroupId>, I: IntoIterator<Item = RelayId>>( &self, group_id: GID, relay_ids: I, ) -> impl Future<Output = AddGroupRelaysResponse<C>>

pub fn add_group_relay<GID: Into<GroupId>, RID: Into<RelayId>>( &self, group_id: GID, relay_id: RID, ) -> impl Future<Output = AddGroupRelaysResponse<C>>

pub fn get_chats( &self, pagination: PaginationByTime, query: ChatListQuery, ) -> impl Future<Output = Result<Arc<ApiChatsResponse>, C::Error>>

Get chats with time-based pagination. Prefer this over Bot::contacts / Bot::groups for large databases as it avoids loading all records into memory at once.

pub fn default_relays( &self, ) -> impl Future<Output = Result<Vec<RelayId>, C::Error>>

Get a list of default user relays

pub fn accept_remote_ctrl( &self, handle: &CtrlHandle, link: &str, ) -> impl Future<Output = Result<(), CtrlError<C::Error>>>

Accept an incoming remote control session from a SimpleX Desktop client.

Requires a CtrlHandle installed on the event stream via EventStream::hook_remote_control.

Deadlock warning

See CtrlHandle::accept_remote_ctrl.

impl<C: XftpExt> Bot<C>

pub fn download_file<FID: Into<FileId>>( &self, file_id: FID, ) -> DownloadFileBuilder<'_, C>

Available on crate feature xftp only.

impl Bot<XftpClient<Client>>

pub fn shutdown(self) -> impl Future<Output = ()>

Available on crate feature websocket only.

impl Bot<XftpClient<Client>>

pub fn shutdown(self) -> impl Future<Output = ()>

Available on crate feature ffi only.

Trait Implementations

impl<C: Clone> Clone for Bot<C>

fn clone(&self) -> Bot<C>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.