EVENTS.md

API Events

This file is generated automatically.

Contact connection events

• Main event
  • ContactConnected
• Other events
  • ContactUpdated
  • ContactDeletedByContact
  • ReceivedContactRequest
  • NewMemberContactReceivedInv
  • ContactSndReady

Message events

• Main event
  • NewChatItems
• Other events
  • ChatItemReaction
  • ChatItemsDeleted
  • ChatItemUpdated
  • GroupChatItemsDeleted
  • ChatItemsStatusesUpdated

Group events

• Main events
  • ReceivedGroupInvitation
  • UserJoinedGroup
  • GroupUpdated
  • JoinedGroupMember
  • MemberRole
  • DeletedMember
  • LeftMember
  • DeletedMemberUser
  • GroupDeleted
• Other events
  • ConnectedToGroupMember
  • MemberAcceptedByOther
  • MemberBlockedForAll
  • GroupMemberUpdated

File events

• Main events
  • RcvFileDescrReady
  • RcvFileComplete
  • SndFileCompleteXFTP
• Other events
  • RcvFileStart
  • RcvFileSndCancelled
  • RcvFileAccepted
  • RcvFileError
  • RcvFileWarning
  • SndFileError
  • SndFileWarning

Connection progress events

• AcceptingContactRequest
• AcceptingBusinessRequest
• ContactConnecting
• BusinessLinkConnecting
• JoinedGroupMemberConnecting
• SentGroupInvitation
• GroupLinkConnecting

Error events

• MessageError
• ChatError
• ChatErrors

---

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:

• type: "contactConnected"
• user: User
• contact: Contact
• userCustomProfile: Profile?

---

ContactUpdated

Contact profile of another user is updated.

Record type:

• type: "contactUpdated"
• user: User
• fromContact: Contact
• toContact: Contact

---

ContactDeletedByContact

Bot user's connection with another contact is deleted (conversation is kept).

Record type:

• type: "contactDeletedByContact"
• user: User
• contact: Contact

---

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:

• type: "contactSndReady"
• user: User
• contact: Contact

---

Message events

Bots must use these events to process received messages.

NewChatItems

Received message(s).

Record type:

• type: "newChatItems"
• user: User
• chatItems: [AChatItem]

---

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.

Record type:

• type: "chatItemUpdated"
• user: User
• chatItem: AChatItem

---

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:

• type: "chatItemsStatusesUpdated"
• user: User
• chatItems: [AChatItem]

---

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

---

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?

---

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

---

DeletedMember

Another member is removed from the group.

Record type:

• type: "deletedMember"
• user: User
• groupInfo: GroupInfo
• byMember: GroupMember
• deletedMember: GroupMember
• withMessages: bool

---

LeftMember

Another member left the group.

Record type:

• type: "leftMember"
• user: User
• groupInfo: GroupInfo
• member: GroupMember

---

DeletedMemberUser

Bot user was removed from the group.

Record type:

• type: "deletedMemberUser"
• user: User
• groupInfo: GroupInfo
• member: GroupMember
• withMessages: bool

---

GroupDeleted

Group was deleted by the owner (not bot user).

Record type:

• type: "groupDeleted"
• user: User
• groupInfo: GroupInfo
• member: GroupMember

---

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

---

GroupMemberUpdated

Another group member profile updated.

Record type:

• type: "groupMemberUpdated"
• user: User
• groupInfo: GroupInfo
• fromMember: GroupMember
• toMember: GroupMember

---

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:

• type: "rcvFileComplete"
• user: User
• chatItem: AChatItem

---

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:

• type: "rcvFileStart"
• user: User
• chatItem: AChatItem

---

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:

• type: "rcvFileAccepted"
• user: User
• chatItem: AChatItem

---

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:

• type: "acceptingContactRequest"
• user: User
• contact: Contact

---

AcceptingBusinessRequest

Automatically accepting contact request via bot's business address.

Record type:

• type: "acceptingBusinessRequest"
• user: User
• groupInfo: GroupInfo

---

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:

• type: "contactConnecting"
• user: User
• contact: Contact

---

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

---

SentGroupInvitation

Sent when another user joins group via bot's link.

Record type:

• type: "sentGroupInvitation"
• user: User
• groupInfo: GroupInfo
• contact: Contact
• member: GroupMember

---

GroupLinkConnecting

Sent when bot joins group via another user link.

Record type:

• type: "groupLinkConnecting"
• user: User
• groupInfo: GroupInfo
• hostMember: GroupMember

---

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.

Record type:

• type: "chatError"
• chatError: ChatError

---

ChatErrors

Chat errors.

Record type:

• type: "chatErrors"
• chatErrors: [ChatError]

---