Console commands

This page is the reference of the commands a program can send to BeeBEEP's console, for whoever writes a bot or an integration. For each command it gives the scope it needs, its arguments and what it answers. How to start the console, connect and authenticate is on the console, and the events BeeBEEP sends are on the events page.

How to read this page

A command is a JSON object on one line, with the command's name in cmd and its arguments as the other keys:

{"cmd":"send_message","chatId":1001,"text":"Ciao"}

BeeBEEP answers with one line, {"ok":true,"data":{...}} or {"ok":false,"error":"..."}; the replies and their codes are on the console page.

The commands are listed from Connection and control on, by what they are for. Each one gives its scope: the lowest scope that may call it, as the scopes explain. A connection below it gets scopeTooLow, and does not see the command in help. The page lists the commands of the admin scope; the commands of the debug scope exist only in a console started for development and are not here.

An argument has a type and may be required. In the table of a command:

The text of a description is the program's own, as help gives it.

Identifiers and formats

• A user is a number, its id, which list_users and get_user give. Your own id is 1, and status gives it as localUserId. Ids are local to one installation: another installation numbers the same user differently. What names a user everywhere is its uuid.
• A group is a number, its id, and also a uuid that is the same on every member's computer.
• A chat is a number, the chatId of the commands: the id of the other user for a private chat, the id of a group for a group, and 2 for Chat with Everyone, which the descriptions call ID_DEFAULT_CHAT. 1, your own id, is never a chat. In a chat message, groupId is the chat's number.
• A message, a file transfer or an invitation is named by a uuid, written as text without braces, such as 21ed7cf7-b9ee-4bd2-ae4d-3703c838b635. An argument that takes a uuid accepts it with or without braces, in lower or upper case, but with its hyphens.
• A time is a whole number of milliseconds since 1970-01-01 UTC, 0 for none.
• A key is lowercase hexadecimal text, empty while there is none.

Files and paths

send_file, send_voice_message, set_avatar and set_group_avatar take a filePath on the computer BeeBEEP runs on. Below admin it must lie inside the console's file root, and without a file root these commands need admin: see files.

What the commands answer

A command with nothing to say answers data empty, {}. The others put these keys in data:

A user

list_users and get_user answer with this object for each user:

{"id":1001,"uuid":"2cc610c7-3375-54c3-957f-8be4ea6f7083","displayName":"Christian","firstName":"","lastName":"","birthDate":"","email":"","phoneNumber":"","location":"","info":"","color":"#FF4040","status":"Online","notResponding":false,"outOfSight":false,"queuedMessages":0,"participatesInDefaultChat":true,"acceptsFileTransfers":true,"acceptsVoiceMessages":true,"relayMode":"Everyone","circles":[],"pluginCapabilities":[],"avatarHash":"","lastConnection":1791265201802,"lastSeenActiveDay":1,"isFavorite":false,"relationship":"Discovered","relationshipOrigin":"Undecided","relationshipNetworkId":"","contactSuspendedByKeyChange":false,"effectiveRelationship":"Discovered","e2ePublicKey":"","signingPublicKey":"","proven":false,"trustSource":"unverified","introducedBy":""}

A group

{"id":1002,"uuid":"b54db1d4-e942-4145-87b7-7aa64e586f00","name":"Lunch","color":"#C08040","memberIds":[1,1001],"adminIds":[1],"isDefault":false}

memberIds and adminIds are user ids, yours (1) included; isDefault is true for Chat with Everyone. list_groups adds muted.

A chat message

get_chat_history answers with these objects, and chatMessageAdded carries one:

{"id":42,"messageUuid":"21ed7cf7-b9ee-4bd2-ae4d-3703c838b635","groupId":1001,"senderId":1,"senderName":"Alessandra","text":"Ciao","timestamp":1791265285598,"overallState":"Delivered","isAutoResponse":false,"isTemporary":false,"chatKind":"private","reactions":[]}

