bots: add APIs (#7494)

* docs: fix bot API surface - Fix missing space in APIShareMyAddress syntax expression which resulted in parse errors - Document missing `Connect` responses: `CRConnectionPlan`, `CRSentInvitationToContact`, `CRStartedConnectionToContact`, and `CRStartedConnectionToGroup` (relay channel links). - Document missing `CRUserProfileNoChange` responsed returned when `APISetProfileAddress` doesn't change the profile. - Expose remote control APIs to bots * website: improve sign-up forms (#7484) * website: improve sign-up forms * name --------- Co-authored-by: Evgeny @ SimpleX Chat <259188159+evgeny-simplex@users.noreply.github.com> * rename field * generic --------- Co-authored-by: a1akris <alkrivitskiy@pm.me> Co-authored-by: Evgeny @ SimpleX Chat <259188159+evgeny-simplex@users.noreply.github.com>
2026-09-23 22:15:24 +00:00 · 2026-09-12 14:13:11 +01:00
parent 9631e0b1b9
commit 47d32b674a
17 changed files with 661 additions and 26 deletions
@@ -79,6 +79,10 @@ This file is generated automatically.
 - [StartChat](#startchat)
 - [APIStopChat](#apistopchat)

+[Remote control commands](#remote-control-commands)
+- [ConnectRemoteCtrl](#connectremotectrl)
+- [VerifyRemoteCtrlSession](#verifyremotectrlsession)
+
 ---


@@ -231,6 +235,10 @@ UserProfileUpdated: User profile updated.
 - toProfile: [Profile](./TYPES.md#profile)
 - updateSummary: [UserProfileUpdateSummary](./TYPES.md#userprofileupdatesummary)

+UserProfileNoChange: User profile was not changed.
+- type: "userProfileNoChange"
+- user: [User](./TYPES.md#user)
+
 ChatCmdError: Command error (only used in WebSockets API).
 - type: "chatCmdError"
 - chatError: [ChatError](./TYPES.md#chaterror)
@@ -505,15 +513,15 @@ Share user address card
 **Syntax**:

 ```
-/_share address<str(toSendRef)>
+/_share address <str(toSendRef)>
 ```

 ```javascript
-'/_share address' + ChatRef.cmdString(toSendRef) // JavaScript
+'/_share address ' + ChatRef.cmdString(toSendRef) // JavaScript
 ```

 ```python
-'/_share address' + ChatRef_cmd_string(toSendRef) # Python
+'/_share address ' + ChatRef_cmd_string(toSendRef) # Python
 ```

 **Response**:
@@ -1609,6 +1617,33 @@ SentInvitation: Invitation sent to contact address.
 - connection: [PendingContactConnection](./TYPES.md#pendingcontactconnection)
 - customUserProfile: [Profile](./TYPES.md#profile)?

+ConnectionPlan: Connection link information.
+- type: "connectionPlan"
+- user: [User](./TYPES.md#user)
+- connLink: [CreatedConnLink](./TYPES.md#createdconnlink)
+- planSimplexName: [SimplexNameInfo](./TYPES.md#simplexnameinfo)?
+- otherSimplexName: [SimplexNameInfo](./TYPES.md#simplexnameinfo)?
+- connectionPlan: [ConnectionPlan](./TYPES.md#connectionplan)
+
+SentInvitationToContact: Invitation sent to contact (when connecting via SimpleX name to a known contact address)..
+- type: "sentInvitationToContact"
+- user: [User](./TYPES.md#user)
+- contact: [Contact](./TYPES.md#contact)
+- customUserProfile: [Profile](./TYPES.md#profile)?
+
+StartedConnectionToContact: Connection to contact started (when connecting via prepared contact)..
+- type: "startedConnectionToContact"
+- user: [User](./TYPES.md#user)
+- contact: [Contact](./TYPES.md#contact)
+- customUserProfile: [Profile](./TYPES.md#profile)?
+
+StartedConnectionToGroup: Connection to channel started (when connecting via channel link)..
+- type: "startedConnectionToGroup"
+- user: [User](./TYPES.md#user)
+- groupInfo: [GroupInfo](./TYPES.md#groupinfo)
+- customUserProfile: [Profile](./TYPES.md#profile)?
+- relayResults: [[RelayConnectionResult](./TYPES.md#relayconnectionresult)]
+
 ChatCmdError: Command error (only used in WebSockets API).
 - type: "chatCmdError"
 - chatError: [ChatError](./TYPES.md#chaterror)
@@ -2370,3 +2405,83 @@ ChatStopped: Chat stopped.
 - type: "chatStopped"

 ---
+
+
+## Remote control commands
+
+Allows a bot to accept an incoming remote control session from a SimpleX Desktop client, giving the desktop live access to the bot's SimpleX instance.
+
+
+### ConnectRemoteCtrl
+
+Connect to a remote controller using an OOB invitation link.
+
+*Network usage*: interactive.
+
+**Parameters**:
+- remoteInvitation: string
+
+**Syntax**:
+
+```
+/crc <remoteInvitation>
+```
+
+```javascript
+'/crc ' + remoteInvitation // JavaScript
+```
+
+```python
+'/crc ' + remoteInvitation # Python
+```
+
+**Responses**:
+
+RemoteCtrlConnecting: Remote controller is connecting..
+- type: "remoteCtrlConnecting"
+- remoteCtrl_: [RemoteCtrlInfo](./TYPES.md#remotectrlinfo)?
+- ctrlAppInfo: [CtrlAppInfo](./TYPES.md#ctrlappinfo)
+- appVersion: string
+
+ChatCmdError: Command error (only used in WebSockets API).
+- type: "chatCmdError"
+- chatError: [ChatError](./TYPES.md#chaterror)
+
+---
+
+
+### VerifyRemoteCtrlSession
+
+Verify the remote controller session code to complete the connection.
+
+*Network usage*: no.
+
+**Parameters**:
+- sessionCode: string
+
+**Syntax**:
+
+```
+/verify remote ctrl <sessionCode>
+```
+
+```javascript
+'/verify remote ctrl ' + sessionCode // JavaScript
+```
+
+```python
+'/verify remote ctrl ' + sessionCode # Python
+```
+
+**Responses**:
+
+RemoteCtrlConnected: Remote controller session connected..
+- type: "remoteCtrlConnected"
+- remoteCtrl: [RemoteCtrlInfo](./TYPES.md#remotectrlinfo)
+- compression: bool
+
+ChatCmdError: Command error (only used in WebSockets API).
+- type: "chatCmdError"
+- chatError: [ChatError](./TYPES.md#chaterror)
+
+---
@@ -72,6 +72,10 @@ This file is generated automatically.
 - [ServiceRequest](#servicerequest)
 - [ServiceReplySent](#servicereplysent)

+[Remote control events](#remote-control-events)
+- [RemoteCtrlSessionCode](#remotectrlsessioncode)
+- [RemoteCtrlStopped](#remotectrlstopped)
+
 [Error events](#error-events)
 - [MessageError](#messageerror)
 - [ChatError](#chaterror)
@@ -793,6 +797,37 @@ Correlate `connectionId` with the connection ID from the response to [APISendSer
 ---


+## 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](./COMMANDS.md#verifyremotectrlsession) to complete the connection.
+
+**Record type**:
+- type: "remoteCtrlSessionCode"
+- remoteCtrl_: [RemoteCtrlInfo](./TYPES.md#remotectrlinfo)?
+- sessionCode: string
+
+---
+
+
+### RemoteCtrlStopped
+
+Remote controller session stopped.
+
+**Record type**:
+- type: "remoteCtrlStopped"
+- rcsState: [RemoteCtrlSessionState](./TYPES.md#remotectrlsessionstate)
+- rcStopReason: [RemoteCtrlStopReason](./TYPES.md#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).
@@ -10,6 +10,7 @@ This file is generated automatically.
 - [AgentCryptoError](#agentcryptoerror)
 - [AgentErrorType](#agenterrortype)
 - [AgentServiceError](#agentserviceerror)
+- [AppVersionRange](#appversionrange)
 - [AutoAccept](#autoaccept)
 - [BadgeInfo](#badgeinfo)
 - [BadgeProof](#badgeproof)
@@ -77,6 +78,7 @@ This file is generated automatically.
 - [CreatedConnLink](#createdconnlink)
 - [CryptoFile](#cryptofile)
 - [CryptoFileArgs](#cryptofileargs)
+- [CtrlAppInfo](#ctrlappinfo)
 - [DroppedMsg](#droppedmsg)
 - [E2EInfo](#e2einfo)
 - [ErrorType](#errortype)
@@ -170,8 +172,12 @@ This file is generated automatically.
 - [RcvGroupEvent](#rcvgroupevent)
 - [RcvMsgError](#rcvmsgerror)
 - [RelayCapabilities](#relaycapabilities)
+- [RelayConnectionResult](#relayconnectionresult)
 - [RelayProfile](#relayprofile)
 - [RelayStatus](#relaystatus)
+- [RemoteCtrlInfo](#remotectrlinfo)
+- [RemoteCtrlSessionState](#remotectrlsessionstate)
+- [RemoteCtrlStopReason](#remotectrlstopreason)
 - [ReportReason](#reportreason)
 - [RoleGroupPreference](#rolegrouppreference)
 - [SMPAgentError](#smpagenterror)
@@ -386,6 +392,17 @@ BadSignature:
 - type: "badSignature"


+---
+
+## AppVersionRange
+
+Remote controller app version range (min and max as version strings).
+
+**Record type**:
+- minVersion: string
+- maxVersion: string
+
+
 ---

 ## AutoAccept
@@ -1967,6 +1984,18 @@ connFullLink + ((' ' + connShortLink) if connShortLink is not None else '') # Py
 - fileNonce: string


+---
+
+## CtrlAppInfo
+
+Remote controller application info.
+
+**Record type**:
+- appVersionRange: [AppVersionRange](#appversionrange)
+- deviceName: string
+- compression: bool
+
+
 ---

 ## DroppedMsg
@@ -3558,6 +3587,15 @@ ParseError:
 - webDomain: string?


+---
+
+## RelayConnectionResult
+
+**Record type**:
+- relayMember: [GroupMember](#groupmember)
+- relayError: [ChatError](#chaterror)?
+
+
 ---

 ## RelayProfile
@@ -3583,6 +3621,62 @@ ParseError:
 - "rejected"


+---
+
+## RemoteCtrlInfo
+
+**Record type**:
+- remoteCtrlId: int64
+- ctrlDeviceName: string
+- sessionState: [RemoteCtrlSessionState](#remotectrlsessionstate)?
+
+
+---
+
+## RemoteCtrlSessionState
+
+**Discriminated union type**:
+
+Starting:
+- type: "starting"
+
+Searching:
+- type: "searching"
+
+Connecting:
+- type: "connecting"
+
+PendingConfirmation:
+- type: "pendingConfirmation"
+- sessionCode: string
+
+Connected:
+- type: "connected"
+- sessionCode: string
+
+
+---
+
+## RemoteCtrlStopReason
+
+**Discriminated union type**:
+
+DiscoveryFailed:
+- type: "discoveryFailed"
+- chatError: [ChatError](#chaterror)
+
+ConnectionFailed:
+- type: "connectionFailed"
+- chatError: [ChatError](#chaterror)
+
+SetupFailed:
+- type: "setupFailed"
+- chatError: [ChatError](#chaterror)
+
+Disconnected:
+- type: "disconnected"
+
+
 ---

 ## ReportReason