simplex-chat/bots/api/COMMANDS.md

API Commands and Responses

This file is generated automatically.

Address commands

• APICreateMyAddress
• APIDeleteMyAddress
• APIShowMyAddress
• APISetProfileAddress
• APISetAddressSettings

Message commands

• APISendMessages
• APIUpdateChatItem
• APIDeleteChatItem
• APIDeleteMemberChatItem
• APIChatItemReaction

File commands

• ReceiveFile
• CancelFile

Group commands

• APIAddMember
• APIJoinGroup
• APIAcceptMember
• APIMembersRole
• APIBlockMembersForAll
• APIRemoveMembers
• APILeaveGroup
• APIListMembers
• APINewGroup
• APIUpdateGroupProfile

Group link commands

• APICreateGroupLink
• APIGroupLinkMemberRole
• APIDeleteGroupLink
• APIGetGroupLink

Connection commands

• APIAddContact
• APIConnectPlan
• APIConnect
• Connect
• APIAcceptContact
• APIRejectContact

Chat commands

• APIListContacts
• APIListGroups
• APIDeleteChat

User profile commands

• ShowActiveUser
• CreateActiveUser
• ListUsers
• APISetActiveUser
• APIDeleteUser
• APIUpdateProfile
• APISetContactPrefs

Chat management

• StartChat
• APIStopChat

---

Address commands

Bots can use these commands to automatically check and create address when initialized

APICreateMyAddress

Create bot address.

Network usage: interactive.

Parameters:

• userId: int64

Syntax:

/_address <userId>

'/_address ' + userId // JavaScript

'/_address ' + str(userId) # Python

Responses:

UserContactLinkCreated: User contact address created.

• type: "userContactLinkCreated"
• user: User
• connLinkContact: CreatedConnLink

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIDeleteMyAddress

Delete bot address.

Network usage: background.

Parameters:

• userId: int64

Syntax:

/_delete_address <userId>

'/_delete_address ' + userId // JavaScript

'/_delete_address ' + str(userId) # Python

Responses:

UserContactLinkDeleted: User contact address deleted.

• type: "userContactLinkDeleted"
• user: User

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIShowMyAddress

Get bot address and settings.

Network usage: no.

Parameters:

• userId: int64

Syntax:

/_show_address <userId>

'/_show_address ' + userId // JavaScript

'/_show_address ' + str(userId) # Python

Responses:

UserContactLink: User contact address.

• type: "userContactLink"
• user: User
• contactLink: UserContactLink

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APISetProfileAddress

Add address to bot profile.

Network usage: interactive.

Parameters:

• userId: int64
• enable: bool

Syntax:

/_profile_address <userId> on|off

'/_profile_address ' + userId + ' ' + (enable ? 'on' : 'off') // JavaScript

'/_profile_address ' + str(userId) + ' ' + ('on' if enable else 'off') # Python

Responses:

UserProfileUpdated: User profile updated.

• type: "userProfileUpdated"
• user: User
• fromProfile: Profile
• toProfile: Profile
• updateSummary: UserProfileUpdateSummary

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APISetAddressSettings

Set bot address settings.

Network usage: interactive.

Parameters:

• userId: int64
• settings: AddressSettings

Syntax:

/_address_settings <userId> <json(settings)>

'/_address_settings ' + userId + ' ' + JSON.stringify(settings) // JavaScript

'/_address_settings ' + str(userId) + ' ' + json.dumps(settings) # Python

Responses:

UserContactLinkUpdated: User contact address updated.

• type: "userContactLinkUpdated"
• user: User
• contactLink: UserContactLink

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

Message commands

Commands to send, update, delete, moderate messages and set message reactions

APISendMessages

Send messages.

Network usage: background.

Parameters:

• sendRef: ChatRef
• liveMessage: bool
• ttl: int?
• composedMessages: [ComposedMessage]

Syntax:

/_send <str(sendRef)>[ live=on][ ttl=<ttl>] json <json(composedMessages)>

'/_send ' + ChatRef.cmdString(sendRef) + (liveMessage ? ' live=on' : '') + (ttl ? ' ttl=' + ttl : '') + ' json ' + JSON.stringify(composedMessages) // JavaScript

'/_send ' + str(sendRef) + (' live=on' if liveMessage else '') + ((' ttl=' + str(ttl)) if ttl is not None else '') + ' json ' + json.dumps(composedMessages) # Python

Responses:

NewChatItems: New messages.

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

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIUpdateChatItem

Update message.

Network usage: background.

Parameters:

