Files
simplex-chat/apps/ios/spec/api.md
2026-02-19 10:58:16 +00:00

42 KiB

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


Table of Contents

  1. Overview
  2. Command Categories (ChatCommand)
  3. Response Types (ChatResponse)
  4. Event Types (ChatEvent)
  5. Error Types (ChatError)
  6. FFI Bridge Functions
  7. Result Type (APIResult)

1. Overview

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

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

Source files:


2. Command Categories

The ChatCommand enum (AppAPITypes.swift L14) 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 L15
createActiveUser profile: Profile?, pastTimestamp: Bool Create new user profile L16
listUsers -- List all user profiles L17
apiSetActiveUser userId: Int64, viewPwd: String? Switch active user L18
apiHideUser userId: Int64, viewPwd: String Hide user behind password L23
apiUnhideUser userId: Int64, viewPwd: String Unhide hidden user L24
apiMuteUser userId: Int64 Mute notifications for user L25
apiUnmuteUser userId: Int64 Unmute notifications for user L26
apiDeleteUser userId: Int64, delSMPQueues: Bool, viewPwd: String? Delete user profile L27
apiUpdateProfile userId: Int64, profile: Profile Update user display name/image L138
setAllContactReceipts enable: Bool Set delivery receipts for all contacts L19
apiSetUserContactReceipts userId: Int64, userMsgReceiptSettings Per-user contact receipt settings L20
apiSetUserGroupReceipts userId: Int64, userMsgReceiptSettings Per-user group receipt settings L21
apiSetUserAutoAcceptMemberContacts userId: Int64, enable: Bool Auto-accept group member contacts L22

2.2 Chat Lifecycle Control

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

2.3 Chat & Message Operations

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

2.4 Contact Management

Command Parameters Description Source
apiAddContact userId, incognito Create invitation link L123
apiConnect userId, incognito, connLink Connect via link L133
apiConnectPlan userId, connLink Plan connection (preview) L126
apiPrepareContact userId, connLink, contactShortLinkData Prepare contact from link L127
apiConnectPreparedContact contactId, incognito, msg Connect prepared contact L131
apiConnectContactViaAddress userId, incognito, contactId Connect via address L134
apiAcceptContact incognito, contactReqId Accept contact request L151
apiRejectContact contactReqId Reject contact request L152
apiDeleteChat type, id, chatDeleteMode Delete conversation L135
apiClearChat type, id Clear conversation history L136
apiListContacts userId List all contacts L137
apiSetContactPrefs contactId, preferences Set contact preferences L139
apiSetContactAlias contactId, localAlias Set local alias L140
apiSetConnectionAlias connId, localAlias Set pending connection alias L142
apiContactInfo contactId Get contact info + connection stats L109
apiSetConnectionIncognito connId, incognito Toggle incognito on pending connection L124

2.5 Group Management

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

2.6 Chat Tags

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

2.7 File Operations

Command Parameters Description Source
receiveFile fileId, userApprovedRelays, encrypted, inline Accept and download file L166
setFileToReceive fileId, userApprovedRelays, encrypted Mark file for auto-receive L167
cancelFile fileId Cancel file transfer L168
apiUploadStandaloneFile userId, file: CryptoFile Upload file to XFTP (no chat) L178
apiDownloadStandaloneFile userId, url, file: CryptoFile Download from XFTP URL L179
apiStandaloneFileInfo url Get file metadata from XFTP URL L180

2.8 WebRTC Call Operations

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

2.9 Push Notifications

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

2.10 Settings & Configuration

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

2.11 Database & Storage

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

2.12 Server Operations

Command Parameters Description Source
apiGetServerOperators -- Get server operators L91
apiSetServerOperators operators Set server operators L92
apiGetUserServers userId Get user's configured servers L93
apiSetUserServers userId, userServers Set user's servers L94
apiValidateServers userId, userServers Validate server configuration L95
apiGetUsageConditions -- Get usage conditions L96
apiAcceptConditions conditionsId, operatorIds Accept usage conditions L98
apiTestProtoServer userId, server Test server connectivity L90

2.13 Theme & UI

Command Parameters Description Source
apiSetUserUIThemes userId, themes: ThemeModeOverrides? Set per-user theme L143
apiSetChatUIThemes chatId, themes: ThemeModeOverrides? Set per-chat theme L144

2.14 Remote Desktop

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

2.15 Diagnostics

