Skip to content

List chat accounts

accounts.list() -> AccountListResponse

GET/v1/accounts

List chat accounts connected to this Beeper Client API server, including bridge, network, user identity, and connection status.

ReturnsExpand Collapse

Chat accounts configured on this device. Includes accountID, bridge metadata, optional network name, and user identity.

account_id: str

Chat account added to Beeper. Use this to route account-scoped actions. Examples include matrix for Beeper/Matrix, discordgo for a cloud bridge, slackgo.TEAM-USER for workspace-scoped cloud bridges, and local-whatsapp_ba_… for local bridges.

bridge: AccountBridge

Bridge metadata for the account. Available in Beeper Desktop v4.2.785+.

id: str

Bridge identifier. Beeper Cloud accounts often use the network type (for example matrix or discordgo); on-device accounts use a local bridge ID (for example local-whatsapp). Available in Beeper Desktop v4.2.785+.

provider: Literal["cloud", "self-hosted", "local", "platform-sdk"]

Where this account runs: on this device or in Beeper Cloud. Available in Beeper Desktop v4.2.785+.

One of the following:

"cloud"

"self-hosted"

"local"

"platform-sdk"

type: str

Bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. Available in Beeper Desktop v4.2.785+.

status: Literal["connected", "connecting", "backfilling", 5 more]

Current connection status for this account.

One of the following:

"connected"

"connecting"

"backfilling"

"connection_required"

"reconnect_required"

"attention_required"

"disconnected"

"disabled"

user: User

User the account belongs to.

id: str

Stable Beeper user ID. Use as the primary key when referencing a person.

cannot_message: Optional[bool]

True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you.

email: Optional[str]

Email address if known. Not guaranteed verified.

full_name: Optional[str]

Display name as shown in clients (e.g., ‘Alice Example’). May include emojis.

img_url: Optional[str]

Avatar image URL if available. This may be a remote URL, media URL, data URL, or local file URL depending on the source. May be temporary or available only on this device; download promptly if durable access is needed.

is_self: Optional[bool]

True if this user represents the authenticated account’s own identity.

phone_number: Optional[str]

User’s phone number in E.164 format (e.g., ‘+14155552671’). Omit if unknown.

username: Optional[str]

Human-readable handle if available (e.g., ‘@alice’). May be network-specific and not globally unique.

capabilities: Optional[Dict[str, Optional[object]]]

Runtime chat/message capabilities for this connected account, when available.

login_id: Optional[str]

Bridge login ID for this account, when known. One bridge login can contain multiple chat accounts.

network: Optional[str]

Human-friendly network name for the account. Omitted when the network is unknown.

status_text: Optional[str]

Human-friendly account status text.

List chat accounts

import os
from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop(
    access_token=os.environ.get("BEEPER_ACCESS_TOKEN"),  # This is the default and can be omitted
)
accounts = client.accounts.list()
print(accounts)

[
  {
    "accountID": "matrix",
    "bridge": {
      "id": "matrix",
      "provider": "cloud",
      "type": "matrix"
    },
    "status": "connected",
    "user": {
      "id": "@batuhan:beeper.com",
      "cannotMessage": true,
      "email": "batuhan@example.com",
      "fullName": "Batuhan İçöz",
      "imgURL": "imgURL",
      "isSelf": true,
      "phoneNumber": "phoneNumber",
      "username": "batuhan:beeper.com"
    },
    "capabilities": {
      "foo": "bar"
    },
    "loginID": "matrix",
    "network": "Beeper",
    "statusText": "statusText"
  },
  {
    "accountID": "discordgo",
    "bridge": {
      "id": "discordgo",
      "provider": "cloud",
      "type": "discordgo"
    },
    "status": "connected",
    "user": {
      "id": "221590782384013314",
      "cannotMessage": true,
      "email": "email",
      "fullName": "Batuhan İçöz",
      "imgURL": "file:///Users/batuhan/Library/Application%20Support/BeeperTexts/media/local.beeper.com/batuhan_jmaNwqQPUITme6VV5OSXhH3ZYpmi9UyaYQ43S2UA9qkkzy11Q9JUAiv8TYmOkoQr",
      "isSelf": true,
      "phoneNumber": "phoneNumber",
      "username": "batuhanicoz"
    },
    "capabilities": {
      "foo": "bar"
    },
    "loginID": "discordgo",
    "network": "Discord",
    "statusText": "statusText"
  },
  {
    "accountID": "local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
    "bridge": {
      "id": "local-whatsapp",
      "provider": "local",
      "type": "whatsapp"
    },
    "status": "connected",
    "user": {
      "id": "ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
      "cannotMessage": true,
      "email": "email",
      "fullName": "Batuhan İçöz",
      "imgURL": "file:///Users/batuhan/Library/Application%20Support/BeeperTexts/media/localhostlocal-whatsapp/_gkBAAAAB1xsnfQKMTcwOTkzODU5MAkBAAAAB1xsnfQ",
      "isSelf": true,
      "phoneNumber": "+15550101001",
      "username": "username"
    },
    "capabilities": {
      "foo": "bar"
    },
    "loginID": "ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
    "network": "WhatsApp",
    "statusText": "statusText"
  }
]

Returns Examples

[
  {
    "accountID": "matrix",
    "bridge": {
      "id": "matrix",
      "provider": "cloud",
      "type": "matrix"
    },
    "status": "connected",
    "user": {
      "id": "@batuhan:beeper.com",
      "cannotMessage": true,
      "email": "batuhan@example.com",
      "fullName": "Batuhan İçöz",
      "imgURL": "imgURL",
      "isSelf": true,
      "phoneNumber": "phoneNumber",
      "username": "batuhan:beeper.com"
    },
    "capabilities": {
      "foo": "bar"
    },
    "loginID": "matrix",
    "network": "Beeper",
    "statusText": "statusText"
  },
  {
    "accountID": "discordgo",
    "bridge": {
      "id": "discordgo",
      "provider": "cloud",
      "type": "discordgo"
    },
    "status": "connected",
    "user": {
      "id": "221590782384013314",
      "cannotMessage": true,
      "email": "email",
      "fullName": "Batuhan İçöz",
      "imgURL": "file:///Users/batuhan/Library/Application%20Support/BeeperTexts/media/local.beeper.com/batuhan_jmaNwqQPUITme6VV5OSXhH3ZYpmi9UyaYQ43S2UA9qkkzy11Q9JUAiv8TYmOkoQr",
      "isSelf": true,
      "phoneNumber": "phoneNumber",
      "username": "batuhanicoz"
    },
    "capabilities": {
      "foo": "bar"
    },
    "loginID": "discordgo",
    "network": "Discord",
    "statusText": "statusText"
  },
  {
    "accountID": "local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
    "bridge": {
      "id": "local-whatsapp",
      "provider": "local",
      "type": "whatsapp"
    },
    "status": "connected",
    "user": {
      "id": "ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
      "cannotMessage": true,
      "email": "email",
      "fullName": "Batuhan İçöz",
      "imgURL": "file:///Users/batuhan/Library/Application%20Support/BeeperTexts/media/localhostlocal-whatsapp/_gkBAAAAB1xsnfQKMTcwOTkzODU5MAkBAAAAB1xsnfQ",
      "isSelf": true,
      "phoneNumber": "+15550101001",
      "username": "username"
    },
    "capabilities": {
      "foo": "bar"
    },
    "loginID": "ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
    "network": "WhatsApp",
    "statusText": "statusText"
  }
]