A message with a file has an attachment, with fileName, fileSize, contentHash and mimeType; a voice note's adds isVoiceMessage, durationMs and waveform, and the message gains isVoicePlayed. A group invitation has an invitation (groupUuid, groupName, memberCount, invitationId, expiresAt) and the answer to one an invitationAnswer (groupUuid, invitationId, answer).

In the reply of get_chat_history every message also has recipients, one entry for each user it went to, with recipientId, state (the same words as overallState), deliveredAt and readAt, 0 while that step has not happened. The events leave recipients out, so that the events of a message sent to many users stay small: ask get_chat_history for the states.

A file transfer

{"messageUuid":"21ed7cf7-b9ee-4bd2-ae4d-3703c838b635","peerUuid":"2cc610c7-3375-54c3-957f-8be4ea6f7083","direction":"Receive","state":"Transferring","fileName":"report.pdf","fileSize":481920,"bytesCheckpoint":204800,"contentHash":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","localPath":"/data/downloads/report.pdf","updatedAt":1735599999000,"offeredActiveDay":0}

direction is Send or Receive; state is Offered, Accepted, Requesting, Transferring, Paused, Completed, Rejected, Failed or Canceled. bytesCheckpoint is the last offset known to be safe on disk, and lags the live count: watch fileTransferProgress for that. localPath is the source file of a sent file and, once a received file is Completed, where it was saved. peerUuid is the uuid of the other user, not its id.

Connection and control

auth

Presents one role's password (read, user or admin): the connection gets that role's scope, capped by --console-max-scope.

Scope: none.

help

Lists every command, or describes one named command.

Scope: read.

subscribe

Starts the event channel on this connection (already on by default): every event, or only the ones named.

Scope: read.

unsubscribe

Stops the event channel on this connection.

Scope: read. Takes no arguments.

disconnect

Closes only the calling connection; BeeBEEP keeps running.

Scope: read. Takes no arguments.

quit

Shuts the whole BeeBEEP process down cleanly.

Scope: admin. Takes no arguments.

You and your settings

status

Returns a summary of the local user and how many remote users are currently online.

Scope: read. Takes no arguments.

set

Sets one runtime parameter, named by param, to value. Each parameter has its own values and needs its own scope, as the tables below say.

Scope: read.

The values of value depend on param:

set_profile

Updates one or more fields of the local user's own profile.

Scope: user.

set_preferences

Updates one or more of the local user's own declared preferences.

Scope: user.

set_avatar

Loads a local image file and sets it as the local user's own avatar.

Scope: user.

set_chat_muted

Mutes or unmutes one chat's notifications; its unread count and its place in the list are unaffected.

Scope: user.

get_circles

The local user's circles, and whether the administrator's policy file sets them.

Scope: read. Takes no arguments.

circles_heard

The circles announced on this network lately, in sight or not: the ones to offer when a circle is added.

Scope: read. Takes no arguments.

set_circles

Replaces the local user's circles; nothing changes if one name is refused.

Scope: user.

Users

list_users

Lists every known remote user (never the local user).

Scope: read. Takes no arguments.

get_user

Looks up one user by id.

Scope: read.

set_favorite

Marks or unmarks a contact as a favorite -- it only orders the user list and grants no permission.

Scope: user.

set_relationship

Sets by hand what a peer is to the local user -- Discovered or Contact; a private network never overrides it.

Scope: user.

request_profile_details

Asks a peer for its extended profile fields and avatar, if currently online -- fire-and-forget, watch userUpdated/chatMessageAdded events.

Scope: user.

request_user_gallery

Asks a peer for its gallery, if currently online -- fire-and-forget, watch userUpdated/chatMessageAdded events.

Scope: user.

block_user

Blocks a contact by identity: persisted, and refuses that peer's connections (in or out) from now on, closing its current one immediately if it has one.

Scope: admin.

unblock_user

Reverses a previous block_user -- this peer may connect again from now on.

Scope: admin.

list_blocked_users

Lists every currently blocked peer.

Scope: read. Takes no arguments.

Chats and messages

get_chat_history

Returns a page of persisted chat history for one chat, newest first.

Scope: read.

send_message

Sends a chat message.

Scope: user.

send_reaction

Sets, replaces, or removes this instance's own emoji reaction on a message. Asking for the emoji already in place removes it. Watch the chatMessageReactionChanged event on every side.

Scope: user.

send_typing

Announces this instance is/isn't typing (or recording a voice note) in a chat -- never ID_DEFAULT_CHAT. Watch the typingStateChanged event on the peer's own side.

Scope: user.

mark_read

Marks every unread message in a chat as Read.

Scope: user.

get_unread_counts

Returns every chat's current unread-message count.

Scope: read. Takes no arguments.

list_archives

Lists the archived chats (the history of a BeeBEEP 5.x installation, imported, read only), the most recent first.

Scope: read. Takes no arguments.

get_archive

Returns one archived chat and a page of its messages as plain text, oldest first.

Scope: read.

delete_archive

Deletes one archived chat from this device; importing the old installation again brings it back while its files are still there.

Scope: user.

Files

send_file

Offers a local file as a chat attachment. Never ID_DEFAULT_CHAT.

Scope: user.

send_voice_message

Offers a local audio file as a voice note, as a recording would be. Never ID_DEFAULT_CHAT.

Scope: user.

accept_file_transfer

Accepts a pending incoming file offer -- watch the fileTransferOfferReceived event for its messageUuid.

Scope: user.

reject_file_transfer

Declines a pending incoming file offer.

Scope: user.

pause_file_transfer

Pauses a currently-active file transfer, notifying the peer.

Scope: user.

resume_file_transfer

Resumes a previously-paused (or restart-survived) file transfer.

Scope: user.

cancel_file_transfer

Abandons a file transfer outright, deleting the partial file; its record stays, state Canceled.

Scope: user.

list_file_transfers

Returns every currently active file transfer (Requesting/Transferring/Paused, either direction).

Scope: read. Takes no arguments.

get_file_transfer

Returns every transfer record of one message, in any state -- more than one in a group send.

Scope: read.

Groups

create_group

Creates a new custom group owned by the local user.

Scope: user.

list_groups

Lists every group, including the Default group.

Scope: read. Takes no arguments.

get_group

Looks up one group by id.

Scope: read.

set_group_identity

Renames and/or recolors a group the local user administers.

Scope: user.

set_group_avatar

Sets the avatar of a group the local user administers.

Scope: user.

add_user_to_group

Adds a user to a group the local user administers.

Scope: user.

invite_to_group

Invites one of our Contacts to a group the local user administers, in their private chat.

Scope: user.

list_group_invitations

Lists the invitations the local user sent for a group, with their state.

Scope: read.

withdraw_group_invitation

Withdraws a pending invitation (local only: a late acceptance is answered "no longer valid").

Scope: user.

answer_group_invitation

Accepts or declines an invitation received in the private chat with its inviter (the fields of groupInvitationReceived).

Scope: user.

list_group_acceptances

Lists the invitations the local user accepted whose group has not arrived yet ("joining...").

Scope: read. Takes no arguments.

remove_user_from_group

Removes a member from a group the local user administers.

Scope: user.

set_group_admin

Promotes or demotes a member as admin of a group the local user administers.

Scope: user.

claim_group_admin

Claims admin of a group the local user is a member of but that currently has no admin at all (e.g. its sole admin left).

Scope: user.

leave_group

Removes the local user from a group -- never admin-gated, leaving is always a member's own call.

Scope: user.

Plugins

list_plugins

Lists the registered plugins with their manifests (id, version, name, category, modes), the policy file's rules on plugins and what the loader refused.

Scope: read. Takes no arguments.

invite_to_plugin_session

Puts a plugin session together: an invitation in each user's private chat; the session starts on the last acceptance.

Scope: user.

answer_plugin_invite

Accepts or declines an invitation to a plugin session received in the private chat with its inviter (the fields of pluginInviteReceived).

Scope: user.

replace_plugin_participant

Gives a refused or expired seat of a session being put together to another user (or the same one again).

Scope: user.

start_plugin_session

Starts a session being put together with whoever accepted so far, a refused seat left out (the inviter's explicit start).

Scope: user.

send_plugin_data

Sends bytes into an active plugin session as its plugin would.

Scope: user.

list_plugin_sessions

Lists every plugin session this side knows: inviting, active, suspended, ended (until pruned).

Scope: read. Takes no arguments.

suspend_plugin_session

Puts a persistent active plugin session aside on this side.

Scope: user.

resume_plugin_session

Runs a suspended plugin session again (after a restart, every persistent session is suspended).

Scope: user.

end_plugin_session

Ends a plugin session for everybody.

Scope: user.

Network

list_networks

Lists every network this installation has joined, with its category, and the networks it is on right now.

Scope: read. Takes no arguments.

set_network_category

Classifies a joined network as Private or Public -- refused while the operating system decides (Windows).

Scope: admin.

revert_network_promotions

Demotes back to Discovered every peer a network made a Contact on its own; decisions made by hand are kept.

Scope: admin.

set_network_password

Updates the pre-shared network password and/or whether it's applied; an actual change live-restarts the network+Bluetooth threads.

Scope: admin.

connect_to_address

Dials a peer at host:port, the way the manual "+" flow does -- watch userConnected, or list_links for a second link to a known peer; a host name that resolves to nothing comes back as hostNotFound, an address the administrator's list leaves out as dialRefused.

Scope: admin.

list_links

Lists a peer's live links, TCP or Bluetooth: id, class, local interface, both addresses, and which one is primary.

Scope: read.

list_leases

Lists the lease's claims per uuid: source, address, interface or link, seconds left, the last counter. Never a status.

Scope: read. Takes no arguments.

search_users

Starts whichever discovery mechanism(s) are requested, all under one shared time limit -- watch userConnected events as peers are found, and the searchCompleted event once the window closes.

Scope: user.

search_network_users

Sends a fresh presence announcement over the local LAN subnet broadcast -- watch userConnected events as peers are found.

Scope: user. Takes no arguments.

start_bluetooth_search

Starts advertising and scanning for nearby Bluetooth peers -- watch userConnected events as peers are found.

Scope: user. Takes no arguments.

stop_bluetooth_search

Stops advertising/scanning for nearby Bluetooth peers. Already-established links are unaffected.

Scope: user. Takes no arguments.

start_multicast_search

Joins the well-known multicast group and sends one announcement -- watch userConnected events as peers are found.

Scope: user. Takes no arguments.

stop_multicast_search

Leaves the multicast group. Already-established links are unaffected.

Scope: user. Takes no arguments.

network_stats

Reports what the network has cost so far: bytes and frames per message type, connections, dials, handshakes, worst tick lateness.

Scope: read.

set_parameter

Sets one named runtime scaling parameter, live -- the same names --param= and beebeep.rc's [Scaling] section take; network_stats reports the values in force.

Scope: admin.

Clock and maintenance

clock_status

Reports what this instance thinks the time is, what the machine's own clock says, and whether it is below a floor: the date of this build (Build) or the last date this installation wrote down (Stored).

Scope: read. Takes no arguments.

set_clock_time

Gives this instance the real time, as the banner's own dialog does -- refused below this build's own commit date. Never touches the system clock.

Scope: admin.

import_legacy_installation

Imports an old BeeBEEP 5.x installation's contacts, groups and missing profile fields, merging with what this installation already has, and its saved chats as archives (chatArchivesImported follows).

Scope: admin.