Command Parameters Description Source
showVersion -- Get core version info L182
getAgentSubsTotal userId Get total SMP subscriptions L183
getAgentServersSummary userId Get server summary stats L184
resetAgentServersStats -- Reset server statistics L185

2.16 Address Management

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

2.17 Connection Security

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

3. Response Types

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

ChatResponse0

Synchronous query responses (AppAPITypes.swift L647):

Response Key Fields Description Source
activeUser user: User Current active user L648
usersList users: [UserInfo] All user profiles L649
chatStarted -- Chat engine started L650
chatRunning -- Chat is already running L651
chatStopped -- Chat engine stopped L652
apiChats user, chats: [ChatData] All chat previews L653
apiChat user, chat: ChatData, navInfo Single chat with messages L654
chatTags user, userTags: [ChatTag] User's chat tags L656
chatItemInfo user, chatItem, chatItemInfo Message detail info L657
serverTestResult user, testServer, testFailure Server test result L658
networkConfig networkConfig: NetCfg Current network config L664
contactInfo user, contact, connectionStats, customUserProfile Contact details L665
groupMemberInfo user, groupInfo, member, connectionStats Member details L666
connectionVerified verified, expectedCode Verification result L676
tagsUpdated user, userTags, chatTags Tags changed L677

ChatResponse1

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

Response Key Fields Description Source
invitation user, connLinkInvitation, connection Created invitation link L769
connectionPlan user, connLink, connectionPlan Connection plan preview L772
newPreparedChat user, chat: ChatData Prepared contact/group L773
contactDeleted user, contact Contact deleted L782
newChatItems user, chatItems: [AChatItem] New messages sent/received L800
chatItemUpdated user, chatItem: AChatItem Message edited L803
chatItemReaction user, added, reaction Reaction change L805
chatItemsDeleted user, chatItemDeletions, byUser Messages deleted L807
contactsList user, contacts: [Contact] All contacts list L808
userProfileUpdated user, fromProfile, toProfile Profile changed L788
userContactLinkCreated user, connLinkContact Address created L796
forwardPlan user, chatItemIds, forwardConfirmation Forward plan result L802
groupChatItemsDeleted user, groupInfo, chatItemIDs, byUser, member_ Group items deleted L801

ChatResponse2

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

Response Key Fields Description Source
groupCreated user, groupInfo New group created L909
sentGroupInvitation user, groupInfo, contact, member Group invitation sent L910
groupMembers user, group: Group Group member list L914
membersRoleUser user, groupInfo, members, toRole Role changed L918
groupUpdated user, toGroup: GroupInfo Group profile updated L920
groupLinkCreated user, groupInfo, groupLink Group link created L921
rcvFileAccepted user, chatItem File download started L928
callInvitations callInvitations: [RcvCallInvitation] Pending calls L937
ntfToken token, status, ntfMode, ntfServer Notification token info L940
versionInfo versionInfo, chatMigrations, agentMigrations Core version L948
cmdOk user_ Generic success L949
archiveExported archiveErrors: [ArchiveError] Export result L953
archiveImported archiveErrors: [ArchiveError] Import result L954
appSettings appSettings: AppSettings Retrieved settings L955

4. Event Types

The ChatEvent enum (AppAPITypes.swift L1050) 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 L1057
contactConnecting user, contact Contact connecting in progress L1058
contactSndReady user, contact Ready to send to contact L1059
contactDeletedByContact user, contact Contact deleted by other party L1056
contactUpdated user, toContact Contact profile updated L1061
receivedContactRequest user, contactRequest, chat_ Incoming contact request L1060
subscriptionStatus subscriptionStatus, connections Connection subscription change L1063

Message Events

Event Key Fields Description Source
newChatItems user, chatItems: [AChatItem] New messages received L1065
chatItemUpdated user, chatItem: AChatItem Message edited remotely L1067
chatItemReaction user, added, reaction: ACIReaction Reaction added/removed L1068
chatItemsDeleted user, chatItemDeletions, byUser Messages deleted L1069
chatItemsStatusesUpdated user, chatItems: [AChatItem] Delivery status changed L1066
groupChatItemsDeleted user, groupInfo, chatItemIDs, byUser, member_ Group items deleted L1071
chatInfoUpdated user, chatInfo Chat metadata changed L1064

Group Events

