mirror of https://github.com/simplex-chat/simplex-chat.git synced 2026-04-03 11:26:25 +00:00

Files

spaced4ndy b97868d79f ios: channels and chat relays ui (#6634 )

2026-03-05 09:13:24 +00:00

44 KiB

Raw Blame History

SimpleX Chat iOS -- Chat API Reference

Complete specification of the ChatCommand, ChatResponse, ChatEvent, and ChatError types that form the API between the Swift UI layer and the Haskell core.

Related specs: Architecture | State Management | README Related product: Concept Index

Source: AppAPITypes.swift | SimpleXAPI.swift | APITypes.swift | API.swift

Overview
Command Categories (ChatCommand)
Response Types (ChatResponse)
Event Types (ChatEvent)
Error Types (ChatError)
FFI Bridge Functions
Result Type (APIResult)

1. Overview

The iOS app communicates with the Haskell core exclusively through a command/response protocol:

Swift constructs a ChatCommand enum value
The command's cmdString property serializes it to a text command
The FFI bridge sends the string to Haskell via chat_send_cmd_retry
Haskell returns a JSON response, decoded as APIResult<ChatResponse>
Async events arrive separately via chat_recv_msg_wait, decoded as ChatEvent

Source files:

Shared/Model/AppAPITypes.swift -- ChatCommand (L15), ChatResponse0 (L657), ChatResponse1 (L779), ChatResponse2 (L919), ChatEvent (L1069) enums
SimpleXChat/APITypes.swift -- APIResult<R> (L27), ChatAPIResult (L65), ChatError (L699)
Shared/Model/SimpleXAPI.swift -- FFI bridge functions (chatSendCmd L121, chatRecvMsg L237)
SimpleXChat/API.swift -- Low-level FFI (sendSimpleXCmd L115, recvSimpleXMsg L137)
SimpleXChat/ChatTypes.swift -- Data types used in commands/responses (User, Contact, GroupInfo, ChatItem, etc.)
../../src/Simplex/Chat/Controller.hs -- Haskell controller (function chat_send_cmd_retry, chat_recv_msg_wait)

2. Command Categories

The ChatCommand enum (AppAPITypes.swift L15) contains all commands the iOS app can send to the Haskell core. Commands are organized below by functional area.

2.1 User Management

Command	Parameters	Description	Source
`showActiveUser`	--	Get current active user	L16
`createActiveUser`	`profile: Profile?, pastTimestamp: Bool`	Create new user profile	L17
`listUsers`	--	List all user profiles	L18
`apiSetActiveUser`	`userId: Int64, viewPwd: String?`	Switch active user	L19
`apiHideUser`	`userId: Int64, viewPwd: String`	Hide user behind password	L24
`apiUnhideUser`	`userId: Int64, viewPwd: String`	Unhide hidden user	L25
`apiMuteUser`	`userId: Int64`	Mute notifications for user	L26
`apiUnmuteUser`	`userId: Int64`	Unmute notifications for user	L27
`apiDeleteUser`	`userId: Int64, delSMPQueues: Bool, viewPwd: String?`	Delete user profile	L28
`apiUpdateProfile`	`userId: Int64, profile: Profile`	Update user display name/image	L141
`setAllContactReceipts`	`enable: Bool`	Set delivery receipts for all contacts	L20
`apiSetUserContactReceipts`	`userId: Int64, userMsgReceiptSettings`	Per-user contact receipt settings	L21
`apiSetUserGroupReceipts`	`userId: Int64, userMsgReceiptSettings`	Per-user group receipt settings	L22
`apiSetUserAutoAcceptMemberContacts`	`userId: Int64, enable: Bool`	Auto-accept group member contacts	L23

2.2 Chat Lifecycle Control

Command	Parameters	Description	Source
`startChat`	`mainApp: Bool, enableSndFiles: Bool`	Start chat engine	L29
`checkChatRunning`	--	Check if chat is running	L30
`apiStopChat`	--	Stop chat engine	L31
`apiActivateChat`	`restoreChat: Bool`	Resume from background	L32
`apiSuspendChat`	`timeoutMicroseconds: Int`	Suspend for background	L33
`apiSetAppFilePaths`	`filesFolder, tempFolder, assetsFolder`	Set file storage paths	L34
`apiSetEncryptLocalFiles`	`enable: Bool`	Toggle local file encryption	L35

2.3 Chat & Message Operations

Command	Parameters	Description	Source
`apiGetChats`	`userId: Int64`	Get all chat previews for user	L44
`apiGetChat`	`chatId, scope, contentTag, pagination, search`	Get messages for a chat	L45
`apiGetChatContentTypes`	`chatId, scope`	Get content type counts for a chat	L46
`apiGetChatItemInfo`	`type, id, scope, itemId`	Get detailed info for a message	L47
`apiSendMessages`	`type, id, scope, sendAsGroup, live, ttl, composedMessages`	Send one or more messages; `sendAsGroup` sends as channel owner	L48
`apiCreateChatItems`	`noteFolderId, composedMessages`	Create items in notes folder	L54
`apiUpdateChatItem`	`type, id, scope, itemId, updatedMessage, live`	Edit a sent message	L56
`apiDeleteChatItem`	`type, id, scope, itemIds, mode`	Delete messages	L57
`apiDeleteMemberChatItem`	`groupId, itemIds`	Moderate group messages	L58
`apiChatItemReaction`	`type, id, scope, itemId, add, reaction`	Add/remove emoji reaction	L61
`apiGetReactionMembers`	`userId, groupId, itemId, reaction`	Get who reacted	L62
`apiPlanForwardChatItems`	`fromChatType, fromChatId, fromScope, itemIds`	Plan message forwarding	L63
`apiForwardChatItems`	`toChatType, toChatId, toScope, sendAsGroup, from..., itemIds, ttl`	Forward messages; `sendAsGroup` forwards as channel owner	L64
`apiReportMessage`	`groupId, chatItemId, reportReason, reportText`	Report group message	L55
`apiChatRead`	`type, id, scope`	Mark entire chat as read	L166
`apiChatItemsRead`	`type, id, scope, itemIds`	Mark specific items as read	L167
`apiChatUnread`	`type, id, unreadChat`	Toggle unread badge	L168

2.4 Contact Management

Command	Parameters	Description	Source
`apiAddContact`	`userId, incognito`	Create invitation link	L126
`apiConnect`	`userId, incognito, connLink`	Connect via link	L136
`apiConnectPlan`	`userId, connLink`	Plan connection (preview)	L129
`apiPrepareContact`	`userId, connLink, contactShortLinkData`	Prepare contact from link	L130
`apiPrepareGroup`	`userId, connLink, directLink, groupShortLinkData`	Prepare group from link; `directLink` (required, no default) indicates whether link is a direct (non-relay) group link	L131
`apiConnectPreparedContact`	`contactId, incognito, msg`	Connect prepared contact	L134
`apiConnectPreparedGroup`	`groupId, incognito, msg`	Connect to a prepared group/channel; returns `(GroupInfo, [RelayConnectionResult])?`	L135
`apiConnectContactViaAddress`	`userId, incognito, contactId`	Connect via address	L137
`apiAcceptContact`	`incognito, contactReqId`	Accept contact request	L154
`apiRejectContact`	`contactReqId`	Reject contact request	L155
`apiDeleteChat`	`type, id, chatDeleteMode`	Delete conversation	L138
`apiClearChat`	`type, id`	Clear conversation history	L139
`apiListContacts`	`userId`	List all contacts	L140
`apiSetContactPrefs`	`contactId, preferences`	Set contact preferences	L142
`apiSetContactAlias`	`contactId, localAlias`	Set local alias	L143
`apiSetConnectionAlias`	`connId, localAlias`	Set pending connection alias	L145
`apiContactInfo`	`contactId`	Get contact info + connection stats	L112
`apiSetConnectionIncognito`	`connId, incognito`	Toggle incognito on pending connection	L127

2.5 Group Management

Command	Parameters	Description	Source
`apiNewGroup`	`userId, incognito, groupProfile`	Create new group	L72
`apiNewPublicGroup`	`userId, incognito, relayIds, groupProfile`	Create new public group (channel) with chat relays	L73
`apiGetGroupRelays`	`groupId`	Get group relay list with status (owner only)	L74
`apiAddMember`	`groupId, contactId, memberRole`	Invite contact to group	L75
`apiJoinGroup`	`groupId`	Accept group invitation	L76
`apiAcceptMember`	`groupId, groupMemberId, memberRole`	Accept member (knocking)	L77
`apiRemoveMembers`	`groupId, memberIds, withMessages`	Remove members	L81
`apiLeaveGroup`	`groupId`	Leave group	L82
`apiListMembers`	`groupId`	List group members	L83
`apiUpdateGroupProfile`	`groupId, groupProfile`	Update group name/image/description	L84
`apiMembersRole`	`groupId, memberIds, memberRole`	Change member roles	L79
`apiBlockMembersForAll`	`groupId, memberIds, blocked`	Block members for all	L80
`apiCreateGroupLink`	`groupId, memberRole`	Create shareable group link	L85
`apiGroupLinkMemberRole`	`groupId, memberRole`	Change group link default role	L86
`apiDeleteGroupLink`	`groupId`	Delete group link	L87
`apiGetGroupLink`	`groupId`	Get existing group link	L88
`apiAddGroupShortLink`	`groupId`	Add short link to group	L89
`apiCreateMemberContact`	`groupId, groupMemberId`	Create direct contact from group member	L90
`apiSendMemberContactInvitation`	`contactId, msg`	Send contact invitation to member	L91
`apiGroupMemberInfo`	`groupId, groupMemberId`	Get member info + connection stats	L113
`apiDeleteMemberSupportChat`	`groupId, groupMemberId`	Delete member support chat	L78
`apiSetMemberSettings`	`groupId, groupMemberId, memberSettings`	Set per-member settings	L111
`apiSetGroupAlias`	`groupId, localAlias`	Set local group alias	L144

2.6 Chat Tags

Command	Parameters	Description	Source
`apiGetChatTags`	`userId`	Get all user tags	L43
`apiCreateChatTag`	`tag: ChatTagData`	Create a new tag	L49
`apiSetChatTags`	`type, id, tagIds`	Assign tags to a chat	L50
`apiDeleteChatTag`	`tagId`	Delete a tag	L51
`apiUpdateChatTag`	`tagId, tagData`	Update tag name/emoji	L52
`apiReorderChatTags`	`tagIds`	Reorder tags	L53

2.7 File Operations

Command	Parameters	Description	Source
`receiveFile`	`fileId, userApprovedRelays, encrypted, inline`	Accept and download file	L169
`setFileToReceive`	`fileId, userApprovedRelays, encrypted`	Mark file for auto-receive	L170
`cancelFile`	`fileId`	Cancel file transfer	L171
`apiUploadStandaloneFile`	`userId, file: CryptoFile`	Upload file to XFTP (no chat)	L181
`apiDownloadStandaloneFile`	`userId, url, file: CryptoFile`	Download from XFTP URL	L182
`apiStandaloneFileInfo`	`url`	Get file metadata from XFTP URL	L183

2.8 WebRTC Call Operations

Command	Parameters	Description	Source
`apiSendCallInvitation`	`contact, callType`	Initiate call	L157
`apiRejectCall`	`contact`	Reject incoming call	L158
`apiSendCallOffer`	`contact, callOffer: WebRTCCallOffer`	Send SDP offer	L159
`apiSendCallAnswer`	`contact, answer: WebRTCSession`	Send SDP answer	L160
`apiSendCallExtraInfo`	`contact, extraInfo: WebRTCExtraInfo`	Send ICE candidates	L161
`apiEndCall`	`contact`	End active call	L162
`apiGetCallInvitations`	--	Get pending call invitations	L163
`apiCallStatus`	`contact, callStatus`	Report call status change	L164

2.9 Push Notifications

Command	Parameters	Description	Source
`apiGetNtfToken`	--	Get current notification token	L65
`apiRegisterToken`	`token, notificationMode`	Register device token with server	L66
`apiVerifyToken`	`token, nonce, code`	Verify token registration	L67
`apiCheckToken`	`token`	Check token status	L68
`apiDeleteToken`	`token`	Unregister token	L69
`apiGetNtfConns`	`nonce, encNtfInfo`	Get notification connections (NSE)	L70
`apiGetConnNtfMessages`	`connMsgReqs`	Get notification messages (NSE)	L71

2.10 Settings & Configuration

Command	Parameters	Description	Source
`apiSaveSettings`	`settings: AppSettings`	Save app settings to core	L41
`apiGetSettings`	`settings: AppSettings`	Get settings from core	L42
`apiSetChatSettings`	`type, id, chatSettings`	Per-chat notification settings	L110
`apiSetChatItemTTL`	`userId, seconds`	Set global message TTL	L102
`apiGetChatItemTTL`	`userId`	Get global message TTL	L103
`apiSetChatTTL`	`userId, type, id, seconds`	Per-chat message TTL	L104
`apiSetNetworkConfig`	`networkConfig: NetCfg`	Set network configuration	L105
`apiGetNetworkConfig`	--	Get network configuration	L106
`apiSetNetworkInfo`	`networkInfo: UserNetworkInfo`	Set network type/status	L107
`reconnectAllServers`	--	Force reconnect all servers	L108
`reconnectServer`	`userId, smpServer`	Reconnect specific server	L109

2.11 Database & Storage

Command	Parameters	Description	Source
`apiStorageEncryption`	`config: DBEncryptionConfig`	Set/change database encryption	L39
`testStorageEncryption`	`key: String`	Test encryption key	L40
`apiExportArchive`	`config: ArchiveConfig`	Export database archive	L36
`apiImportArchive`	`config: ArchiveConfig`	Import database archive	L37
`apiDeleteStorage`	--	Delete all storage	L38

2.12 Server Operations

Command	Parameters	Description	Source
`apiGetServerOperators`	--	Get server operators	L94
`apiSetServerOperators`	`operators`	Set server operators	L95
`apiGetUserServers`	`userId`	Get user's configured servers	L96
`apiSetUserServers`	`userId, userServers`	Set user's servers	L97
`apiValidateServers`	`userId, userServers`	Validate server configuration; returns errors and warnings	L98
`apiGetUsageConditions`	--	Get usage conditions	L99
`apiAcceptConditions`	`conditionsId, operatorIds`	Accept usage conditions	L101
`apiTestProtoServer`	`userId, server`	Test server connectivity	L93

2.13 Theme & UI

Command	Parameters	Description	Source
`apiSetUserUIThemes`	`userId, themes: ThemeModeOverrides?`	Set per-user theme	L146
`apiSetChatUIThemes`	`chatId, themes: ThemeModeOverrides?`	Set per-chat theme	L147

2.14 Remote Desktop

Command	Parameters	Description	Source
`setLocalDeviceName`	`displayName`	Set device name for pairing	L173
`connectRemoteCtrl`	`xrcpInvitation`	Connect to desktop via QR code	L174
`findKnownRemoteCtrl`	--	Find previously paired desktops	L175
`confirmRemoteCtrl`	`remoteCtrlId`	Confirm known remote controller	L176
`verifyRemoteCtrlSession`	`sessionCode`	Verify session code	L177
`listRemoteCtrls`	--	List known remote controllers	L178
`stopRemoteCtrl`	--	Stop remote session	L179
`deleteRemoteCtrl`	`remoteCtrlId`	Delete known controller	L180

2.15 Diagnostics

Command	Parameters	Description	Source
`showVersion`	--	Get core version info	L185
`getAgentSubsTotal`	`userId`	Get total SMP subscriptions	L186
`getAgentServersSummary`	`userId`	Get server summary stats	L187
`resetAgentServersStats`	--	Reset server statistics	L188

2.16 Address Management

Command	Parameters	Description	Source
`apiCreateMyAddress`	`userId`	Create SimpleX address	L148
`apiDeleteMyAddress`	`userId`	Delete SimpleX address	L149
`apiShowMyAddress`	`userId`	Show current address	L150
`apiAddMyAddressShortLink`	`userId`	Add short link to address	L151
`apiSetProfileAddress`	`userId, on: Bool`	Toggle address in profile	L152
`apiSetAddressSettings`	`userId, addressSettings`	Configure address settings	L153

2.17 Connection Security

Command	Parameters	Description	Source
`apiGetContactCode`	`contactId`	Get verification code	L122
`apiGetGroupMemberCode`	`groupId, groupMemberId`	Get member verification code	L123
`apiVerifyContact`	`contactId, connectionCode`	Verify contact identity	L124
`apiVerifyGroupMember`	`groupId, groupMemberId, connectionCode`	Verify group member identity	L125
`apiSwitchContact`	`contactId`	Switch contact connection (key rotation)	L116
`apiSwitchGroupMember`	`groupId, groupMemberId`	Switch group member connection	L117
`apiAbortSwitchContact`	`contactId`	Abort contact switch	L118
`apiAbortSwitchGroupMember`	`groupId, groupMemberId`	Abort member switch	L119
`apiSyncContactRatchet`	`contactId, force`	Sync double-ratchet state	L120
`apiSyncGroupMemberRatchet`	`groupId, groupMemberId, force`	Sync member ratchet	L121

3. Response Types

Responses are split across three enums due to Swift enum size limitations:

ChatResponse0

Synchronous query responses (AppAPITypes.swift L657):

Response	Key Fields	Description	Source
`activeUser`	`user: User`	Current active user	L658
`usersList`	`users: [UserInfo]`	All user profiles	L659
`chatStarted`	--	Chat engine started	L660
`chatRunning`	--	Chat is already running	L661
`chatStopped`	--	Chat engine stopped	L662
`apiChats`	`user, chats: [ChatData]`	All chat previews	L663
`apiChat`	`user, chat: ChatData, navInfo`	Single chat with messages	L664
`chatTags`	`user, userTags: [ChatTag]`	User's chat tags	L666
`chatItemInfo`	`user, chatItem, chatItemInfo`	Message detail info	L667
`serverTestResult`	`user, testServer, testFailure`	Server test result	L668
`userServersValidation`	`user, serverErrors: [UserServersError], serverWarnings: [UserServersWarning]`	Server validation result with errors and warnings	L671
`networkConfig`	`networkConfig: NetCfg`	Current network config	L674
`contactInfo`	`user, contact, connectionStats, customUserProfile`	Contact details	L675
`groupMemberInfo`	`user, groupInfo, member, connectionStats`	Member details	L676
`connectionVerified`	`verified, expectedCode`	Verification result	L686
`tagsUpdated`	`user, userTags, chatTags`	Tags changed	L687

ChatResponse1

Contact, message, and profile responses (AppAPITypes.swift L779):

Response	Key Fields	Description	Source
`invitation`	`user, connLinkInvitation, connection`	Created invitation link	L780
`connectionPlan`	`user, connLink, connectionPlan`	Connection plan preview	L783
`newPreparedChat`	`user, chat: ChatData`	Prepared contact/group	L784
`startedConnectionToGroup`	`user, groupInfo, relayResults: [RelayConnectionResult]`	Group/channel join initiated; relay results indicate per-relay connection success/failure	L790
`contactDeleted`	`user, contact`	Contact deleted	L793
`newChatItems`	`user, chatItems: [AChatItem]`	New messages sent/received	L811
`chatItemUpdated`	`user, chatItem: AChatItem`	Message edited	L814
`chatItemReaction`	`user, added, reaction`	Reaction change	L816
`chatItemsDeleted`	`user, chatItemDeletions, byUser`	Messages deleted	L818
`contactsList`	`user, contacts: [Contact]`	All contacts list	L819
`userProfileUpdated`	`user, fromProfile, toProfile`	Profile changed	L799
`userContactLinkCreated`	`user, connLinkContact`	Address created	L807
`forwardPlan`	`user, chatItemIds, forwardConfirmation`	Forward plan result	L813
`groupChatItemsDeleted`	`user, groupInfo, chatItemIDs, byUser, member_`	Group items deleted	L812

ChatResponse2

Group, file, call, notification, and misc responses (AppAPITypes.swift L919):

Response	Key Fields	Description	Source
`groupCreated`	`user, groupInfo`	New group created	L921
`publicGroupCreated`	`user, groupInfo, groupLink, groupRelays: [GroupRelay]`	New public group (channel) created with relay info	L922
`groupRelays`	`user, groupInfo, groupRelays: [GroupRelay]`	Group relay list (owner API response)	L923
`sentGroupInvitation`	`user, groupInfo, contact, member`	Group invitation sent	L924
`groupMembers`	`user, group: Group`	Group member list	L928
`membersRoleUser`	`user, groupInfo, members, toRole`	Role changed	L932
`groupUpdated`	`user, toGroup: GroupInfo`	Group profile updated	L934
`groupLinkCreated`	`user, groupInfo, groupLink`	Group link created	L935
`rcvFileAccepted`	`user, chatItem`	File download started	L942
`callInvitations`	`callInvitations: [RcvCallInvitation]`	Pending calls	L951
`ntfToken`	`token, status, ntfMode, ntfServer`	Notification token info	L954
`versionInfo`	`versionInfo, chatMigrations, agentMigrations`	Core version	L962
`cmdOk`	`user_`	Generic success	L963
`archiveExported`	`archiveErrors: [ArchiveError]`	Export result	L967
`archiveImported`	`archiveErrors: [ArchiveError]`	Import result	L968
`appSettings`	`appSettings: AppSettings`	Retrieved settings	L969

4. Event Types

The ChatEvent enum (AppAPITypes.swift L1069) represents async events from the Haskell core. These arrive via chat_recv_msg_wait polling, not as responses to commands.

Event processing entry point: processReceivedMsg in SimpleXAPI.swift.

Connection Events

Event	Key Fields	Description	Source
`contactConnected`	`user, contact, userCustomProfile`	Contact connection established	L1076
`contactConnecting`	`user, contact`	Contact connecting in progress	L1077
`contactSndReady`	`user, contact`	Ready to send to contact	L1078
`contactDeletedByContact`	`user, contact`	Contact deleted by other party	L1075
`contactUpdated`	`user, toContact`	Contact profile updated	L1080
`receivedContactRequest`	`user, contactRequest, chat_`	Incoming contact request	L1079
`subscriptionStatus`	`subscriptionStatus, connections`	Connection subscription change	L1082

Message Events

Event	Key Fields	Description	Source
`newChatItems`	`user, chatItems: [AChatItem]`	New messages received	L1084
`chatItemUpdated`	`user, chatItem: AChatItem`	Message edited remotely	L1086
`chatItemReaction`	`user, added, reaction: ACIReaction`	Reaction added/removed	L1087
`chatItemsDeleted`	`user, chatItemDeletions, byUser`	Messages deleted	L1088
`chatItemsStatusesUpdated`	`user, chatItems: [AChatItem]`	Delivery status changed	L1085
`groupChatItemsDeleted`	`user, groupInfo, chatItemIDs, byUser, member_`	Group items deleted	L1090
`chatInfoUpdated`	`user, chatInfo`	Chat metadata changed	L1083

Group Events

Event	Key Fields	Description	Source
`receivedGroupInvitation`	`user, groupInfo, contact, memberRole`	Group invitation received	L1091
`userAcceptedGroupSent`	`user, groupInfo, hostContact`	Joined group	L1092
`groupLinkConnecting`	`user, groupInfo, hostMember`	Connecting via group link	L1093
`joinedGroupMemberConnecting`	`user, groupInfo, hostMember, member`	Member joining	L1095
`memberRole`	`user, groupInfo, byMember, member, fromRole, toRole`	Role changed	L1097
`memberBlockedForAll`	`user, groupInfo, byMember, member, blocked`	Member blocked	L1098
`deletedMemberUser`	`user, groupInfo, member, withMessages`	Current user removed	L1099
`deletedMember`	`user, groupInfo, byMember, deletedMember`	Member removed	L1100
`leftMember`	`user, groupInfo, member`	Member left	L1101
`groupDeleted`	`user, groupInfo, member`	Group deleted	L1102
`userJoinedGroup`	`user, groupInfo, hostMember`	Successfully joined; `hostMember` is upserted into group members	L1103
`joinedGroupMember`	`user, groupInfo, member`	New member joined	L1104
`connectedToGroupMember`	`user, groupInfo, member, memberContact`	E2E session established with member	L1105
`groupUpdated`	`user, toGroup: GroupInfo`	Group profile changed	L1106
`groupLinkRelaysUpdated`	`user, groupInfo, groupLink, groupRelays: [GroupRelay]`	Channel relay configuration changed	L1107
`groupMemberUpdated`	`user, groupInfo, fromMember, toMember`	Member info updated	L1081

File Transfer Events

Event	Key Fields	Description	Source
`rcvFileStart`	`user, chatItem`	Download started	L1112
`rcvFileProgressXFTP`	`user, chatItem_, receivedSize, totalSize`	Download progress	L1113
`rcvFileComplete`	`user, chatItem`	Download complete	L1114
`rcvFileSndCancelled`	`user, chatItem, rcvFileTransfer`	Sender cancelled	L1116
`rcvFileError`	`user, chatItem_, agentError, rcvFileTransfer`	Download error	L1117
`sndFileStart`	`user, chatItem, sndFileTransfer`	Upload started	L1120
`sndFileComplete`	`user, chatItem, sndFileTransfer`	Upload complete (inline)	L1121
`sndFileProgressXFTP`	`user, chatItem_, fileTransferMeta, sentSize, totalSize`	Upload progress	L1123
`sndFileCompleteXFTP`	`user, chatItem, fileTransferMeta`	XFTP upload complete	L1125
`sndFileError`	`user, chatItem_, fileTransferMeta, errorMessage`	Upload error	L1127

Call Events

Event	Key Fields	Description	Source
`callInvitation`	`callInvitation: RcvCallInvitation`	Incoming call	L1130
`callOffer`	`user, contact, callType, offer, sharedKey, askConfirmation`	SDP offer received	L1131
`callAnswer`	`user, contact, answer`	SDP answer received	L1132
`callExtraInfo`	`user, contact, extraInfo`	ICE candidates received	L1133
`callEnded`	`user, contact`	Call ended by remote	L1134

Connection Security Events

Event	Key Fields	Description	Source
`contactSwitch`	`user, contact, switchProgress`	Key rotation progress	L1071
`groupMemberSwitch`	`user, groupInfo, member, switchProgress`	Member key rotation	L1072
`contactRatchetSync`	`user, contact, ratchetSyncProgress`	Ratchet sync progress	L1073
`groupMemberRatchetSync`	`user, groupInfo, member, ratchetSyncProgress`	Member ratchet sync	L1074

System Events

Event	Key Fields	Description	Source
`chatSuspended`	--	Core suspended	L1070

5. Error Types

Defined in SimpleXChat/APITypes.swift L699:

public enum ChatError: Decodable, Hashable, Error {
    case error(errorType: ChatErrorType)
    case errorAgent(agentError: AgentErrorType)
    case errorStore(storeError: StoreError)
    case errorDatabase(databaseError: DatabaseError)
    case errorRemoteCtrl(remoteCtrlError: RemoteCtrlError)
    case invalidJSON(json: Data?)
    case unexpectedResult(type: String)
}

Error Categories

Category	Enum	Description	Source
Chat logic	`ChatErrorType`	Business logic errors (e.g., invalid state, permission denied, `chatRelayExists`)	`APITypes.swift` L722
SMP Agent	`AgentErrorType`	Protocol/network errors from the SMP agent layer	`APITypes.swift` L884
Database store	`StoreError`	SQLite query/constraint errors (includes relay-related: `relayUserNotFound`, `duplicateMemberId`, `userChatRelayNotFound`, `groupRelayNotFound`, `groupRelayNotFoundByMemberId`)	`APITypes.swift` L802
Database engine	`DatabaseError`	DB open/migration/encryption errors	`APITypes.swift` L871
Remote control	`RemoteCtrlError`	Remote desktop session errors	`APITypes.swift` L1054
Parse failure	`invalidJSON`	Failed to decode response JSON	`APITypes.swift` L699
Unexpected	`unexpectedResult`	Response type does not match expected	`APITypes.swift` L699

6. FFI Bridge Functions

Defined in Shared/Model/SimpleXAPI.swift:

Synchronous (blocking current thread)

// Throws on error, returns typed result
func chatSendCmdSync<R: ChatAPIResult>(           // SimpleXAPI.swift L93
    _ cmd: ChatCommand,
    bgTask: Bool = true,
    bgDelay: Double? = nil,
    ctrl: chat_ctrl? = nil,
    log: Bool = true
) throws -> R

// Returns APIResult (caller handles error)
func chatApiSendCmdSync<R: ChatAPIResult>(         // SimpleXAPI.swift L99
    _ cmd: ChatCommand,
    bgTask: Bool = true,
    bgDelay: Double? = nil,
    ctrl: chat_ctrl? = nil,
    retryNum: Int32 = 0,
    log: Bool = true
) -> APIResult<R>

Asynchronous (Swift concurrency)

// Throws on error, returns typed result
func chatSendCmd<R: ChatAPIResult>(                // SimpleXAPI.swift L121
    _ cmd: ChatCommand,
    bgTask: Bool = true,
    bgDelay: Double? = nil,
    ctrl: chat_ctrl? = nil,
    log: Bool = true
) async throws -> R

// Returns APIResult with optional retry on network errors
func chatApiSendCmdWithRetry<R: ChatAPIResult>(    // SimpleXAPI.swift L127
    _ cmd: ChatCommand,
    bgTask: Bool = true,
    bgDelay: Double? = nil,
    inProgress: BoxedValue<Bool>? = nil,
    retryNum: Int32 = 0
) async -> APIResult<R>?

Low-Level FFI

// Direct C FFI call -- serializes cmd.cmdString, calls chat_send_cmd_retry, decodes response
public func sendSimpleXCmd<R: ChatAPIResult>(      // API.swift L115
    _ cmd: ChatCmdProtocol,
    _ ctrl: chat_ctrl?,
    retryNum: Int32 = 0
) -> APIResult<R>

Event Receiver

// Polls for async events from the Haskell core
func chatRecvMsg(                                  // SimpleXAPI.swift L237
    _ ctrl: chat_ctrl? = nil
) async -> APIResult<ChatEvent>?

// Processes a received event and updates app state
func processReceivedMsg(                           // SimpleXAPI.swift L2282
    _ res: ChatEvent
) async

7. Result Type

Defined in SimpleXChat/APITypes.swift L27:

public enum APIResult<R>: Decodable where R: Decodable, R: ChatAPIResult {
    case result(R)           // Successful response
    case error(ChatError)    // Error response from core
    case invalid(type: String, json: Data)  // Undecodable response

    public var responseType: String { ... }
    public var unexpected: ChatError { ... }
}

public protocol ChatAPIResult: Decodable {         // APITypes.swift L65
    var responseType: String { get }
    var details: String { get }
    static func fallbackResult(_ type: String, _ json: NSDictionary) -> Self?
}

The decodeAPIResult<R> function (APITypes.swift L86) handles JSON decoding with fallback logic:

Try standard JSONDecoder.decode(APIResult<R>.self, from: data)
If that fails, try manual JSON parsing via JSONSerialization
Check for "error" key -- return .error
Check for "result" key -- try R.fallbackResult or return .invalid
Last resort: return .invalid(type: "invalid", json: ...)

Source Files

File	Path
ChatCommand enum	`Shared/Model/AppAPITypes.swift` L15
ChatResponse0/1/2 enums	`Shared/Model/AppAPITypes.swift` L657, L779, L919
ChatEvent enum	`Shared/Model/AppAPITypes.swift` L1069
APIResult, ChatError	`SimpleXChat/APITypes.swift` L27, L699
FFI bridge functions	`Shared/Model/SimpleXAPI.swift`
Low-level FFI	`SimpleXChat/API.swift`
Data types	`SimpleXChat/ChatTypes.swift`
C header	`SimpleXChat/SimpleX.h`
Haskell controller	`../../src/Simplex/Chat/Controller.hs`

44 KiB Raw Blame History