• chatRef: ChatRef
• chatItemId: int64
• liveMessage: bool
• updatedMessage: UpdatedMessage

Syntax:

/_update item <str(chatRef)> <chatItemId>[ live=on] json <json(updatedMessage)>

'/_update item ' + ChatRef.cmdString(chatRef) + ' ' + chatItemId + (liveMessage ? ' live=on' : '') + ' json ' + JSON.stringify(updatedMessage) // JavaScript

'/_update item ' + str(chatRef) + ' ' + str(chatItemId) + (' live=on' if liveMessage else '') + ' json ' + json.dumps(updatedMessage) # Python

Responses:

ChatItemUpdated: Message updated.

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

ChatItemNotChanged: Message not changed.

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

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

Errors:

• InvalidChatItemUpdate: Not user's message or cannot be edited.

---

APIDeleteChatItem

Delete message.

Network usage: background.

Parameters:

• chatRef: ChatRef
• chatItemIds: [int64]
• deleteMode: CIDeleteMode

Syntax:

/_delete item <str(chatRef)> <chatItemIds[0]>[,<chatItemIds[1]>...] broadcast|internal|internalMark

'/_delete item ' + ChatRef.cmdString(chatRef) + ' ' + chatItemIds.join(',') + ' ' + deleteMode // JavaScript

'/_delete item ' + str(chatRef) + ' ' + ','.join(map(str, chatItemIds)) + ' ' + str(deleteMode) # Python

Responses:

ChatItemsDeleted: Messages deleted.

• type: "chatItemsDeleted"
• user: User
• chatItemDeletions: [ChatItemDeletion]
• byUser: bool
• timed: bool

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIDeleteMemberChatItem

Moderate message. Requires Moderator role (and higher than message author's).

Network usage: background.

Parameters:

• groupId: int64
• chatItemIds: [int64]

Syntax:

/_delete member item #<groupId> <chatItemIds[0]>[,<chatItemIds[1]>...]

'/_delete member item #' + groupId + ' ' + chatItemIds.join(',') // JavaScript

'/_delete member item #' + str(groupId) + ' ' + ','.join(map(str, chatItemIds)) # Python

Responses:

ChatItemsDeleted: Messages deleted.

• type: "chatItemsDeleted"
• user: User
• chatItemDeletions: [ChatItemDeletion]
• byUser: bool
• timed: bool

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIChatItemReaction

Add/remove message reaction.

Network usage: background.

Parameters:

• chatRef: ChatRef
• chatItemId: int64
• add: bool
• reaction: MsgReaction

Syntax:

/_reaction <str(chatRef)> <chatItemId> on|off <json(reaction)>

'/_reaction ' + ChatRef.cmdString(chatRef) + ' ' + chatItemId + ' ' + (add ? 'on' : 'off') + ' ' + JSON.stringify(reaction) // JavaScript

'/_reaction ' + str(chatRef) + ' ' + str(chatItemId) + ' ' + ('on' if add else 'off') + ' ' + json.dumps(reaction) # Python

Responses:

ChatItemReaction: Message reaction.

• type: "chatItemReaction"
• user: User
• added: bool
• reaction: ACIReaction

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

File commands

Commands to receive and to cancel files. Files are sent as part of the message, there are no separate commands to send files.

ReceiveFile

Receive file.

Network usage: no.

Parameters:

• fileId: int64
• userApprovedRelays: bool
• storeEncrypted: bool?
• fileInline: bool?
• filePath: string?

Syntax:

/freceive <fileId>[ approved_relays=on][ encrypt=on|off][ inline=on|off][ <filePath>]

'/freceive ' + fileId + (userApprovedRelays ? ' approved_relays=on' : '') + (typeof storeEncrypted == 'boolean' ? ' encrypt=' + (storeEncrypted ? 'on' : 'off') : '') + (typeof fileInline == 'boolean' ? ' inline=' + (fileInline ? 'on' : 'off') : '') + (filePath ? ' ' + filePath : '') // JavaScript

'/freceive ' + str(fileId) + (' approved_relays=on' if userApprovedRelays else '') + ((' encrypt=' + ('on' if storeEncrypted else 'off')) if storeEncrypted is not None else '') + ((' inline=' + ('on' if fileInline else 'off')) if fileInline is not None else '') + ((' ' + filePath) if filePath is not None else '') # Python

Responses:

RcvFileAccepted: File accepted to be received.

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

RcvFileAcceptedSndCancelled: File accepted, but no longer sent.

• type: "rcvFileAcceptedSndCancelled"
• user: User
• rcvFileTransfer: RcvFileTransfer

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

CancelFile

Cancel file.

Network usage: background.

Parameters:

• fileId: int64

Syntax:

/fcancel <fileId>

'/fcancel ' + fileId // JavaScript

'/fcancel ' + str(fileId) # Python

Responses:

SndFileCancelled: Cancelled sending file.

• type: "sndFileCancelled"
• user: User
• chatItem_: AChatItem?
• fileTransferMeta: FileTransferMeta
• sndFileTransfers: [SndFileTransfer]

RcvFileCancelled: Cancelled receiving file.

• type: "rcvFileCancelled"
• user: User
• chatItem_: AChatItem?
• rcvFileTransfer: RcvFileTransfer

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

Errors:

• FileCancel: Cannot cancel file.

---

Group commands

Commands to manage and moderate groups. These commands can be used with business chats as well - they are groups. E.g., a common scenario would be to add human agents to business chat with the customer who connected via business address.

APIAddMember

Add contact to group. Requires bot to have Admin role.

Network usage: interactive.

Parameters:

• groupId: int64
• contactId: int64
• memberRole: GroupMemberRole

Syntax:

/_add #<groupId> <contactId> observer|author|member|moderator|admin|owner

'/_add #' + groupId + ' ' + contactId + ' ' + memberRole // JavaScript

'/_add #' + str(groupId) + ' ' + str(contactId) + ' ' + str(memberRole) # Python

Responses:

SentGroupInvitation: Group invitation sent.

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

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIJoinGroup

Join group.

Network usage: interactive.

Parameters:

• groupId: int64

Syntax:

/_join #<groupId>

'/_join #' + groupId // JavaScript

'/_join #' + str(groupId) # Python

Responses:

UserAcceptedGroupSent: User accepted group invitation.

• type: "userAcceptedGroupSent"
• user: User
• groupInfo: GroupInfo
• hostContact: Contact?

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIAcceptMember

Accept group member. Requires Admin role.

Network usage: background.

Parameters:

• groupId: int64
• groupMemberId: int64
• memberRole: GroupMemberRole

Syntax:

/_accept member #<groupId> <groupMemberId> observer|author|member|moderator|admin|owner

'/_accept member #' + groupId + ' ' + groupMemberId + ' ' + memberRole // JavaScript

'/_accept member #' + str(groupId) + ' ' + str(groupMemberId) + ' ' + str(memberRole) # Python

Responses:

MemberAccepted: Member accepted to group.

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

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

Errors:

• GroupMemberNotActive: Member is not connected yet.

---

APIMembersRole

Set members role. Requires Admin role.

Network usage: background.

Parameters:

• groupId: int64
• groupMemberIds: [int64]
• memberRole: GroupMemberRole

Syntax:

/_member role #<groupId> <groupMemberIds[0]>[,<groupMemberIds[1]>...] observer|author|member|moderator|admin|owner

'/_member role #' + groupId + ' ' + groupMemberIds.join(',') + ' ' + memberRole // JavaScript

'/_member role #' + str(groupId) + ' ' + ','.join(map(str, groupMemberIds)) + ' ' + str(memberRole) # Python

Responses:

MembersRoleUser: Members role changed by user.

• type: "membersRoleUser"
• user: User
• groupInfo: GroupInfo
• members: [GroupMember]
• toRole: GroupMemberRole

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIBlockMembersForAll

Block members. Requires Moderator role.

Network usage: background.

Parameters:

• groupId: int64
• groupMemberIds: [int64]
• blocked: bool

Syntax:

/_block #<groupId> <groupMemberIds[0]>[,<groupMemberIds[1]>...] blocked=on|off

'/_block #' + groupId + ' ' + groupMemberIds.join(',') + ' blocked=' + (blocked ? 'on' : 'off') // JavaScript

'/_block #' + str(groupId) + ' ' + ','.join(map(str, groupMemberIds)) + ' blocked=' + ('on' if blocked else 'off') # Python

Responses:

MembersBlockedForAllUser: Members blocked for all by admin.

• type: "membersBlockedForAllUser"
• user: User
• groupInfo: GroupInfo
• members: [GroupMember]
• blocked: bool

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIRemoveMembers

Remove members. Requires Admin role.

Network usage: background.

Parameters:

• groupId: int64
• groupMemberIds: [int64]
• withMessages: bool

Syntax:

/_remove #<groupId> <groupMemberIds[0]>[,<groupMemberIds[1]>...][ messages=on]

'/_remove #' + groupId + ' ' + groupMemberIds.join(',') + (withMessages ? ' messages=on' : '') // JavaScript

'/_remove #' + str(groupId) + ' ' + ','.join(map(str, groupMemberIds)) + (' messages=on' if withMessages else '') # Python

Responses:

UserDeletedMembers: Members deleted.

• type: "userDeletedMembers"
• user: User
• groupInfo: GroupInfo
• members: [GroupMember]
• withMessages: bool

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

Errors:

• GroupMemberNotFound: Group member not found.

---

APILeaveGroup

Leave group.

Network usage: background.

Parameters:

• groupId: int64

Syntax:

/_leave #<groupId>

'/_leave #' + groupId // JavaScript

'/_leave #' + str(groupId) # Python

Responses:

LeftMemberUser: User left group.

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

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIListMembers

Get group members.

Network usage: no.

Parameters:

• groupId: int64

Syntax:

/_members #<groupId>

'/_members #' + groupId // JavaScript

'/_members #' + str(groupId) # Python

Responses:

GroupMembers: Group members.

• type: "groupMembers"
• user: User
• group: Group

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APINewGroup

Create group.

Network usage: no.

Parameters:

• userId: int64
• incognito: bool
• groupProfile: GroupProfile

Syntax:

/_group <userId>[ incognito=on] <json(groupProfile)>

'/_group ' + userId + (incognito ? ' incognito=on' : '') + ' ' + JSON.stringify(groupProfile) // JavaScript

'/_group ' + str(userId) + (' incognito=on' if incognito else '') + ' ' + json.dumps(groupProfile) # Python

Responses:

GroupCreated: Group created.

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

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIUpdateGroupProfile

Update group profile.

Network usage: background.

Parameters:

• groupId: int64
• groupProfile: GroupProfile

Syntax:

/_group_profile #<groupId> <json(groupProfile)>

'/_group_profile #' + groupId + ' ' + JSON.stringify(groupProfile) // JavaScript

'/_group_profile #' + str(groupId) + ' ' + json.dumps(groupProfile) # Python

Responses:

GroupUpdated: Group updated.

• type: "groupUpdated"
• user: User
• fromGroup: GroupInfo
• toGroup: GroupInfo
• member_: GroupMember?

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

Group link commands

These commands can be used by bots that manage multiple public groups

APICreateGroupLink

Create group link.

Network usage: interactive.

Parameters:

• groupId: int64
• memberRole: GroupMemberRole

Syntax:

/_create link #<groupId> observer|author|member|moderator|admin|owner

'/_create link #' + groupId + ' ' + memberRole // JavaScript

'/_create link #' + str(groupId) + ' ' + str(memberRole) # Python

Responses:

GroupLinkCreated: Group link created.

• type: "groupLinkCreated"
• user: User
• groupInfo: GroupInfo
• groupLink: GroupLink

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIGroupLinkMemberRole

Set member role for group link.

Network usage: no.

Parameters:

• groupId: int64
• memberRole: GroupMemberRole

Syntax:

/_set link role #<groupId> observer|author|member|moderator|admin|owner

'/_set link role #' + groupId + ' ' + memberRole // JavaScript

'/_set link role #' + str(groupId) + ' ' + str(memberRole) # Python

Responses:

GroupLink: Group link.

• type: "groupLink"
• user: User
• groupInfo: GroupInfo
• groupLink: GroupLink

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIDeleteGroupLink

Delete group link.

Network usage: background.

Parameters:

• groupId: int64

Syntax:

/_delete link #<groupId>

'/_delete link #' + groupId // JavaScript

'/_delete link #' + str(groupId) # Python

Responses:

GroupLinkDeleted: Group link deleted.

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

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIGetGroupLink

Get group link.

Network usage: no.

Parameters:

• groupId: int64

Syntax:

/_get link #<groupId>

'/_get link #' + groupId // JavaScript

'/_get link #' + str(groupId) # Python

Responses:

GroupLink: Group link.

• type: "groupLink"
• user: User
• groupInfo: GroupInfo
• groupLink: GroupLink

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

Connection commands

These commands may be used to create connections. Most bots do not need to use them - bot users will connect via bot address with auto-accept enabled.

APIAddContact

Create 1-time invitation link.

Network usage: interactive.

Parameters:

• userId: int64
• incognito: bool

Syntax:

/_connect <userId>[ incognito=on]

'/_connect ' + userId + (incognito ? ' incognito=on' : '') // JavaScript

'/_connect ' + str(userId) + (' incognito=on' if incognito else '') # Python

Responses:

Invitation: One-time invitation.

• type: "invitation"
• user: User
• connLinkInvitation: CreatedConnLink
• connection: PendingContactConnection

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIConnectPlan

Determine SimpleX link type and if the bot is already connected via this link.

Network usage: interactive.

Parameters:

• userId: int64
• connectionLink: string?

Syntax:

/_connect plan <userId> <connectionLink>

'/_connect plan ' + userId + ' ' + connectionLink // JavaScript

'/_connect plan ' + str(userId) + ' ' + connectionLink # Python

Responses:

ConnectionPlan: Connection link information.

• type: "connectionPlan"
• user: User
• connLink: CreatedConnLink
• connectionPlan: ConnectionPlan

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIConnect

Connect via prepared SimpleX link. The link can be 1-time invitation link, contact address or group link.

Network usage: interactive.

Parameters:

• userId: int64
• incognito: bool
• preparedLink_: CreatedConnLink?

Syntax:

/_connect <userId>[ <str(preparedLink_)>]

'/_connect ' + userId + (preparedLink_ ? ' ' + CreatedConnLink.cmdString(preparedLink_) : '') // JavaScript

'/_connect ' + str(userId) + ((' ' + str(preparedLink_)) if preparedLink_ is not None else '') # Python

Responses:

SentConfirmation: Confirmation sent to one-time invitation.

• type: "sentConfirmation"
• user: User
• connection: PendingContactConnection
• customUserProfile: Profile?

ContactAlreadyExists: Contact already exists.

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

SentInvitation: Invitation sent to contact address.

• type: "sentInvitation"
• user: User
• connection: PendingContactConnection
• customUserProfile: Profile?

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

Connect

Connect via SimpleX link as string in the active user profile.

Network usage: interactive.

Parameters:

• incognito: bool
• connLink_: string?

Syntax:

/connect[ <connLink_>]

'/connect' + (connLink_ ? ' ' + connLink_ : '') // JavaScript

'/connect' + ((' ' + connLink_) if connLink_ is not None else '') # Python

Responses:

SentConfirmation: Confirmation sent to one-time invitation.

• type: "sentConfirmation"
• user: User
• connection: PendingContactConnection
• customUserProfile: Profile?

ContactAlreadyExists: Contact already exists.

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

SentInvitation: Invitation sent to contact address.

• type: "sentInvitation"
• user: User
• connection: PendingContactConnection
• customUserProfile: Profile?

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIAcceptContact

Accept contact request.

Network usage: interactive.

Parameters:

• contactReqId: int64

Syntax:

/_accept <contactReqId>

'/_accept ' + contactReqId // JavaScript

'/_accept ' + str(contactReqId) # Python

Responses:

AcceptingContactRequest: Contact request accepted.

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

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIRejectContact

Reject contact request. The user who sent the request is not notified.

Network usage: no.

Parameters:

• contactReqId: int64

Syntax:

/_reject <contactReqId>

'/_reject ' + contactReqId // JavaScript

'/_reject ' + str(contactReqId) # Python

Responses:

ContactRequestRejected: Contact request rejected.

• type: "contactRequestRejected"
• user: User
• contactRequest: UserContactRequest
• contact_: Contact?

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

Chat commands

Commands to list and delete conversations.

APIListContacts

Get contacts.

Network usage: no.

Parameters:

• userId: int64

Syntax:

/_contacts <userId>

'/_contacts ' + userId // JavaScript

'/_contacts ' + str(userId) # Python

Responses:

ContactsList: Contacts.

• type: "contactsList"
• user: User
• contacts: [Contact]

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIListGroups

Get groups.

Network usage: no.

Parameters:

• userId: int64
• contactId_: int64?
• search: string?

Syntax:

/_groups <userId>[ @<contactId_>][ <search>]

'/_groups ' + userId + (contactId_ ? ' @' + contactId_ : '') + (search ? ' ' + search : '') // JavaScript

'/_groups ' + str(userId) + ((' @' + str(contactId_)) if contactId_ is not None else '') + ((' ' + search) if search is not None else '') # Python

Responses:

GroupsList: Groups.

• type: "groupsList"
• user: User
• groups: [GroupInfo]

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIDeleteChat

Delete chat.

Network usage: background.

Parameters:

• chatRef: ChatRef
• chatDeleteMode: ChatDeleteMode

Syntax:

/_delete <str(chatRef)> <str(chatDeleteMode)>

'/_delete ' + ChatRef.cmdString(chatRef) + ' ' + ChatDeleteMode.cmdString(chatDeleteMode) // JavaScript

'/_delete ' + str(chatRef) + ' ' + str(chatDeleteMode) # Python

Responses:

ContactDeleted: Contact deleted.

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

ContactConnectionDeleted: Connection deleted.

• type: "contactConnectionDeleted"
• user: User
• connection: PendingContactConnection

GroupDeletedUser: User deleted group.

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

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

User profile commands

Most bots don't need to use these commands, as bot profile can be configured manually via CLI or desktop client. These commands can be used by bots that need to manage multiple user profiles (e.g., the profiles of support agents).

ShowActiveUser

Get active user profile.

Network usage: no.

Syntax:

/user

Responses:

ActiveUser: Active user profile.

• type: "activeUser"
• user: User

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

CreateActiveUser

Create new user profile.

Network usage: no.

Parameters:

• newUser: NewUser

Syntax:

/_create user <json(newUser)>

'/_create user ' + JSON.stringify(newUser) // JavaScript

'/_create user ' + json.dumps(newUser) # Python

Responses:

ActiveUser: Active user profile.

• type: "activeUser"
• user: User

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

Errors:

• UserExists: User or contact with this name already exists.
• InvalidDisplayName: Invalid user display name.

---

ListUsers

Get all user profiles.

Network usage: no.

Syntax:

/users

Responses:

UsersList: Users.

• type: "usersList"
• users: [UserInfo]

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APISetActiveUser

Set active user profile.

Network usage: no.

Parameters:

• userId: int64
• viewPwd: string?

Syntax:

/_user <userId>[ <json(viewPwd)>]

'/_user ' + userId + (viewPwd ? ' ' + JSON.stringify(viewPwd) : '') // JavaScript

'/_user ' + str(userId) + ((' ' + json.dumps(viewPwd)) if viewPwd is not None else '') # Python

Responses:

ActiveUser: Active user profile.

• type: "activeUser"
• user: User

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

Errors:

• ChatNotStarted: Chat not started.

---

APIDeleteUser

Delete user profile.

Network usage: background.

Parameters:

• userId: int64
• delSMPQueues: bool
• viewPwd: string?

Syntax:

/_delete user <userId> del_smp=on|off[ <json(viewPwd)>]

'/_delete user ' + userId + ' del_smp=' + (delSMPQueues ? 'on' : 'off') + (viewPwd ? ' ' + JSON.stringify(viewPwd) : '') // JavaScript

'/_delete user ' + str(userId) + ' del_smp=' + ('on' if delSMPQueues else 'off') + ((' ' + json.dumps(viewPwd)) if viewPwd is not None else '') # Python

Responses:

CmdOk: Ok.

• type: "cmdOk"
• user_: User?

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APIUpdateProfile

Update user profile.

Network usage: background.

Parameters:

• userId: int64
• profile: Profile

Syntax:

/_profile <userId> <json(profile)>

'/_profile ' + userId + ' ' + JSON.stringify(profile) // JavaScript

'/_profile ' + str(userId) + ' ' + json.dumps(profile) # Python

Responses:

UserProfileUpdated: User profile updated.

• type: "userProfileUpdated"
• user: User
• fromProfile: Profile
• toProfile: Profile
• updateSummary: UserProfileUpdateSummary

UserProfileNoChange: User profile was not changed.

• type: "userProfileNoChange"
• user: User

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

APISetContactPrefs

Configure chat preference overrides for the contact.

Network usage: background.

Parameters:

• contactId: int64
• preferences: Preferences

Syntax:

/_set prefs @<contactId> <json(preferences)>

'/_set prefs @' + contactId + ' ' + JSON.stringify(preferences) // JavaScript

'/_set prefs @' + str(contactId) + ' ' + json.dumps(preferences) # Python

Responses:

ContactPrefsUpdated: Contact preferences updated.

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

ChatCmdError: Command error (only used in WebSockets API).

• type: "chatCmdError"
• chatError: ChatError

---

Chat management

These commands should not be used with CLI-based bots

StartChat

Start chat controller.

Network usage: no.

Parameters:

• mainApp: bool
• enableSndFiles: bool

Syntax:

/_start

Responses:

ChatStarted: Chat started.

• type: "chatStarted"

ChatRunning: Chat running.

• type: "chatRunning"

---

APIStopChat

Stop chat controller.

Network usage: no.

Syntax:

/_stop

Response:

ChatStopped: Chat stopped.

• type: "chatStopped"

---