* core, ui: chatItemUpdated event has the previous item Apps change counters by the difference between the previous and the new item, and insert an updated item only when the update created it. * core, ui: a recreated item is sent as newChatItems An update of a locally deleted message creates it again and sends it as a new item, so chatItemUpdated always has the previous item and the apps never insert on an update. * core, ui: previous item is optional and has no chat info Events from older remote hosts decode without it; the apps then insert the item if it is not loaded and change no counters. * core: catch-up subscriber gets an edited history post as a new item * ui: updates in another profile do not notify, as on iOS * core, ui: one type for the updated item and its previous version AChatItemUpdate has the chat info, the new item and the previous item with the same chat type and direction. Its JSON is the JSON of AChatItem with an optional prevChatItem; the event keeps the key chatItem. * core: tested event key, previous item reactions, cleared mentions One function renames the event field to chatItem for JSON and docs, and the test checks the wire key and compatibility with AChatItem. The previous item of a direct edit has its reactions. An edit that removes all mentions sends the item without them. * core: test that an edit removing mentions sends the item without them * core: event JSON field mapping inline in the TH options, for the Windows build * core: file chat item update checked in one store transaction * core: test that a file reset by unknown relays sends its previous item * core, ui: chatItemUpdated event key chatItemUpdate * core, ui: chatItemUpdated always has the previous item * ci: mcp scope tests the plugin with its published dependencies * core: mention of the user follows edits of a group message * core: previous item of a prohibited file is read before the prohibition * android, desktop: missed call check inline, counter test with core pairs * ios: spec link of the chatItemUpdated event * core: mention edits in support chats update members requiring attention * core: one rule for the mention of the user in received and edited items * core: record item events of updates for app tests * android, desktop: remove the missed call notification of updates, never shown * android, desktop: test item updates on events recorded by the core * ios: test item updates on events recorded by the core * docs: plan of app tests of item updates, recording tests in the CI guide * core: record the response to an update after its item status is final * ios: notification manager replaceable in tests * ios: test notifications of updates and the update response * android, desktop: test the recorded update response * docs: plan with iOS notifications and the update response * core: recorded response to an update of a sent message
20 KiB
API Events
This file is generated automatically.
- Main event
- Other events
- Main event
- Other events
- Main events
- Other events
- Main events
- Other events
- AcceptingContactRequest
- AcceptingBusinessRequest
- ContactConnecting
- BusinessLinkConnecting
- JoinedGroupMemberConnecting
- GroupLinkConnecting
Contact connection events
Bots must use these events to process connecting users.
Most bots enable auto-accept and don't need to accept connections via commands.
You may create bot SimpleX address manually via CLI or desktop app or from bot code with these commands:
- APIShowMyAddress to check if address exists,
- APICreateMyAddress to create address,
- APISetAddressSettings to enable auto-access.
ContactConnected
This event is sent after a user connects via bot SimpleX address (not a business address).
Record type:
ContactUpdated
Contact profile of another user is updated.
Record type:
ContactDeletedByContact
Bot user's connection with another contact is deleted (conversation is kept).
Record type:
ReceivedContactRequest
Contact request received.
This event is only sent when auto-accept is disabled.
The request needs to be accepted using APIAcceptContact command
Record type:
- type: "receivedContactRequest"
- user: User
- contactRequest: UserContactRequest
- chat_: AChat?
NewMemberContactReceivedInv
Received invitation to connect directly with a group member.
This event only needs to be processed to associate contact with group, the connection will proceed automatically.
Record type:
- type: "newMemberContactReceivedInv"
- user: User
- contact: Contact
- groupInfo: GroupInfo
- member: GroupMember
ContactSndReady
Connecting via 1-time invitation or after accepting contact request.
After this event bot can send messages to this contact.
Record type:
Message events
Bots must use these events to process received messages.
NewChatItems
Received message(s).
Record type:
ChatItemReaction
Received message reaction.
Record type:
- type: "chatItemReaction"
- user: User
- added: bool
- reaction: ACIReaction
ChatItemsDeleted
Message was deleted by another user.
Record type:
- type: "chatItemsDeleted"
- user: User
- chatItemDeletions: [ChatItemDeletion]
- byUser: bool
- timed: bool
ChatItemUpdated
Message was updated by another user.
chatItemUpdate has prevChatItem, the message before the update. When the bot deleted the message locally, the update creates it again, and it is sent in NewChatItems event.
Record type:
- type: "chatItemUpdated"
- user: User
- chatItemUpdate: AChatItemUpdate
GroupChatItemsDeleted
Group messages are deleted or moderated.
Record type:
- type: "groupChatItemsDeleted"
- user: User
- groupInfo: GroupInfo
- chatItemIDs: [int64]
- byUser: bool
- member_: GroupMember?
ChatItemsStatusesUpdated
Message delivery status updates.
Record type:
Group events
Bots may use these events to manage users' groups and business address groups.
Please note: programming groups is more complex than programming direct connections
ReceivedGroupInvitation
Received group invitation.
Record type:
- type: "receivedGroupInvitation"
- user: User
- groupInfo: GroupInfo
- contact: Contact
- fromMemberRole: GroupMemberRole
- memberRole: GroupMemberRole
ReceivedGroupInvitationViaGroup
Received group invitation from member of another group.
Record type:
- type: "receivedGroupInvitationViaGroup"
- user: User
- groupInfo: GroupInfo
- viaGroupInfo: GroupInfo
- viaMember: GroupMember
- fromMemberRole: GroupMemberRole
- memberRole: GroupMemberRole
UserJoinedGroup
Bot user joined group. Received when connection via group link completes.
Record type:
- type: "userJoinedGroup"
- user: User
- groupInfo: GroupInfo
- hostMember: GroupMember
GroupUpdated
Group profile or preferences updated.
Record type:
- type: "groupUpdated"
- user: User
- fromGroup: GroupInfo
- toGroup: GroupInfo
- member_: GroupMember?
- msgSigned: MsgSigStatus?
JoinedGroupMember
Another member joined group.
Record type:
- type: "joinedGroupMember"
- user: User
- groupInfo: GroupInfo
- member: GroupMember
MemberRole
Member (or bot user's) group role changed.
Record type:
- type: "memberRole"
- user: User
- groupInfo: GroupInfo
- byMember: GroupMember
- member: GroupMember
- fromRole: GroupMemberRole
- toRole: GroupMemberRole
- msgSigned: MsgSigStatus?
DeletedMember
Another member is removed from the group.
Record type:
- type: "deletedMember"
- user: User
- groupInfo: GroupInfo
- byMember: GroupMember
- deletedMember: GroupMember
- withMessages: bool
- msgSigned: MsgSigStatus?
LeftMember
Another member left the group.
Record type:
- type: "leftMember"
- user: User
- groupInfo: GroupInfo
- member: GroupMember
- msgSigned: MsgSigStatus?
DeletedMemberUser
Bot user was removed from the group.
Record type:
- type: "deletedMemberUser"
- user: User
- groupInfo: GroupInfo
- member: GroupMember
- withMessages: bool
- msgSigned: MsgSigStatus?
GroupDeleted
Group was deleted by the owner (not bot user).
Record type:
- type: "groupDeleted"
- user: User
- groupInfo: GroupInfo
- member: GroupMember
- msgSigned: MsgSigStatus?
ConnectedToGroupMember
Connected to another group member.
Record type:
- type: "connectedToGroupMember"
- user: User
- groupInfo: GroupInfo
- member: GroupMember
- memberContact: Contact?
MemberAcceptedByOther
Another group owner, admin or moderator accepted member to the group after review ("knocking").
Record type:
- type: "memberAcceptedByOther"
- user: User
- groupInfo: GroupInfo
- acceptingMember: GroupMember
- member: GroupMember
MemberBlockedForAll
Another member blocked for all members.
Record type:
- type: "memberBlockedForAll"
- user: User
- groupInfo: GroupInfo
- byMember: GroupMember
- member: GroupMember
- blocked: bool
- msgSigned: MsgSigStatus?
GroupMemberUpdated
Another group member profile updated.
Record type:
- type: "groupMemberUpdated"
- user: User
- groupInfo: GroupInfo
- fromMember: GroupMember
- toMember: GroupMember
GroupLinkDataUpdated
Group link data updated.
Record type:
- type: "groupLinkDataUpdated"
- user: User
- groupInfo: GroupInfo
- groupLink: GroupLink
- groupRelays: [GroupRelay]
- relaysChanged: bool
GroupRelayUpdated
Group relay member updated.
Record type:
- type: "groupRelayUpdated"
- user: User
- groupInfo: GroupInfo
- member: GroupMember
- groupRelay: GroupRelay
File events
Bots that send or receive files may process these events to track delivery status and to process completion.
Bots that need to receive or moderate files (e.g., based on name, size or extension), can use relevant commands (e.g., ReceiveFile or APIDeleteMemberChatItem) when processing NewChatItems event.
Bots that need to send files should use APISendMessages command.
RcvFileDescrReady
File is ready to be received.
This event is useful for processing sender file servers and monitoring file reception progress.
ReceiveFile command can be used before this event.
Record type:
- type: "rcvFileDescrReady"
- user: User
- chatItem: AChatItem
- rcvFileTransfer: RcvFileTransfer
- rcvFileDescr: RcvFileDescr
RcvFileComplete
File reception is competed.
Record type:
SndFileCompleteXFTP
File upload is competed.
Record type:
- type: "sndFileCompleteXFTP"
- user: User
- chatItem: AChatItem
- fileTransferMeta: FileTransferMeta
RcvFileStart
File reception started. This event will be sent after CEvtRcvFileDescrReady event.
Record type:
RcvFileSndCancelled
File was cancelled by the sender. This event may be sent instead of CEvtRcvFileDescrReady event.
Record type:
- type: "rcvFileSndCancelled"
- user: User
- chatItem: AChatItem
- rcvFileTransfer: RcvFileTransfer
RcvFileAccepted
This event will be sent when file is automatically accepted because of CLI option.
Record type:
RcvFileError
Error receiving file.
Record type:
- type: "rcvFileError"
- user: User
- chatItem_: AChatItem?
- agentError: AgentErrorType
- rcvFileTransfer: RcvFileTransfer
RcvFileWarning
Warning when receiving file. It can happen when CLI settings do not allow to connect to file server(s).
Record type:
- type: "rcvFileWarning"
- user: User
- chatItem_: AChatItem?
- agentError: AgentErrorType
- rcvFileTransfer: RcvFileTransfer
SndFileError
Error sending file.
Record type:
- type: "sndFileError"
- user: User
- chatItem_: AChatItem?
- fileTransferMeta: FileTransferMeta
- errorMessage: string
SndFileWarning
Warning when sending file.
Record type:
- type: "sndFileWarning"
- user: User
- chatItem_: AChatItem?
- fileTransferMeta: FileTransferMeta
- errorMessage: string
Connection progress events
Bots may use these events to track progress of connections for monitoring or debugging.
AcceptingContactRequest
Automatically accepting contact request via bot's SimpleX address with auto-accept enabled.
Record type:
AcceptingBusinessRequest
Automatically accepting contact request via bot's business address.
Record type:
ContactConnecting
Contact confirmed connection.
Sent when contact started connecting via bot's 1-time invitation link or when bot connects to another SimpleX address.
Record type:
BusinessLinkConnecting
Contact confirmed connection.
Sent when bot connects to another business address.
Record type:
- type: "businessLinkConnecting"
- user: User
- groupInfo: GroupInfo
- hostMember: GroupMember
- fromContact: Contact
JoinedGroupMemberConnecting
Group member is announced to the group and will be connecting to bot.
Record type:
- type: "joinedGroupMemberConnecting"
- user: User
- groupInfo: GroupInfo
- hostMember: GroupMember
- member: GroupMember
GroupLinkConnecting
Sent when bot joins group via another user link.
Record type:
- type: "groupLinkConnecting"
- user: User
- groupInfo: GroupInfo
- hostMember: GroupMember
Network connection events
HostConnected
Messaging or file server connected
Record type:
- type: "hostConnected"
- protocol: string
- transportHost: string
HostDisconnected
Messaging or file server disconnected
Record type:
- type: "hostDisconnected"
- protocol: string
- transportHost: string
SubscriptionStatus
Messaging subscription status changed
Record type:
- type: "subscriptionStatus"
- server: string
- subscriptionStatus: SubscriptionStatus
- connections: [string]
Service events
Bots with a double ratchet address, started with service request processing enabled, can answer service requests - a single request with a single response (RPC).
ServiceRequest
Service request received.
The request needs to be answered using APISendServiceResponse command.
Record type:
- type: "serviceRequest"
- user: User
- requestId: string
- signerKey: string?
- requestData: JSONObject
ServiceReplySent
Service reply was sent (delivered to the server).
Correlate connectionId with the connection ID from the response to APISendServiceResponse to learn when the reply is delivered.
Record type:
- type: "serviceReplySent"
- connectionId: string
Remote control events
Bots that act as remote control hosts receive these events during the remote control session lifecycle.
RemoteCtrlSessionCode
Remote controller session code ready for verification.
Use VerifyRemoteCtrlSession to complete the connection.
Record type:
- type: "remoteCtrlSessionCode"
- remoteCtrl_: RemoteCtrlInfo?
- sessionCode: string
RemoteCtrlStopped
Remote controller session stopped.
Record type:
- type: "remoteCtrlStopped"
- rcsState: RemoteCtrlSessionState
- rcStopReason: RemoteCtrlStopReason
Error events
Bots may log these events for debugging. There will be many error events - this does NOT indicate a malfunction - e.g., they may happen because of bad network connectivity, or because messages may be delivered to deleted chats for a short period of time (they will be ignored).
MessageError
Message error.
Record type:
- type: "messageError"
- user: User
- severity: string
- errorMessage: string
ChatError
Chat error (only used in WebSockets API).
Record type:
- type: "chatError"
- chatError: ChatError
ChatErrors
Chat errors.
Record type:
- type: "chatErrors"
- chatErrors: [ChatError]