# Bridges ## List available bridges `bridges.list() -> BridgeListResponse` **get** `/v1/bridges` List available bridges. A bridge is a chat-network connector that can connect or reconnect chat accounts. Connected accounts use the same Account schema as GET /v1/accounts. ### Returns - `class BridgeListResponse: …` Available bridges and their connected accounts. - `items: List[Bridge]` - `id: str` Bridge ID. Use with bridge endpoints. - `accounts: List[Account]` Connected accounts for this bridge. Uses the same Account schema as GET /v1/accounts. - `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+. - `"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. - `"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. - `active_account_count: int` Number of active accounts for this network on this device. - `display_name: str` Human-friendly bridge name shown in Beeper. - `provider: Literal["cloud", "self-hosted", "local", "platform-sdk"]` Where accounts for this bridge run: on this device or in Beeper Cloud. - `"cloud"` - `"self-hosted"` - `"local"` - `"platform-sdk"` - `status: Literal["available", "connected", "limit_reached", 2 more]` Whether this bridge can currently be used to connect new accounts. - `"available"` - `"connected"` - `"limit_reached"` - `"temporarily_unavailable"` - `"disabled"` - `supports_multiple_accounts: bool` Whether this bridge can have multiple active accounts for the same network. - `type: str` Underlying bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. - `network: Optional[str]` Network grouping used for account counts and limits. - `status_text: Optional[str]` Human-friendly status text matching Beeper account management language. ### Example ```python 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 ) bridges = client.bridges.list() print(bridges.items) ``` #### Response ```json { "items": [ { "id": "id", "accounts": [ { "accountID": "accountID", "bridge": { "id": "id", "provider": "cloud", "type": "type" }, "status": "connected", "user": { "id": "id", "cannotMessage": true, "email": "email", "fullName": "fullName", "imgURL": "imgURL", "isSelf": true, "phoneNumber": "phoneNumber", "username": "username" }, "capabilities": { "foo": "bar" }, "loginID": "loginID", "network": "network", "statusText": "statusText" } ], "activeAccountCount": 0, "displayName": "displayName", "provider": "cloud", "status": "available", "supportsMultipleAccounts": true, "type": "type", "network": "network", "statusText": "statusText" } ] } ``` ## Get bridge `bridges.retrieve(strbridge_id) -> BridgeRetrieveResponse` **get** `/v1/bridges/{bridgeID}` Get one bridge, including the chat accounts connected through it. ### Parameters - `bridge_id: str` Bridge ID. ### Returns - `class BridgeRetrieveResponse: …` Available bridge that can connect or reconnect chat accounts. - `id: str` Bridge ID. Use with bridge endpoints. - `accounts: List[Account]` Connected accounts for this bridge. Uses the same Account schema as GET /v1/accounts. - `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+. - `"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. - `"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. - `active_account_count: int` Number of active accounts for this network on this device. - `display_name: str` Human-friendly bridge name shown in Beeper. - `provider: Literal["cloud", "self-hosted", "local", "platform-sdk"]` Where accounts for this bridge run: on this device or in Beeper Cloud. - `"cloud"` - `"self-hosted"` - `"local"` - `"platform-sdk"` - `status: Literal["available", "connected", "limit_reached", 2 more]` Whether this bridge can currently be used to connect new accounts. - `"available"` - `"connected"` - `"limit_reached"` - `"temporarily_unavailable"` - `"disabled"` - `supports_multiple_accounts: bool` Whether this bridge can have multiple active accounts for the same network. - `type: str` Underlying bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. - `network: Optional[str]` Network grouping used for account counts and limits. - `status_text: Optional[str]` Human-friendly status text matching Beeper account management language. ### Example ```python 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 ) bridge = client.bridges.retrieve( "local-whatsapp", ) print(bridge.id) ``` #### Response ```json { "id": "id", "accounts": [ { "accountID": "accountID", "bridge": { "id": "id", "provider": "cloud", "type": "type" }, "status": "connected", "user": { "id": "id", "cannotMessage": true, "email": "email", "fullName": "fullName", "imgURL": "imgURL", "isSelf": true, "phoneNumber": "phoneNumber", "username": "username" }, "capabilities": { "foo": "bar" }, "loginID": "loginID", "network": "network", "statusText": "statusText" } ], "activeAccountCount": 0, "displayName": "displayName", "provider": "cloud", "status": "available", "supportsMultipleAccounts": true, "type": "type", "network": "network", "statusText": "statusText" } ``` ## Get bridge capabilities `bridges.retrieve_capabilities(strbridge_id) -> ProvisioningCapabilities` **get** `/v1/bridges/{bridgeID}/capabilities` Get advanced network capabilities for a bridge. This endpoint is intended for clients that build custom connect or chat-creation flows. ### Parameters - `bridge_id: str` Bridge ID. ### Returns - `class ProvisioningCapabilities: …` Advanced network capabilities for account lookup and group creation. - `group_creation: Dict[str, GroupTypeCapabilities]` - `type_description: str` - `avatar: Optional[GroupFieldCapability]` Group creation field capability. - `allowed: bool` - `max_length: Optional[int]` - `min_length: Optional[int]` - `required: Optional[bool]` - `settings: Optional[DisappearingTimerCapability]` Disappearing-message timer capability. - `types: List[Literal["", "after_read", "after_send"]]` - `""` - `"after_read"` - `"after_send"` - `omit_empty_timer: Optional[Literal[true]]` - `true` - `timers: Optional[List[int]]` - `disappear: Optional[GroupFieldCapability]` Group creation field capability. - `name: Optional[GroupFieldCapability]` Group creation field capability. - `parent: Optional[GroupFieldCapability]` Group creation field capability. - `participants: Optional[GroupFieldCapability]` Group creation field capability. - `topic: Optional[GroupFieldCapability]` Group creation field capability. - `username: Optional[GroupFieldCapability]` Group creation field capability. - `resolve_identifier: ResolveIdentifierCapabilities` Identifier lookup capabilities for this bridge. - `any_phone: bool` - `contact_list: bool` - `create_dm: bool` - `lookup_email: bool` - `lookup_phone: bool` - `lookup_username: bool` - `search: bool` - `image_pack_import: Optional[bool]` ### Example ```python 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 ) provisioning_capabilities = client.bridges.retrieve_capabilities( "local-whatsapp", ) print(provisioning_capabilities.resolve_identifier) ``` #### Response ```json { "group_creation": { "foo": { "type_description": "type_description", "avatar": { "allowed": true, "max_length": 0, "min_length": 0, "required": true, "settings": { "types": [ "" ], "omit_empty_timer": true, "timers": [ 0 ] } }, "disappear": { "allowed": true, "max_length": 0, "min_length": 0, "required": true, "settings": { "types": [ "" ], "omit_empty_timer": true, "timers": [ 0 ] } }, "name": { "allowed": true, "max_length": 0, "min_length": 0, "required": true, "settings": { "types": [ "" ], "omit_empty_timer": true, "timers": [ 0 ] } }, "parent": { "allowed": true, "max_length": 0, "min_length": 0, "required": true, "settings": { "types": [ "" ], "omit_empty_timer": true, "timers": [ 0 ] } }, "participants": { "allowed": true, "max_length": 0, "min_length": 0, "required": true, "settings": { "types": [ "" ], "omit_empty_timer": true, "timers": [ 0 ] } }, "topic": { "allowed": true, "max_length": 0, "min_length": 0, "required": true, "settings": { "types": [ "" ], "omit_empty_timer": true, "timers": [ 0 ] } }, "username": { "allowed": true, "max_length": 0, "min_length": 0, "required": true, "settings": { "types": [ "" ], "omit_empty_timer": true, "timers": [ 0 ] } } } }, "resolve_identifier": { "any_phone": true, "contact_list": true, "create_dm": true, "lookup_email": true, "lookup_phone": true, "lookup_username": true, "search": true }, "image_pack_import": true } ``` ## Domain Types ### Bridge - `class Bridge: …` Available bridge that can connect or reconnect chat accounts. - `id: str` Bridge ID. Use with bridge endpoints. - `accounts: List[Account]` Connected accounts for this bridge. Uses the same Account schema as GET /v1/accounts. - `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+. - `"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. - `"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. - `active_account_count: int` Number of active accounts for this network on this device. - `display_name: str` Human-friendly bridge name shown in Beeper. - `provider: Literal["cloud", "self-hosted", "local", "platform-sdk"]` Where accounts for this bridge run: on this device or in Beeper Cloud. - `"cloud"` - `"self-hosted"` - `"local"` - `"platform-sdk"` - `status: Literal["available", "connected", "limit_reached", 2 more]` Whether this bridge can currently be used to connect new accounts. - `"available"` - `"connected"` - `"limit_reached"` - `"temporarily_unavailable"` - `"disabled"` - `supports_multiple_accounts: bool` Whether this bridge can have multiple active accounts for the same network. - `type: str` Underlying bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. - `network: Optional[str]` Network grouping used for account counts and limits. - `status_text: Optional[str]` Human-friendly status text matching Beeper account management language. ### Cookie Field - `class CookieField: …` - `id: str` Field ID to send back in the fields object. - `name: Optional[str]` Cookie, header, or local storage key to collect. - `type: Optional[Literal["cookie", "header", "local_storage"]]` Browser storage source for this value. - `"cookie"` - `"header"` - `"local_storage"` ### Disappearing Timer Capability - `class DisappearingTimerCapability: …` Disappearing-message timer capability. - `types: List[Literal["", "after_read", "after_send"]]` - `""` - `"after_read"` - `"after_send"` - `omit_empty_timer: Optional[Literal[true]]` - `true` - `timers: Optional[List[int]]` ### Group Field Capability - `class GroupFieldCapability: …` Group creation field capability. - `allowed: bool` - `max_length: Optional[int]` - `min_length: Optional[int]` - `required: Optional[bool]` - `settings: Optional[DisappearingTimerCapability]` Disappearing-message timer capability. - `types: List[Literal["", "after_read", "after_send"]]` - `""` - `"after_read"` - `"after_send"` - `omit_empty_timer: Optional[Literal[true]]` - `true` - `timers: Optional[List[int]]` ### Group Type Capabilities - `class GroupTypeCapabilities: …` Group creation capabilities for one group type. - `type_description: str` - `avatar: Optional[GroupFieldCapability]` Group creation field capability. - `allowed: bool` - `max_length: Optional[int]` - `min_length: Optional[int]` - `required: Optional[bool]` - `settings: Optional[DisappearingTimerCapability]` Disappearing-message timer capability. - `types: List[Literal["", "after_read", "after_send"]]` - `""` - `"after_read"` - `"after_send"` - `omit_empty_timer: Optional[Literal[true]]` - `true` - `timers: Optional[List[int]]` - `disappear: Optional[GroupFieldCapability]` Group creation field capability. - `name: Optional[GroupFieldCapability]` Group creation field capability. - `parent: Optional[GroupFieldCapability]` Group creation field capability. - `participants: Optional[GroupFieldCapability]` Group creation field capability. - `topic: Optional[GroupFieldCapability]` Group creation field capability. - `username: Optional[GroupFieldCapability]` Group creation field capability. ### Login Flow - `class LoginFlow: …` Connect or reconnect flow option for a bridge. - `id: str` Flow ID to pass when creating a bridge login session. - `description: Optional[str]` Short explanation for when to use this flow, when provided. - `name: Optional[str]` Display name for the flow, when provided. ### Login Input Field - `class LoginInputField: …` - `id: str` Field ID to send back in the fields object. - `initial_value: Optional[str]` Initial field value, when provided by the network. - `label: Optional[str]` Field label to show to the user. - `optional: Optional[bool]` True if the user can leave this field empty. - `placeholder: Optional[str]` Placeholder text to show when the field is empty. - `type: Optional[str]` Suggested input type, such as text, password, or email. ### Login Session - `class LoginSession: …` - `bridge_id: str` Bridge ID. - `login_session_id: str` Temporary bridge login session ID. - `status: Literal["waiting_for_input", "waiting_for_cookies", "waiting_for_display", 3 more]` - `"waiting_for_input"` - `"waiting_for_cookies"` - `"waiting_for_display"` - `"complete"` - `"cancelled"` - `"failed"` - `account: Optional[Account]` A chat account added to Beeper. - `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+. - `"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. - `"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. - `account_id: Optional[str]` Chat account ID for reconnect flows, when known. - `current_step: Optional[CurrentStep]` Step the client should show or complete next. Omitted when the session is complete, cancelled, or failed. - `class CurrentStepUserInput: …` - `fields: List[LoginInputField]` - `id: str` Field ID to send back in the fields object. - `initial_value: Optional[str]` Initial field value, when provided by the network. - `label: Optional[str]` Field label to show to the user. - `optional: Optional[bool]` True if the user can leave this field empty. - `placeholder: Optional[str]` Placeholder text to show when the field is empty. - `type: Optional[str]` Suggested input type, such as text, password, or email. - `step_id: str` - `type: Literal["user_input"]` - `"user_input"` - `attachments: Optional[List[Optional[object]]]` - `instructions: Optional[str]` User-facing instructions for this step. - `class CurrentStepCookies: …` - `fields: List[CookieField]` - `id: str` Field ID to send back in the fields object. - `name: Optional[str]` Cookie, header, or local storage key to collect. - `type: Optional[Literal["cookie", "header", "local_storage"]]` Browser storage source for this value. - `"cookie"` - `"header"` - `"local_storage"` - `step_id: str` - `type: Literal["cookies"]` - `"cookies"` - `url: str` URL to open for the user. - `expected_final_url_regex: Optional[str]` Regular expression that identifies the final URL after sign-in. - `extract_js: Optional[str]` Optional extraction script for browser-based sign-in helpers. Treat as an opaque helper value. - `instructions: Optional[str]` User-facing instructions for this browser step. - `user_agent: Optional[str]` Suggested user agent for the browser session. - `class CurrentStepDisplayAndWait: …` - `display: CurrentStepDisplayAndWaitDisplay` - `class CurrentStepDisplayAndWaitDisplayQrCode: …` - `data: str` - `type: Literal["qr"]` - `"qr"` - `class CurrentStepDisplayAndWaitDisplayEmoji: …` - `image_url: str` - `type: Literal["emoji"]` - `"emoji"` - `class CurrentStepDisplayAndWaitDisplayEmpty: …` - `type: Literal["nothing"]` - `"nothing"` - `step_id: str` - `type: Literal["display_and_wait"]` - `"display_and_wait"` - `instructions: Optional[str]` User-facing instructions for this step. - `class CurrentStepComplete: …` - `type: Literal["complete"]` - `"complete"` - `account: Optional[Account]` A chat account added to Beeper. - `instructions: Optional[str]` Completion instructions, when provided. - `login: Optional[CurrentStepCompleteLogin]` Signed-in identity for a bridge. One bridge login can contain multiple chat accounts. - `bridge_id: str` Bridge ID. - `login_id: str` Bridge login ID. - `remove_scopes: List[Literal["current-device", "all-devices"]]` - `"current-device"` - `"all-devices"` - `status: Literal["connected", "connecting", "needs_login", 2 more]` - `"connected"` - `"connecting"` - `"needs_login"` - `"logged_out"` - `"unknown"` - `account_ids: Optional[List[str]]` Chat accounts that belong to this bridge login, when known. - `status_text: Optional[str]` Human-friendly bridge login status text. - `user: Optional[User]` User the account belongs to. - `step_id: Optional[str]` - `error: Optional[APIError]` - `code: str` - `message: str` - `details: Optional[Dict[str, Optional[object]]]` - `login: Optional[Login]` Signed-in identity for a bridge. One bridge login can contain multiple chat accounts. - `bridge_id: str` Bridge ID. - `login_id: str` Bridge login ID. - `remove_scopes: List[Literal["current-device", "all-devices"]]` - `"current-device"` - `"all-devices"` - `status: Literal["connected", "connecting", "needs_login", 2 more]` - `"connected"` - `"connecting"` - `"needs_login"` - `"logged_out"` - `"unknown"` - `account_ids: Optional[List[str]]` Chat accounts that belong to this bridge login, when known. - `status_text: Optional[str]` Human-friendly bridge login status text. - `user: Optional[User]` User the account belongs to. - `login_id: Optional[str]` Bridge login ID for reconnect flows, when known. ### Provisioning Capabilities - `class ProvisioningCapabilities: …` Advanced network capabilities for account lookup and group creation. - `group_creation: Dict[str, GroupTypeCapabilities]` - `type_description: str` - `avatar: Optional[GroupFieldCapability]` Group creation field capability. - `allowed: bool` - `max_length: Optional[int]` - `min_length: Optional[int]` - `required: Optional[bool]` - `settings: Optional[DisappearingTimerCapability]` Disappearing-message timer capability. - `types: List[Literal["", "after_read", "after_send"]]` - `""` - `"after_read"` - `"after_send"` - `omit_empty_timer: Optional[Literal[true]]` - `true` - `timers: Optional[List[int]]` - `disappear: Optional[GroupFieldCapability]` Group creation field capability. - `name: Optional[GroupFieldCapability]` Group creation field capability. - `parent: Optional[GroupFieldCapability]` Group creation field capability. - `participants: Optional[GroupFieldCapability]` Group creation field capability. - `topic: Optional[GroupFieldCapability]` Group creation field capability. - `username: Optional[GroupFieldCapability]` Group creation field capability. - `resolve_identifier: ResolveIdentifierCapabilities` Identifier lookup capabilities for this bridge. - `any_phone: bool` - `contact_list: bool` - `create_dm: bool` - `lookup_email: bool` - `lookup_phone: bool` - `lookup_username: bool` - `search: bool` - `image_pack_import: Optional[bool]` ### Resolve Identifier Capabilities - `class ResolveIdentifierCapabilities: …` Identifier lookup capabilities for this bridge. - `any_phone: bool` - `contact_list: bool` - `create_dm: bool` - `lookup_email: bool` - `lookup_phone: bool` - `lookup_username: bool` - `search: bool` ### Bridge List Response - `class BridgeListResponse: …` Available bridges and their connected accounts. - `items: List[Bridge]` - `id: str` Bridge ID. Use with bridge endpoints. - `accounts: List[Account]` Connected accounts for this bridge. Uses the same Account schema as GET /v1/accounts. - `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+. - `"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. - `"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. - `active_account_count: int` Number of active accounts for this network on this device. - `display_name: str` Human-friendly bridge name shown in Beeper. - `provider: Literal["cloud", "self-hosted", "local", "platform-sdk"]` Where accounts for this bridge run: on this device or in Beeper Cloud. - `"cloud"` - `"self-hosted"` - `"local"` - `"platform-sdk"` - `status: Literal["available", "connected", "limit_reached", 2 more]` Whether this bridge can currently be used to connect new accounts. - `"available"` - `"connected"` - `"limit_reached"` - `"temporarily_unavailable"` - `"disabled"` - `supports_multiple_accounts: bool` Whether this bridge can have multiple active accounts for the same network. - `type: str` Underlying bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. - `network: Optional[str]` Network grouping used for account counts and limits. - `status_text: Optional[str]` Human-friendly status text matching Beeper account management language. ### Bridge Retrieve Response - `class BridgeRetrieveResponse: …` Available bridge that can connect or reconnect chat accounts. - `id: str` Bridge ID. Use with bridge endpoints. - `accounts: List[Account]` Connected accounts for this bridge. Uses the same Account schema as GET /v1/accounts. - `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+. - `"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. - `"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. - `active_account_count: int` Number of active accounts for this network on this device. - `display_name: str` Human-friendly bridge name shown in Beeper. - `provider: Literal["cloud", "self-hosted", "local", "platform-sdk"]` Where accounts for this bridge run: on this device or in Beeper Cloud. - `"cloud"` - `"self-hosted"` - `"local"` - `"platform-sdk"` - `status: Literal["available", "connected", "limit_reached", 2 more]` Whether this bridge can currently be used to connect new accounts. - `"available"` - `"connected"` - `"limit_reached"` - `"temporarily_unavailable"` - `"disabled"` - `supports_multiple_accounts: bool` Whether this bridge can have multiple active accounts for the same network. - `type: str` Underlying bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. - `network: Optional[str]` Network grouping used for account counts and limits. - `status_text: Optional[str]` Human-friendly status text matching Beeper account management language. # Login Flows ## List login flows `bridges.login_flows.list(strbridge_id) -> LoginFlowListResponse` **get** `/v1/bridges/{bridgeID}/login-flows` List connect and reconnect flow options for a bridge. Use a flowID when creating a bridge login session. ### Parameters - `bridge_id: str` Bridge ID. ### Returns - `class LoginFlowListResponse: …` - `items: List[LoginFlow]` - `id: str` Flow ID to pass when creating a bridge login session. - `description: Optional[str]` Short explanation for when to use this flow, when provided. - `name: Optional[str]` Display name for the flow, when provided. ### Example ```python 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 ) login_flows = client.bridges.login_flows.list( "local-whatsapp", ) print(login_flows.items) ``` #### Response ```json { "items": [ { "id": "id", "description": "description", "name": "name" } ] } ``` ## Domain Types ### Login Flow List Response - `class LoginFlowListResponse: …` - `items: List[LoginFlow]` - `id: str` Flow ID to pass when creating a bridge login session. - `description: Optional[str]` Short explanation for when to use this flow, when provided. - `name: Optional[str]` Display name for the flow, when provided. # Connections # Login Sessions ## Create bridge login session `bridges.login_sessions.create(strbridge_id, LoginSessionCreateParams**kwargs) -> LoginSession` **post** `/v1/bridges/{bridgeID}/login-sessions` Start a temporary bridge login session to connect a new chat account or reconnect an existing bridge login. Omit loginID and accountID to connect a new account. ### Parameters - `bridge_id: str` Bridge ID. - `account_id: Optional[str]` Existing chat account ID to reconnect. Omit to connect a new account. - `flow_id: Optional[str]` Optional flow ID returned by the list login flows endpoint. If omitted, Beeper chooses the default flow. - `login_id: Optional[str]` Existing bridge login ID to reconnect. Omit to connect a new account. ### Returns - `class LoginSession: …` - `bridge_id: str` Bridge ID. - `login_session_id: str` Temporary bridge login session ID. - `status: Literal["waiting_for_input", "waiting_for_cookies", "waiting_for_display", 3 more]` - `"waiting_for_input"` - `"waiting_for_cookies"` - `"waiting_for_display"` - `"complete"` - `"cancelled"` - `"failed"` - `account: Optional[Account]` A chat account added to Beeper. - `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+. - `"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. - `"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. - `account_id: Optional[str]` Chat account ID for reconnect flows, when known. - `current_step: Optional[CurrentStep]` Step the client should show or complete next. Omitted when the session is complete, cancelled, or failed. - `class CurrentStepUserInput: …` - `fields: List[LoginInputField]` - `id: str` Field ID to send back in the fields object. - `initial_value: Optional[str]` Initial field value, when provided by the network. - `label: Optional[str]` Field label to show to the user. - `optional: Optional[bool]` True if the user can leave this field empty. - `placeholder: Optional[str]` Placeholder text to show when the field is empty. - `type: Optional[str]` Suggested input type, such as text, password, or email. - `step_id: str` - `type: Literal["user_input"]` - `"user_input"` - `attachments: Optional[List[Optional[object]]]` - `instructions: Optional[str]` User-facing instructions for this step. - `class CurrentStepCookies: …` - `fields: List[CookieField]` - `id: str` Field ID to send back in the fields object. - `name: Optional[str]` Cookie, header, or local storage key to collect. - `type: Optional[Literal["cookie", "header", "local_storage"]]` Browser storage source for this value. - `"cookie"` - `"header"` - `"local_storage"` - `step_id: str` - `type: Literal["cookies"]` - `"cookies"` - `url: str` URL to open for the user. - `expected_final_url_regex: Optional[str]` Regular expression that identifies the final URL after sign-in. - `extract_js: Optional[str]` Optional extraction script for browser-based sign-in helpers. Treat as an opaque helper value. - `instructions: Optional[str]` User-facing instructions for this browser step. - `user_agent: Optional[str]` Suggested user agent for the browser session. - `class CurrentStepDisplayAndWait: …` - `display: CurrentStepDisplayAndWaitDisplay` - `class CurrentStepDisplayAndWaitDisplayQrCode: …` - `data: str` - `type: Literal["qr"]` - `"qr"` - `class CurrentStepDisplayAndWaitDisplayEmoji: …` - `image_url: str` - `type: Literal["emoji"]` - `"emoji"` - `class CurrentStepDisplayAndWaitDisplayEmpty: …` - `type: Literal["nothing"]` - `"nothing"` - `step_id: str` - `type: Literal["display_and_wait"]` - `"display_and_wait"` - `instructions: Optional[str]` User-facing instructions for this step. - `class CurrentStepComplete: …` - `type: Literal["complete"]` - `"complete"` - `account: Optional[Account]` A chat account added to Beeper. - `instructions: Optional[str]` Completion instructions, when provided. - `login: Optional[CurrentStepCompleteLogin]` Signed-in identity for a bridge. One bridge login can contain multiple chat accounts. - `bridge_id: str` Bridge ID. - `login_id: str` Bridge login ID. - `remove_scopes: List[Literal["current-device", "all-devices"]]` - `"current-device"` - `"all-devices"` - `status: Literal["connected", "connecting", "needs_login", 2 more]` - `"connected"` - `"connecting"` - `"needs_login"` - `"logged_out"` - `"unknown"` - `account_ids: Optional[List[str]]` Chat accounts that belong to this bridge login, when known. - `status_text: Optional[str]` Human-friendly bridge login status text. - `user: Optional[User]` User the account belongs to. - `step_id: Optional[str]` - `error: Optional[APIError]` - `code: str` - `message: str` - `details: Optional[Dict[str, Optional[object]]]` - `login: Optional[Login]` Signed-in identity for a bridge. One bridge login can contain multiple chat accounts. - `bridge_id: str` Bridge ID. - `login_id: str` Bridge login ID. - `remove_scopes: List[Literal["current-device", "all-devices"]]` - `"current-device"` - `"all-devices"` - `status: Literal["connected", "connecting", "needs_login", 2 more]` - `"connected"` - `"connecting"` - `"needs_login"` - `"logged_out"` - `"unknown"` - `account_ids: Optional[List[str]]` Chat accounts that belong to this bridge login, when known. - `status_text: Optional[str]` Human-friendly bridge login status text. - `user: Optional[User]` User the account belongs to. - `login_id: Optional[str]` Bridge login ID for reconnect flows, when known. ### Example ```python 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 ) login_session = client.bridges.login_sessions.create( bridge_id="local-whatsapp", ) print(login_session.bridge_id) ``` #### Response ```json { "bridgeID": "bridgeID", "loginSessionID": "loginSessionID", "status": "waiting_for_input", "account": { "accountID": "accountID", "bridge": { "id": "id", "provider": "cloud", "type": "type" }, "status": "connected", "user": { "id": "id", "cannotMessage": true, "email": "email", "fullName": "fullName", "imgURL": "imgURL", "isSelf": true, "phoneNumber": "phoneNumber", "username": "username" }, "capabilities": { "foo": "bar" }, "loginID": "loginID", "network": "network", "statusText": "statusText" }, "accountID": "accountID", "currentStep": { "fields": [ { "id": "id", "initialValue": "initialValue", "label": "label", "optional": true, "placeholder": "placeholder", "type": "type" } ], "stepID": "stepID", "type": "user_input", "attachments": [ {} ], "instructions": "instructions" }, "error": { "code": "code", "message": "message", "details": { "foo": "bar" } }, "login": { "bridgeID": "bridgeID", "loginID": "loginID", "removeScopes": [ "current-device" ], "status": "connected", "accountIDs": [ "string" ], "statusText": "statusText", "user": { "id": "id", "cannotMessage": true, "email": "email", "fullName": "fullName", "imgURL": "imgURL", "isSelf": true, "phoneNumber": "phoneNumber", "username": "username" } }, "loginID": "loginID" } ``` ## Get bridge login session `bridges.login_sessions.retrieve(strlogin_session_id, LoginSessionRetrieveParams**kwargs) -> LoginSession` **get** `/v1/bridges/{bridgeID}/login-sessions/{loginSessionID}` Get the current state of a temporary bridge login session. ### Parameters - `bridge_id: str` Bridge ID. - `login_session_id: str` Temporary bridge login session ID. ### Returns - `class LoginSession: …` - `bridge_id: str` Bridge ID. - `login_session_id: str` Temporary bridge login session ID. - `status: Literal["waiting_for_input", "waiting_for_cookies", "waiting_for_display", 3 more]` - `"waiting_for_input"` - `"waiting_for_cookies"` - `"waiting_for_display"` - `"complete"` - `"cancelled"` - `"failed"` - `account: Optional[Account]` A chat account added to Beeper. - `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+. - `"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. - `"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. - `account_id: Optional[str]` Chat account ID for reconnect flows, when known. - `current_step: Optional[CurrentStep]` Step the client should show or complete next. Omitted when the session is complete, cancelled, or failed. - `class CurrentStepUserInput: …` - `fields: List[LoginInputField]` - `id: str` Field ID to send back in the fields object. - `initial_value: Optional[str]` Initial field value, when provided by the network. - `label: Optional[str]` Field label to show to the user. - `optional: Optional[bool]` True if the user can leave this field empty. - `placeholder: Optional[str]` Placeholder text to show when the field is empty. - `type: Optional[str]` Suggested input type, such as text, password, or email. - `step_id: str` - `type: Literal["user_input"]` - `"user_input"` - `attachments: Optional[List[Optional[object]]]` - `instructions: Optional[str]` User-facing instructions for this step. - `class CurrentStepCookies: …` - `fields: List[CookieField]` - `id: str` Field ID to send back in the fields object. - `name: Optional[str]` Cookie, header, or local storage key to collect. - `type: Optional[Literal["cookie", "header", "local_storage"]]` Browser storage source for this value. - `"cookie"` - `"header"` - `"local_storage"` - `step_id: str` - `type: Literal["cookies"]` - `"cookies"` - `url: str` URL to open for the user. - `expected_final_url_regex: Optional[str]` Regular expression that identifies the final URL after sign-in. - `extract_js: Optional[str]` Optional extraction script for browser-based sign-in helpers. Treat as an opaque helper value. - `instructions: Optional[str]` User-facing instructions for this browser step. - `user_agent: Optional[str]` Suggested user agent for the browser session. - `class CurrentStepDisplayAndWait: …` - `display: CurrentStepDisplayAndWaitDisplay` - `class CurrentStepDisplayAndWaitDisplayQrCode: …` - `data: str` - `type: Literal["qr"]` - `"qr"` - `class CurrentStepDisplayAndWaitDisplayEmoji: …` - `image_url: str` - `type: Literal["emoji"]` - `"emoji"` - `class CurrentStepDisplayAndWaitDisplayEmpty: …` - `type: Literal["nothing"]` - `"nothing"` - `step_id: str` - `type: Literal["display_and_wait"]` - `"display_and_wait"` - `instructions: Optional[str]` User-facing instructions for this step. - `class CurrentStepComplete: …` - `type: Literal["complete"]` - `"complete"` - `account: Optional[Account]` A chat account added to Beeper. - `instructions: Optional[str]` Completion instructions, when provided. - `login: Optional[CurrentStepCompleteLogin]` Signed-in identity for a bridge. One bridge login can contain multiple chat accounts. - `bridge_id: str` Bridge ID. - `login_id: str` Bridge login ID. - `remove_scopes: List[Literal["current-device", "all-devices"]]` - `"current-device"` - `"all-devices"` - `status: Literal["connected", "connecting", "needs_login", 2 more]` - `"connected"` - `"connecting"` - `"needs_login"` - `"logged_out"` - `"unknown"` - `account_ids: Optional[List[str]]` Chat accounts that belong to this bridge login, when known. - `status_text: Optional[str]` Human-friendly bridge login status text. - `user: Optional[User]` User the account belongs to. - `step_id: Optional[str]` - `error: Optional[APIError]` - `code: str` - `message: str` - `details: Optional[Dict[str, Optional[object]]]` - `login: Optional[Login]` Signed-in identity for a bridge. One bridge login can contain multiple chat accounts. - `bridge_id: str` Bridge ID. - `login_id: str` Bridge login ID. - `remove_scopes: List[Literal["current-device", "all-devices"]]` - `"current-device"` - `"all-devices"` - `status: Literal["connected", "connecting", "needs_login", 2 more]` - `"connected"` - `"connecting"` - `"needs_login"` - `"logged_out"` - `"unknown"` - `account_ids: Optional[List[str]]` Chat accounts that belong to this bridge login, when known. - `status_text: Optional[str]` Human-friendly bridge login status text. - `user: Optional[User]` User the account belongs to. - `login_id: Optional[str]` Bridge login ID for reconnect flows, when known. ### Example ```python 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 ) login_session = client.bridges.login_sessions.retrieve( login_session_id="123", bridge_id="local-whatsapp", ) print(login_session.bridge_id) ``` #### Response ```json { "bridgeID": "bridgeID", "loginSessionID": "loginSessionID", "status": "waiting_for_input", "account": { "accountID": "accountID", "bridge": { "id": "id", "provider": "cloud", "type": "type" }, "status": "connected", "user": { "id": "id", "cannotMessage": true, "email": "email", "fullName": "fullName", "imgURL": "imgURL", "isSelf": true, "phoneNumber": "phoneNumber", "username": "username" }, "capabilities": { "foo": "bar" }, "loginID": "loginID", "network": "network", "statusText": "statusText" }, "accountID": "accountID", "currentStep": { "fields": [ { "id": "id", "initialValue": "initialValue", "label": "label", "optional": true, "placeholder": "placeholder", "type": "type" } ], "stepID": "stepID", "type": "user_input", "attachments": [ {} ], "instructions": "instructions" }, "error": { "code": "code", "message": "message", "details": { "foo": "bar" } }, "login": { "bridgeID": "bridgeID", "loginID": "loginID", "removeScopes": [ "current-device" ], "status": "connected", "accountIDs": [ "string" ], "statusText": "statusText", "user": { "id": "id", "cannotMessage": true, "email": "email", "fullName": "fullName", "imgURL": "imgURL", "isSelf": true, "phoneNumber": "phoneNumber", "username": "username" } }, "loginID": "loginID" } ``` ## Cancel bridge login session `bridges.login_sessions.cancel(strlogin_session_id, LoginSessionCancelParams**kwargs) -> LoginSessionCancelResponse` **delete** `/v1/bridges/{bridgeID}/login-sessions/{loginSessionID}` Cancel a temporary bridge login session. ### Parameters - `bridge_id: str` Bridge ID. - `login_session_id: str` Temporary bridge login session ID. ### Returns - `class LoginSessionCancelResponse: …` - `bridge_id: str` - `login_session_id: str` - `status: Literal["cancelled"]` - `"cancelled"` ### Example ```python 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 ) response = client.bridges.login_sessions.cancel( login_session_id="123", bridge_id="local-whatsapp", ) print(response.bridge_id) ``` #### Response ```json { "bridgeID": "bridgeID", "loginSessionID": "loginSessionID", "status": "cancelled" } ``` ## Domain Types ### Login Session Cancel Response - `class LoginSessionCancelResponse: …` - `bridge_id: str` - `login_session_id: str` - `status: Literal["cancelled"]` - `"cancelled"` # Steps ## Submit login step `bridges.login_sessions.steps.submit(strstep_id, StepSubmitParams**kwargs) -> LoginSession` **post** `/v1/bridges/{bridgeID}/login-sessions/{loginSessionID}/steps/{stepID}` Submit input for the current step of a bridge login session. ### Parameters - `bridge_id: str` Bridge ID. - `login_session_id: str` Temporary bridge login session ID. - `step_id: str` Current bridge login session step ID. - `type: Literal["user_input", "cookies", "display_and_wait"]` - `"user_input"` - `"cookies"` - `"display_and_wait"` - `fields: Optional[Dict[str, str]]` Field values keyed by the field IDs from the current step. - `last_url: Optional[str]` Last browser URL reached during a cookies step, if available. - `source: Optional[Literal["api", "webview", "browser_extension"]]` How the step was completed. Omit unless the client needs to distinguish an embedded webview or browser extension. - `"api"` - `"webview"` - `"browser_extension"` ### Returns - `class LoginSession: …` - `bridge_id: str` Bridge ID. - `login_session_id: str` Temporary bridge login session ID. - `status: Literal["waiting_for_input", "waiting_for_cookies", "waiting_for_display", 3 more]` - `"waiting_for_input"` - `"waiting_for_cookies"` - `"waiting_for_display"` - `"complete"` - `"cancelled"` - `"failed"` - `account: Optional[Account]` A chat account added to Beeper. - `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+. - `"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. - `"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. - `account_id: Optional[str]` Chat account ID for reconnect flows, when known. - `current_step: Optional[CurrentStep]` Step the client should show or complete next. Omitted when the session is complete, cancelled, or failed. - `class CurrentStepUserInput: …` - `fields: List[LoginInputField]` - `id: str` Field ID to send back in the fields object. - `initial_value: Optional[str]` Initial field value, when provided by the network. - `label: Optional[str]` Field label to show to the user. - `optional: Optional[bool]` True if the user can leave this field empty. - `placeholder: Optional[str]` Placeholder text to show when the field is empty. - `type: Optional[str]` Suggested input type, such as text, password, or email. - `step_id: str` - `type: Literal["user_input"]` - `"user_input"` - `attachments: Optional[List[Optional[object]]]` - `instructions: Optional[str]` User-facing instructions for this step. - `class CurrentStepCookies: …` - `fields: List[CookieField]` - `id: str` Field ID to send back in the fields object. - `name: Optional[str]` Cookie, header, or local storage key to collect. - `type: Optional[Literal["cookie", "header", "local_storage"]]` Browser storage source for this value. - `"cookie"` - `"header"` - `"local_storage"` - `step_id: str` - `type: Literal["cookies"]` - `"cookies"` - `url: str` URL to open for the user. - `expected_final_url_regex: Optional[str]` Regular expression that identifies the final URL after sign-in. - `extract_js: Optional[str]` Optional extraction script for browser-based sign-in helpers. Treat as an opaque helper value. - `instructions: Optional[str]` User-facing instructions for this browser step. - `user_agent: Optional[str]` Suggested user agent for the browser session. - `class CurrentStepDisplayAndWait: …` - `display: CurrentStepDisplayAndWaitDisplay` - `class CurrentStepDisplayAndWaitDisplayQrCode: …` - `data: str` - `type: Literal["qr"]` - `"qr"` - `class CurrentStepDisplayAndWaitDisplayEmoji: …` - `image_url: str` - `type: Literal["emoji"]` - `"emoji"` - `class CurrentStepDisplayAndWaitDisplayEmpty: …` - `type: Literal["nothing"]` - `"nothing"` - `step_id: str` - `type: Literal["display_and_wait"]` - `"display_and_wait"` - `instructions: Optional[str]` User-facing instructions for this step. - `class CurrentStepComplete: …` - `type: Literal["complete"]` - `"complete"` - `account: Optional[Account]` A chat account added to Beeper. - `instructions: Optional[str]` Completion instructions, when provided. - `login: Optional[CurrentStepCompleteLogin]` Signed-in identity for a bridge. One bridge login can contain multiple chat accounts. - `bridge_id: str` Bridge ID. - `login_id: str` Bridge login ID. - `remove_scopes: List[Literal["current-device", "all-devices"]]` - `"current-device"` - `"all-devices"` - `status: Literal["connected", "connecting", "needs_login", 2 more]` - `"connected"` - `"connecting"` - `"needs_login"` - `"logged_out"` - `"unknown"` - `account_ids: Optional[List[str]]` Chat accounts that belong to this bridge login, when known. - `status_text: Optional[str]` Human-friendly bridge login status text. - `user: Optional[User]` User the account belongs to. - `step_id: Optional[str]` - `error: Optional[APIError]` - `code: str` - `message: str` - `details: Optional[Dict[str, Optional[object]]]` - `login: Optional[Login]` Signed-in identity for a bridge. One bridge login can contain multiple chat accounts. - `bridge_id: str` Bridge ID. - `login_id: str` Bridge login ID. - `remove_scopes: List[Literal["current-device", "all-devices"]]` - `"current-device"` - `"all-devices"` - `status: Literal["connected", "connecting", "needs_login", 2 more]` - `"connected"` - `"connecting"` - `"needs_login"` - `"logged_out"` - `"unknown"` - `account_ids: Optional[List[str]]` Chat accounts that belong to this bridge login, when known. - `status_text: Optional[str]` Human-friendly bridge login status text. - `user: Optional[User]` User the account belongs to. - `login_id: Optional[str]` Bridge login ID for reconnect flows, when known. ### Example ```python 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 ) login_session = client.bridges.login_sessions.steps.submit( step_id="x", bridge_id="local-whatsapp", login_session_id="123", type="user_input", ) print(login_session.bridge_id) ``` #### Response ```json { "bridgeID": "bridgeID", "loginSessionID": "loginSessionID", "status": "waiting_for_input", "account": { "accountID": "accountID", "bridge": { "id": "id", "provider": "cloud", "type": "type" }, "status": "connected", "user": { "id": "id", "cannotMessage": true, "email": "email", "fullName": "fullName", "imgURL": "imgURL", "isSelf": true, "phoneNumber": "phoneNumber", "username": "username" }, "capabilities": { "foo": "bar" }, "loginID": "loginID", "network": "network", "statusText": "statusText" }, "accountID": "accountID", "currentStep": { "fields": [ { "id": "id", "initialValue": "initialValue", "label": "label", "optional": true, "placeholder": "placeholder", "type": "type" } ], "stepID": "stepID", "type": "user_input", "attachments": [ {} ], "instructions": "instructions" }, "error": { "code": "code", "message": "message", "details": { "foo": "bar" } }, "login": { "bridgeID": "bridgeID", "loginID": "loginID", "removeScopes": [ "current-device" ], "status": "connected", "accountIDs": [ "string" ], "statusText": "statusText", "user": { "id": "id", "cannotMessage": true, "email": "email", "fullName": "fullName", "imgURL": "imgURL", "isSelf": true, "phoneNumber": "phoneNumber", "username": "username" } }, "loginID": "loginID" } ```