Event Key Fields Description Source
receivedGroupInvitation user, groupInfo, contact, memberRole Group invitation received L1072
userAcceptedGroupSent user, groupInfo, hostContact Joined group L1073
groupLinkConnecting user, groupInfo, hostMember Connecting via group link L1074
joinedGroupMemberConnecting user, groupInfo, hostMember, member Member joining L1076
memberRole user, groupInfo, byMember, member, fromRole, toRole Role changed L1078
memberBlockedForAll user, groupInfo, byMember, member, blocked Member blocked L1079
deletedMemberUser user, groupInfo, member, withMessages Current user removed L1080
deletedMember user, groupInfo, byMember, deletedMember Member removed L1081
leftMember user, groupInfo, member Member left L1082
groupDeleted user, groupInfo, member Group deleted L1083
userJoinedGroup user, groupInfo Successfully joined L1084
joinedGroupMember user, groupInfo, member New member joined L1085
connectedToGroupMember user, groupInfo, member, memberContact E2E session established with member L1086
groupUpdated user, toGroup: GroupInfo Group profile changed L1087
groupMemberUpdated user, groupInfo, fromMember, toMember Member info updated L1062

File Transfer Events

Event Key Fields Description Source
rcvFileStart user, chatItem Download started L1092
rcvFileProgressXFTP user, chatItem_, receivedSize, totalSize Download progress L1093
rcvFileComplete user, chatItem Download complete L1094
rcvFileSndCancelled user, chatItem, rcvFileTransfer Sender cancelled L1096
rcvFileError user, chatItem_, agentError, rcvFileTransfer Download error L1097
sndFileStart user, chatItem, sndFileTransfer Upload started L1100
sndFileComplete user, chatItem, sndFileTransfer Upload complete (inline) L1101
sndFileProgressXFTP user, chatItem_, fileTransferMeta, sentSize, totalSize Upload progress L1103
sndFileCompleteXFTP user, chatItem, fileTransferMeta XFTP upload complete L1105
sndFileError user, chatItem_, fileTransferMeta, errorMessage Upload error L1107

Call Events

Event Key Fields Description Source
callInvitation callInvitation: RcvCallInvitation Incoming call L1110
callOffer user, contact, callType, offer, sharedKey, askConfirmation SDP offer received L1111
callAnswer user, contact, answer SDP answer received L1112
callExtraInfo user, contact, extraInfo ICE candidates received L1113
callEnded user, contact Call ended by remote L1114

Connection Security Events

Event Key Fields Description Source
contactSwitch user, contact, switchProgress Key rotation progress L1052
groupMemberSwitch user, groupInfo, member, switchProgress Member key rotation L1053
contactRatchetSync user, contact, ratchetSyncProgress Ratchet sync progress L1054
groupMemberRatchetSync user, groupInfo, member, ratchetSyncProgress Member ratchet sync L1055

System Events

Event Key Fields Description Source
chatSuspended -- Core suspended L1051

5. Error Types

Defined in SimpleXChat/APITypes.swift L695:

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

Error Categories

Category Enum Description Source
Chat logic ChatErrorType Business logic errors (e.g., invalid state, permission denied) APITypes.swift L717
SMP Agent AgentErrorType Protocol/network errors from the SMP agent layer APITypes.swift L873
Database store StoreError SQLite query/constraint errors APITypes.swift L796
Database engine DatabaseError DB open/migration/encryption errors APITypes.swift L860
Remote control RemoteCtrlError Remote desktop session errors APITypes.swift L1043
Parse failure invalidJSON Failed to decode response JSON APITypes.swift L695
Unexpected unexpectedResult Response type does not match expected APITypes.swift L695

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 L91
    _ 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 L96
    _ 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 L117
    _ 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 L122
    _ 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 L230
    _ ctrl: chat_ctrl? = nil
) async -> APIResult<ChatEvent>?

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

7. Result Type

Defined in SimpleXChat/APITypes.swift L26:

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 L63
    var responseType: String { get }
    var details: String { get }
    static func fallbackResult(_ type: String, _ json: NSDictionary) -> Self?
}

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

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

Source Files

File Path
ChatCommand enum Shared/Model/AppAPITypes.swift L14
ChatResponse0/1/2 enums Shared/Model/AppAPITypes.swift L647, L768, L907
ChatEvent enum Shared/Model/AppAPITypes.swift L1050
APIResult, ChatError SimpleXChat/APITypes.swift L26, L695
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