# Bridges ## List available bridges **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 - `items: array of Bridge` - `id: string` Bridge ID. Use with bridge endpoints. - `accounts: array of Account` Connected accounts for this bridge. Uses the same Account schema as GET /v1/accounts. - `accountID: string` 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: string` 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: "cloud" or "self-hosted" or "local" or "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: string` Bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. Available in Beeper Desktop v4.2.785+. - `status: "connected" or "connecting" or "backfilling" or 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: string` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannotMessage: optional boolean` 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 string` Email address if known. Not guaranteed verified. - `fullName: optional string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL: optional string` 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. - `isSelf: optional boolean` True if this user represents the authenticated account's own identity. - `phoneNumber: optional string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: optional string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `capabilities: optional map[unknown]` Runtime chat/message capabilities for this connected account, when available. - `loginID: optional string` Bridge login ID for this account, when known. One bridge login can contain multiple chat accounts. - `network: optional string` Human-friendly network name for the account. Omitted when the network is unknown. - `statusText: optional string` Human-friendly account status text. - `activeAccountCount: number` Number of active accounts for this network on this device. - `displayName: string` Human-friendly bridge name shown in Beeper. - `provider: "cloud" or "self-hosted" or "local" or "platform-sdk"` Where accounts for this bridge run: on this device or in Beeper Cloud. - `"cloud"` - `"self-hosted"` - `"local"` - `"platform-sdk"` - `status: "available" or "connected" or "limit_reached" or 2 more` Whether this bridge can currently be used to connect new accounts. - `"available"` - `"connected"` - `"limit_reached"` - `"temporarily_unavailable"` - `"disabled"` - `supportsMultipleAccounts: boolean` Whether this bridge can have multiple active accounts for the same network. - `type: string` Underlying bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. - `network: optional string` Network grouping used for account counts and limits. - `statusText: optional string` Human-friendly status text matching Beeper account management language. ### Example ```http curl http://localhost:23373/v1/bridges \ -H "Authorization: Bearer $BEEPER_ACCESS_TOKEN" ``` #### 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 **get** `/v1/bridges/{bridgeID}` Get one bridge, including the chat accounts connected through it. ### Path Parameters - `bridgeID: string` Bridge ID. ### Returns - `id: string` Bridge ID. Use with bridge endpoints. - `accounts: array of Account` Connected accounts for this bridge. Uses the same Account schema as GET /v1/accounts. - `accountID: string` 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: string` 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: "cloud" or "self-hosted" or "local" or "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: string` Bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. Available in Beeper Desktop v4.2.785+. - `status: "connected" or "connecting" or "backfilling" or 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: string` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannotMessage: optional boolean` 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 string` Email address if known. Not guaranteed verified. - `fullName: optional string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL: optional string` 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. - `isSelf: optional boolean` True if this user represents the authenticated account's own identity. - `phoneNumber: optional string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: optional string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `capabilities: optional map[unknown]` Runtime chat/message capabilities for this connected account, when available. - `loginID: optional string` Bridge login ID for this account, when known. One bridge login can contain multiple chat accounts. - `network: optional string` Human-friendly network name for the account. Omitted when the network is unknown. - `statusText: optional string` Human-friendly account status text. - `activeAccountCount: number` Number of active accounts for this network on this device. - `displayName: string` Human-friendly bridge name shown in Beeper. - `provider: "cloud" or "self-hosted" or "local" or "platform-sdk"` Where accounts for this bridge run: on this device or in Beeper Cloud. - `"cloud"` - `"self-hosted"` - `"local"` - `"platform-sdk"` - `status: "available" or "connected" or "limit_reached" or 2 more` Whether this bridge can currently be used to connect new accounts. - `"available"` - `"connected"` - `"limit_reached"` - `"temporarily_unavailable"` - `"disabled"` - `supportsMultipleAccounts: boolean` Whether this bridge can have multiple active accounts for the same network. - `type: string` Underlying bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. - `network: optional string` Network grouping used for account counts and limits. - `statusText: optional string` Human-friendly status text matching Beeper account management language. ### Example ```http curl http://localhost:23373/v1/bridges/$BRIDGE_ID \ -H "Authorization: Bearer $BEEPER_ACCESS_TOKEN" ``` #### 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 **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. ### Path Parameters - `bridgeID: string` Bridge ID. ### Returns - `ProvisioningCapabilities object { group_creation, resolve_identifier, image_pack_import }` Advanced network capabilities for account lookup and group creation. - `group_creation: map[GroupTypeCapabilities]` - `type_description: string` - `avatar: optional GroupFieldCapability` Group creation field capability. - `allowed: boolean` - `max_length: optional number` - `min_length: optional number` - `required: optional boolean` - `settings: optional DisappearingTimerCapability` Disappearing-message timer capability. - `types: array of "" or "after_read" or "after_send"` - `""` - `"after_read"` - `"after_send"` - `omit_empty_timer: optional true` - `true` - `timers: optional array of number` - `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: boolean` - `contact_list: boolean` - `create_dm: boolean` - `lookup_email: boolean` - `lookup_phone: boolean` - `lookup_username: boolean` - `search: boolean` - `image_pack_import: optional boolean` ### Example ```http curl http://localhost:23373/v1/bridges/$BRIDGE_ID/capabilities \ -H "Authorization: Bearer $BEEPER_ACCESS_TOKEN" ``` #### 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 - `Bridge object { id, accounts, activeAccountCount, 7 more }` Available bridge that can connect or reconnect chat accounts. - `id: string` Bridge ID. Use with bridge endpoints. - `accounts: array of Account` Connected accounts for this bridge. Uses the same Account schema as GET /v1/accounts. - `accountID: string` 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: string` 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: "cloud" or "self-hosted" or "local" or "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: string` Bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. Available in Beeper Desktop v4.2.785+. - `status: "connected" or "connecting" or "backfilling" or 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: string` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannotMessage: optional boolean` 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 string` Email address if known. Not guaranteed verified. - `fullName: optional string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL: optional string` 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. - `isSelf: optional boolean` True if this user represents the authenticated account's own identity. - `phoneNumber: optional string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: optional string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `capabilities: optional map[unknown]` Runtime chat/message capabilities for this connected account, when available. - `loginID: optional string` Bridge login ID for this account, when known. One bridge login can contain multiple chat accounts. - `network: optional string` Human-friendly network name for the account. Omitted when the network is unknown. - `statusText: optional string` Human-friendly account status text. - `activeAccountCount: number` Number of active accounts for this network on this device. - `displayName: string` Human-friendly bridge name shown in Beeper. - `provider: "cloud" or "self-hosted" or "local" or "platform-sdk"` Where accounts for this bridge run: on this device or in Beeper Cloud. - `"cloud"` - `"self-hosted"` - `"local"` - `"platform-sdk"` - `status: "available" or "connected" or "limit_reached" or 2 more` Whether this bridge can currently be used to connect new accounts. - `"available"` - `"connected"` - `"limit_reached"` - `"temporarily_unavailable"` - `"disabled"` - `supportsMultipleAccounts: boolean` Whether this bridge can have multiple active accounts for the same network. - `type: string` Underlying bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. - `network: optional string` Network grouping used for account counts and limits. - `statusText: optional string` Human-friendly status text matching Beeper account management language. ### Cookie Field - `CookieField object { id, name, type }` - `id: string` Field ID to send back in the fields object. - `name: optional string` Cookie, header, or local storage key to collect. - `type: optional "cookie" or "header" or "local_storage"` Browser storage source for this value. - `"cookie"` - `"header"` - `"local_storage"` ### Disappearing Timer Capability - `DisappearingTimerCapability object { types, omit_empty_timer, timers }` Disappearing-message timer capability. - `types: array of "" or "after_read" or "after_send"` - `""` - `"after_read"` - `"after_send"` - `omit_empty_timer: optional true` - `true` - `timers: optional array of number` ### Group Field Capability - `GroupFieldCapability object { allowed, max_length, min_length, 2 more }` Group creation field capability. - `allowed: boolean` - `max_length: optional number` - `min_length: optional number` - `required: optional boolean` - `settings: optional DisappearingTimerCapability` Disappearing-message timer capability. - `types: array of "" or "after_read" or "after_send"` - `""` - `"after_read"` - `"after_send"` - `omit_empty_timer: optional true` - `true` - `timers: optional array of number` ### Group Type Capabilities - `GroupTypeCapabilities object { type_description, avatar, disappear, 5 more }` Group creation capabilities for one group type. - `type_description: string` - `avatar: optional GroupFieldCapability` Group creation field capability. - `allowed: boolean` - `max_length: optional number` - `min_length: optional number` - `required: optional boolean` - `settings: optional DisappearingTimerCapability` Disappearing-message timer capability. - `types: array of "" or "after_read" or "after_send"` - `""` - `"after_read"` - `"after_send"` - `omit_empty_timer: optional true` - `true` - `timers: optional array of number` - `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 - `LoginFlow object { id, description, name }` Connect or reconnect flow option for a bridge. - `id: string` Flow ID to pass when creating a bridge login session. - `description: optional string` Short explanation for when to use this flow, when provided. - `name: optional string` Display name for the flow, when provided. ### Login Input Field - `LoginInputField object { id, initialValue, label, 3 more }` - `id: string` Field ID to send back in the fields object. - `initialValue: optional string` Initial field value, when provided by the network. - `label: optional string` Field label to show to the user. - `optional: optional boolean` True if the user can leave this field empty. - `placeholder: optional string` Placeholder text to show when the field is empty. - `type: optional string` Suggested input type, such as text, password, or email. ### Login Session - `LoginSession object { bridgeID, loginSessionID, status, 6 more }` - `bridgeID: string` Bridge ID. - `loginSessionID: string` Temporary bridge login session ID. - `status: "waiting_for_input" or "waiting_for_cookies" or "waiting_for_display" or 3 more` - `"waiting_for_input"` - `"waiting_for_cookies"` - `"waiting_for_display"` - `"complete"` - `"cancelled"` - `"failed"` - `account: optional Account` A chat account added to Beeper. - `accountID: string` 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: string` 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: "cloud" or "self-hosted" or "local" or "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: string` Bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. Available in Beeper Desktop v4.2.785+. - `status: "connected" or "connecting" or "backfilling" or 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: string` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannotMessage: optional boolean` 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 string` Email address if known. Not guaranteed verified. - `fullName: optional string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL: optional string` 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. - `isSelf: optional boolean` True if this user represents the authenticated account's own identity. - `phoneNumber: optional string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: optional string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `capabilities: optional map[unknown]` Runtime chat/message capabilities for this connected account, when available. - `loginID: optional string` Bridge login ID for this account, when known. One bridge login can contain multiple chat accounts. - `network: optional string` Human-friendly network name for the account. Omitted when the network is unknown. - `statusText: optional string` Human-friendly account status text. - `accountID: optional string` Chat account ID for reconnect flows, when known. - `currentStep: optional object { fields, stepID, type, 2 more } or object { fields, stepID, type, 5 more } or object { display, stepID, type, instructions } or object { type, account, instructions, 2 more }` Step the client should show or complete next. Omitted when the session is complete, cancelled, or failed. - `UserInput object { fields, stepID, type, 2 more }` - `fields: array of LoginInputField` - `id: string` Field ID to send back in the fields object. - `initialValue: optional string` Initial field value, when provided by the network. - `label: optional string` Field label to show to the user. - `optional: optional boolean` True if the user can leave this field empty. - `placeholder: optional string` Placeholder text to show when the field is empty. - `type: optional string` Suggested input type, such as text, password, or email. - `stepID: string` - `type: "user_input"` - `"user_input"` - `attachments: optional array of unknown` - `instructions: optional string` User-facing instructions for this step. - `Cookies object { fields, stepID, type, 5 more }` - `fields: array of CookieField` - `id: string` Field ID to send back in the fields object. - `name: optional string` Cookie, header, or local storage key to collect. - `type: optional "cookie" or "header" or "local_storage"` Browser storage source for this value. - `"cookie"` - `"header"` - `"local_storage"` - `stepID: string` - `type: "cookies"` - `"cookies"` - `url: string` URL to open for the user. - `expectedFinalURLRegex: optional string` Regular expression that identifies the final URL after sign-in. - `extractJS: optional string` Optional extraction script for browser-based sign-in helpers. Treat as an opaque helper value. - `instructions: optional string` User-facing instructions for this browser step. - `userAgent: optional string` Suggested user agent for the browser session. - `DisplayAndWait object { display, stepID, type, instructions }` - `display: object { data, type } or object { imageURL, type } or object { type }` - `QrCode object { data, type }` - `data: string` - `type: "qr"` - `"qr"` - `Emoji object { imageURL, type }` - `imageURL: string` - `type: "emoji"` - `"emoji"` - `Empty object { type }` - `type: "nothing"` - `"nothing"` - `stepID: string` - `type: "display_and_wait"` - `"display_and_wait"` - `instructions: optional string` User-facing instructions for this step. - `Complete object { type, account, instructions, 2 more }` - `type: "complete"` - `"complete"` - `account: optional Account` A chat account added to Beeper. - `instructions: optional string` Completion instructions, when provided. - `login: optional object { bridgeID, loginID, removeScopes, 4 more }` Signed-in identity for a bridge. One bridge login can contain multiple chat accounts. - `bridgeID: string` Bridge ID. - `loginID: string` Bridge login ID. - `removeScopes: array of "current-device" or "all-devices"` - `"current-device"` - `"all-devices"` - `status: "connected" or "connecting" or "needs_login" or 2 more` - `"connected"` - `"connecting"` - `"needs_login"` - `"logged_out"` - `"unknown"` - `accountIDs: optional array of string` Chat accounts that belong to this bridge login, when known. - `statusText: optional string` Human-friendly bridge login status text. - `user: optional User` User the account belongs to. - `stepID: optional string` - `error: optional APIError` - `code: string` - `message: string` - `details: optional map[unknown]` - `login: optional object { bridgeID, loginID, removeScopes, 4 more }` Signed-in identity for a bridge. One bridge login can contain multiple chat accounts. - `bridgeID: string` Bridge ID. - `loginID: string` Bridge login ID. - `removeScopes: array of "current-device" or "all-devices"` - `"current-device"` - `"all-devices"` - `status: "connected" or "connecting" or "needs_login" or 2 more` - `"connected"` - `"connecting"` - `"needs_login"` - `"logged_out"` - `"unknown"` - `accountIDs: optional array of string` Chat accounts that belong to this bridge login, when known. - `statusText: optional string` Human-friendly bridge login status text. - `user: optional User` User the account belongs to. - `loginID: optional string` Bridge login ID for reconnect flows, when known. ### Provisioning Capabilities - `ProvisioningCapabilities object { group_creation, resolve_identifier, image_pack_import }` Advanced network capabilities for account lookup and group creation. - `group_creation: map[GroupTypeCapabilities]` - `type_description: string` - `avatar: optional GroupFieldCapability` Group creation field capability. - `allowed: boolean` - `max_length: optional number` - `min_length: optional number` - `required: optional boolean` - `settings: optional DisappearingTimerCapability` Disappearing-message timer capability. - `types: array of "" or "after_read" or "after_send"` - `""` - `"after_read"` - `"after_send"` - `omit_empty_timer: optional true` - `true` - `timers: optional array of number` - `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: boolean` - `contact_list: boolean` - `create_dm: boolean` - `lookup_email: boolean` - `lookup_phone: boolean` - `lookup_username: boolean` - `search: boolean` - `image_pack_import: optional boolean` ### Resolve Identifier Capabilities - `ResolveIdentifierCapabilities object { any_phone, contact_list, create_dm, 4 more }` Identifier lookup capabilities for this bridge. - `any_phone: boolean` - `contact_list: boolean` - `create_dm: boolean` - `lookup_email: boolean` - `lookup_phone: boolean` - `lookup_username: boolean` - `search: boolean` ### Bridge List Response - `BridgeListResponse object { items }` Available bridges and their connected accounts. - `items: array of Bridge` - `id: string` Bridge ID. Use with bridge endpoints. - `accounts: array of Account` Connected accounts for this bridge. Uses the same Account schema as GET /v1/accounts. - `accountID: string` 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: string` 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: "cloud" or "self-hosted" or "local" or "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: string` Bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. Available in Beeper Desktop v4.2.785+. - `status: "connected" or "connecting" or "backfilling" or 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: string` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannotMessage: optional boolean` 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 string` Email address if known. Not guaranteed verified. - `fullName: optional string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL: optional string` 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. - `isSelf: optional boolean` True if this user represents the authenticated account's own identity. - `phoneNumber: optional string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: optional string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `capabilities: optional map[unknown]` Runtime chat/message capabilities for this connected account, when available. - `loginID: optional string` Bridge login ID for this account, when known. One bridge login can contain multiple chat accounts. - `network: optional string` Human-friendly network name for the account. Omitted when the network is unknown. - `statusText: optional string` Human-friendly account status text. - `activeAccountCount: number` Number of active accounts for this network on this device. - `displayName: string` Human-friendly bridge name shown in Beeper. - `provider: "cloud" or "self-hosted" or "local" or "platform-sdk"` Where accounts for this bridge run: on this device or in Beeper Cloud. - `"cloud"` - `"self-hosted"` - `"local"` - `"platform-sdk"` - `status: "available" or "connected" or "limit_reached" or 2 more` Whether this bridge can currently be used to connect new accounts. - `"available"` - `"connected"` - `"limit_reached"` - `"temporarily_unavailable"` - `"disabled"` - `supportsMultipleAccounts: boolean` Whether this bridge can have multiple active accounts for the same network. - `type: string` Underlying bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. - `network: optional string` Network grouping used for account counts and limits. - `statusText: optional string` Human-friendly status text matching Beeper account management language. ### Bridge Retrieve Response - `BridgeRetrieveResponse object { id, accounts, activeAccountCount, 7 more }` Available bridge that can connect or reconnect chat accounts. - `id: string` Bridge ID. Use with bridge endpoints. - `accounts: array of Account` Connected accounts for this bridge. Uses the same Account schema as GET /v1/accounts. - `accountID: string` 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: string` 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: "cloud" or "self-hosted" or "local" or "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: string` Bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. Available in Beeper Desktop v4.2.785+. - `status: "connected" or "connecting" or "backfilling" or 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: string` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannotMessage: optional boolean` 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 string` Email address if known. Not guaranteed verified. - `fullName: optional string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL: optional string` 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. - `isSelf: optional boolean` True if this user represents the authenticated account's own identity. - `phoneNumber: optional string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: optional string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `capabilities: optional map[unknown]` Runtime chat/message capabilities for this connected account, when available. - `loginID: optional string` Bridge login ID for this account, when known. One bridge login can contain multiple chat accounts. - `network: optional string` Human-friendly network name for the account. Omitted when the network is unknown. - `statusText: optional string` Human-friendly account status text. - `activeAccountCount: number` Number of active accounts for this network on this device. - `displayName: string` Human-friendly bridge name shown in Beeper. - `provider: "cloud" or "self-hosted" or "local" or "platform-sdk"` Where accounts for this bridge run: on this device or in Beeper Cloud. - `"cloud"` - `"self-hosted"` - `"local"` - `"platform-sdk"` - `status: "available" or "connected" or "limit_reached" or 2 more` Whether this bridge can currently be used to connect new accounts. - `"available"` - `"connected"` - `"limit_reached"` - `"temporarily_unavailable"` - `"disabled"` - `supportsMultipleAccounts: boolean` Whether this bridge can have multiple active accounts for the same network. - `type: string` Underlying bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. - `network: optional string` Network grouping used for account counts and limits. - `statusText: optional string` Human-friendly status text matching Beeper account management language. # Login Flows ## List login flows **get** `/v1/bridges/{bridgeID}/login-flows` List connect and reconnect flow options for a bridge. Use a flowID when creating a bridge login session. ### Path Parameters - `bridgeID: string` Bridge ID. ### Returns - `items: array of LoginFlow` - `id: string` Flow ID to pass when creating a bridge login session. - `description: optional string` Short explanation for when to use this flow, when provided. - `name: optional string` Display name for the flow, when provided. ### Example ```http curl http://localhost:23373/v1/bridges/$BRIDGE_ID/login-flows \ -H "Authorization: Bearer $BEEPER_ACCESS_TOKEN" ``` #### Response ```json { "items": [ { "id": "id", "description": "description", "name": "name" } ] } ``` ## Domain Types ### Login Flow List Response - `LoginFlowListResponse object { items }` - `items: array of LoginFlow` - `id: string` Flow ID to pass when creating a bridge login session. - `description: optional string` Short explanation for when to use this flow, when provided. - `name: optional string` Display name for the flow, when provided. # Connections # Login Sessions ## Create bridge login session **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. ### Path Parameters - `bridgeID: string` Bridge ID. ### Body Parameters - `accountID: optional string` Existing chat account ID to reconnect. Omit to connect a new account. - `flowID: optional string` Optional flow ID returned by the list login flows endpoint. If omitted, Beeper chooses the default flow. - `loginID: optional string` Existing bridge login ID to reconnect. Omit to connect a new account. ### Returns - `LoginSession object { bridgeID, loginSessionID, status, 6 more }` - `bridgeID: string` Bridge ID. - `loginSessionID: string` Temporary bridge login session ID. - `status: "waiting_for_input" or "waiting_for_cookies" or "waiting_for_display" or 3 more` - `"waiting_for_input"` - `"waiting_for_cookies"` - `"waiting_for_display"` - `"complete"` - `"cancelled"` - `"failed"` - `account: optional Account` A chat account added to Beeper. - `accountID: string` 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: string` 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: "cloud" or "self-hosted" or "local" or "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: string` Bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. Available in Beeper Desktop v4.2.785+. - `status: "connected" or "connecting" or "backfilling" or 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: string` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannotMessage: optional boolean` 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 string` Email address if known. Not guaranteed verified. - `fullName: optional string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL: optional string` 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. - `isSelf: optional boolean` True if this user represents the authenticated account's own identity. - `phoneNumber: optional string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: optional string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `capabilities: optional map[unknown]` Runtime chat/message capabilities for this connected account, when available. - `loginID: optional string` Bridge login ID for this account, when known. One bridge login can contain multiple chat accounts. - `network: optional string` Human-friendly network name for the account. Omitted when the network is unknown. - `statusText: optional string` Human-friendly account status text. - `accountID: optional string` Chat account ID for reconnect flows, when known. - `currentStep: optional object { fields, stepID, type, 2 more } or object { fields, stepID, type, 5 more } or object { display, stepID, type, instructions } or object { type, account, instructions, 2 more }` Step the client should show or complete next. Omitted when the session is complete, cancelled, or failed. - `UserInput object { fields, stepID, type, 2 more }` - `fields: array of LoginInputField` - `id: string` Field ID to send back in the fields object. - `initialValue: optional string` Initial field value, when provided by the network. - `label: optional string` Field label to show to the user. - `optional: optional boolean` True if the user can leave this field empty. - `placeholder: optional string` Placeholder text to show when the field is empty. - `type: optional string` Suggested input type, such as text, password, or email. - `stepID: string` - `type: "user_input"` - `"user_input"` - `attachments: optional array of unknown` - `instructions: optional string` User-facing instructions for this step. - `Cookies object { fields, stepID, type, 5 more }` - `fields: array of CookieField` - `id: string` Field ID to send back in the fields object. - `name: optional string` Cookie, header, or local storage key to collect. - `type: optional "cookie" or "header" or "local_storage"` Browser storage source for this value. - `"cookie"` - `"header"` - `"local_storage"` - `stepID: string` - `type: "cookies"` - `"cookies"` - `url: string` URL to open for the user. - `expectedFinalURLRegex: optional string` Regular expression that identifies the final URL after sign-in. - `extractJS: optional string` Optional extraction script for browser-based sign-in helpers. Treat as an opaque helper value. - `instructions: optional string` User-facing instructions for this browser step. - `userAgent: optional string` Suggested user agent for the browser session. - `DisplayAndWait object { display, stepID, type, instructions }` - `display: object { data, type } or object { imageURL, type } or object { type }` - `QrCode object { data, type }` - `data: string` - `type: "qr"` - `"qr"` - `Emoji object { imageURL, type }` - `imageURL: string` - `type: "emoji"` - `"emoji"` - `Empty object { type }` - `type: "nothing"` - `"nothing"` - `stepID: string` - `type: "display_and_wait"` - `"display_and_wait"` - `instructions: optional string` User-facing instructions for this step. - `Complete object { type, account, instructions, 2 more }` - `type: "complete"` - `"complete"` - `account: optional Account` A chat account added to Beeper. - `instructions: optional string` Completion instructions, when provided. - `login: optional object { bridgeID, loginID, removeScopes, 4 more }` Signed-in identity for a bridge. One bridge login can contain multiple chat accounts. - `bridgeID: string` Bridge ID. - `loginID: string` Bridge login ID. - `removeScopes: array of "current-device" or "all-devices"` - `"current-device"` - `"all-devices"` - `status: "connected" or "connecting" or "needs_login" or 2 more` - `"connected"` - `"connecting"` - `"needs_login"` - `"logged_out"` - `"unknown"` - `accountIDs: optional array of string` Chat accounts that belong to this bridge login, when known. - `statusText: optional string` Human-friendly bridge login status text. - `user: optional User` User the account belongs to. - `stepID: optional string` - `error: optional APIError` - `code: string` - `message: string` - `details: optional map[unknown]` - `login: optional object { bridgeID, loginID, removeScopes, 4 more }` Signed-in identity for a bridge. One bridge login can contain multiple chat accounts. - `bridgeID: string` Bridge ID. - `loginID: string` Bridge login ID. - `removeScopes: array of "current-device" or "all-devices"` - `"current-device"` - `"all-devices"` - `status: "connected" or "connecting" or "needs_login" or 2 more` - `"connected"` - `"connecting"` - `"needs_login"` - `"logged_out"` - `"unknown"` - `accountIDs: optional array of string` Chat accounts that belong to this bridge login, when known. - `statusText: optional string` Human-friendly bridge login status text. - `user: optional User` User the account belongs to. - `loginID: optional string` Bridge login ID for reconnect flows, when known. ### Example ```http curl http://localhost:23373/v1/bridges/$BRIDGE_ID/login-sessions \ -X POST \ -H "Authorization: Bearer $BEEPER_ACCESS_TOKEN" ``` #### 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 **get** `/v1/bridges/{bridgeID}/login-sessions/{loginSessionID}` Get the current state of a temporary bridge login session. ### Path Parameters - `bridgeID: string` Bridge ID. - `loginSessionID: string` Temporary bridge login session ID. ### Returns - `LoginSession object { bridgeID, loginSessionID, status, 6 more }` - `bridgeID: string` Bridge ID. - `loginSessionID: string` Temporary bridge login session ID. - `status: "waiting_for_input" or "waiting_for_cookies" or "waiting_for_display" or 3 more` - `"waiting_for_input"` - `"waiting_for_cookies"` - `"waiting_for_display"` - `"complete"` - `"cancelled"` - `"failed"` - `account: optional Account` A chat account added to Beeper. - `accountID: string` 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: string` 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: "cloud" or "self-hosted" or "local" or "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: string` Bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. Available in Beeper Desktop v4.2.785+. - `status: "connected" or "connecting" or "backfilling" or 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: string` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannotMessage: optional boolean` 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 string` Email address if known. Not guaranteed verified. - `fullName: optional string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL: optional string` 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. - `isSelf: optional boolean` True if this user represents the authenticated account's own identity. - `phoneNumber: optional string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: optional string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `capabilities: optional map[unknown]` Runtime chat/message capabilities for this connected account, when available. - `loginID: optional string` Bridge login ID for this account, when known. One bridge login can contain multiple chat accounts. - `network: optional string` Human-friendly network name for the account. Omitted when the network is unknown. - `statusText: optional string` Human-friendly account status text. - `accountID: optional string` Chat account ID for reconnect flows, when known. - `currentStep: optional object { fields, stepID, type, 2 more } or object { fields, stepID, type, 5 more } or object { display, stepID, type, instructions } or object { type, account, instructions, 2 more }` Step the client should show or complete next. Omitted when the session is complete, cancelled, or failed. - `UserInput object { fields, stepID, type, 2 more }` - `fields: array of LoginInputField` - `id: string` Field ID to send back in the fields object. - `initialValue: optional string` Initial field value, when provided by the network. - `label: optional string` Field label to show to the user. - `optional: optional boolean` True if the user can leave this field empty. - `placeholder: optional string` Placeholder text to show when the field is empty. - `type: optional string` Suggested input type, such as text, password, or email. - `stepID: string` - `type: "user_input"` - `"user_input"` - `attachments: optional array of unknown` - `instructions: optional string` User-facing instructions for this step. - `Cookies object { fields, stepID, type, 5 more }` - `fields: array of CookieField` - `id: string` Field ID to send back in the fields object. - `name: optional string` Cookie, header, or local storage key to collect. - `type: optional "cookie" or "header" or "local_storage"` Browser storage source for this value. - `"cookie"` - `"header"` - `"local_storage"` - `stepID: string` - `type: "cookies"` - `"cookies"` - `url: string` URL to open for the user. - `expectedFinalURLRegex: optional string` Regular expression that identifies the final URL after sign-in. - `extractJS: optional string` Optional extraction script for browser-based sign-in helpers. Treat as an opaque helper value. - `instructions: optional string` User-facing instructions for this browser step. - `userAgent: optional string` Suggested user agent for the browser session. - `DisplayAndWait object { display, stepID, type, instructions }` - `display: object { data, type } or object { imageURL, type } or object { type }` - `QrCode object { data, type }` - `data: string` - `type: "qr"` - `"qr"` - `Emoji object { imageURL, type }` - `imageURL: string` - `type: "emoji"` - `"emoji"` - `Empty object { type }` - `type: "nothing"` - `"nothing"` - `stepID: string` - `type: "display_and_wait"` - `"display_and_wait"` - `instructions: optional string` User-facing instructions for this step. - `Complete object { type, account, instructions, 2 more }` - `type: "complete"` - `"complete"` - `account: optional Account` A chat account added to Beeper. - `instructions: optional string` Completion instructions, when provided. - `login: optional object { bridgeID, loginID, removeScopes, 4 more }` Signed-in identity for a bridge. One bridge login can contain multiple chat accounts. - `bridgeID: string` Bridge ID. - `loginID: string` Bridge login ID. - `removeScopes: array of "current-device" or "all-devices"` - `"current-device"` - `"all-devices"` - `status: "connected" or "connecting" or "needs_login" or 2 more` - `"connected"` - `"connecting"` - `"needs_login"` - `"logged_out"` - `"unknown"` - `accountIDs: optional array of string` Chat accounts that belong to this bridge login, when known. - `statusText: optional string` Human-friendly bridge login status text. - `user: optional User` User the account belongs to. - `stepID: optional string` - `error: optional APIError` - `code: string` - `message: string` - `details: optional map[unknown]` - `login: optional object { bridgeID, loginID, removeScopes, 4 more }` Signed-in identity for a bridge. One bridge login can contain multiple chat accounts. - `bridgeID: string` Bridge ID. - `loginID: string` Bridge login ID. - `removeScopes: array of "current-device" or "all-devices"` - `"current-device"` - `"all-devices"` - `status: "connected" or "connecting" or "needs_login" or 2 more` - `"connected"` - `"connecting"` - `"needs_login"` - `"logged_out"` - `"unknown"` - `accountIDs: optional array of string` Chat accounts that belong to this bridge login, when known. - `statusText: optional string` Human-friendly bridge login status text. - `user: optional User` User the account belongs to. - `loginID: optional string` Bridge login ID for reconnect flows, when known. ### Example ```http curl http://localhost:23373/v1/bridges/$BRIDGE_ID/login-sessions/$LOGIN_SESSION_ID \ -H "Authorization: Bearer $BEEPER_ACCESS_TOKEN" ``` #### 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 **delete** `/v1/bridges/{bridgeID}/login-sessions/{loginSessionID}` Cancel a temporary bridge login session. ### Path Parameters - `bridgeID: string` Bridge ID. - `loginSessionID: string` Temporary bridge login session ID. ### Returns - `bridgeID: string` - `loginSessionID: string` - `status: "cancelled"` - `"cancelled"` ### Example ```http curl http://localhost:23373/v1/bridges/$BRIDGE_ID/login-sessions/$LOGIN_SESSION_ID \ -X DELETE \ -H "Authorization: Bearer $BEEPER_ACCESS_TOKEN" ``` #### Response ```json { "bridgeID": "bridgeID", "loginSessionID": "loginSessionID", "status": "cancelled" } ``` ## Domain Types ### Login Session Cancel Response - `LoginSessionCancelResponse object { bridgeID, loginSessionID, status }` - `bridgeID: string` - `loginSessionID: string` - `status: "cancelled"` - `"cancelled"` # Steps ## Submit login step **post** `/v1/bridges/{bridgeID}/login-sessions/{loginSessionID}/steps/{stepID}` Submit input for the current step of a bridge login session. ### Path Parameters - `bridgeID: string` Bridge ID. - `loginSessionID: string` Temporary bridge login session ID. - `stepID: string` Current bridge login session step ID. ### Body Parameters - `type: "user_input" or "cookies" or "display_and_wait"` - `"user_input"` - `"cookies"` - `"display_and_wait"` - `fields: optional map[string]` Field values keyed by the field IDs from the current step. - `lastURL: optional string` Last browser URL reached during a cookies step, if available. - `source: optional "api" or "webview" or "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 - `LoginSession object { bridgeID, loginSessionID, status, 6 more }` - `bridgeID: string` Bridge ID. - `loginSessionID: string` Temporary bridge login session ID. - `status: "waiting_for_input" or "waiting_for_cookies" or "waiting_for_display" or 3 more` - `"waiting_for_input"` - `"waiting_for_cookies"` - `"waiting_for_display"` - `"complete"` - `"cancelled"` - `"failed"` - `account: optional Account` A chat account added to Beeper. - `accountID: string` 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: string` 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: "cloud" or "self-hosted" or "local" or "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: string` Bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter. Available in Beeper Desktop v4.2.785+. - `status: "connected" or "connecting" or "backfilling" or 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: string` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannotMessage: optional boolean` 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 string` Email address if known. Not guaranteed verified. - `fullName: optional string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL: optional string` 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. - `isSelf: optional boolean` True if this user represents the authenticated account's own identity. - `phoneNumber: optional string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: optional string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `capabilities: optional map[unknown]` Runtime chat/message capabilities for this connected account, when available. - `loginID: optional string` Bridge login ID for this account, when known. One bridge login can contain multiple chat accounts. - `network: optional string` Human-friendly network name for the account. Omitted when the network is unknown. - `statusText: optional string` Human-friendly account status text. - `accountID: optional string` Chat account ID for reconnect flows, when known. - `currentStep: optional object { fields, stepID, type, 2 more } or object { fields, stepID, type, 5 more } or object { display, stepID, type, instructions } or object { type, account, instructions, 2 more }` Step the client should show or complete next. Omitted when the session is complete, cancelled, or failed. - `UserInput object { fields, stepID, type, 2 more }` - `fields: array of LoginInputField` - `id: string` Field ID to send back in the fields object. - `initialValue: optional string` Initial field value, when provided by the network. - `label: optional string` Field label to show to the user. - `optional: optional boolean` True if the user can leave this field empty. - `placeholder: optional string` Placeholder text to show when the field is empty. - `type: optional string` Suggested input type, such as text, password, or email. - `stepID: string` - `type: "user_input"` - `"user_input"` - `attachments: optional array of unknown` - `instructions: optional string` User-facing instructions for this step. - `Cookies object { fields, stepID, type, 5 more }` - `fields: array of CookieField` - `id: string` Field ID to send back in the fields object. - `name: optional string` Cookie, header, or local storage key to collect. - `type: optional "cookie" or "header" or "local_storage"` Browser storage source for this value. - `"cookie"` - `"header"` - `"local_storage"` - `stepID: string` - `type: "cookies"` - `"cookies"` - `url: string` URL to open for the user. - `expectedFinalURLRegex: optional string` Regular expression that identifies the final URL after sign-in. - `extractJS: optional string` Optional extraction script for browser-based sign-in helpers. Treat as an opaque helper value. - `instructions: optional string` User-facing instructions for this browser step. - `userAgent: optional string` Suggested user agent for the browser session. - `DisplayAndWait object { display, stepID, type, instructions }` - `display: object { data, type } or object { imageURL, type } or object { type }` - `QrCode object { data, type }` - `data: string` - `type: "qr"` - `"qr"` - `Emoji object { imageURL, type }` - `imageURL: string` - `type: "emoji"` - `"emoji"` - `Empty object { type }` - `type: "nothing"` - `"nothing"` - `stepID: string` - `type: "display_and_wait"` - `"display_and_wait"` - `instructions: optional string` User-facing instructions for this step. - `Complete object { type, account, instructions, 2 more }` - `type: "complete"` - `"complete"` - `account: optional Account` A chat account added to Beeper. - `instructions: optional string` Completion instructions, when provided. - `login: optional object { bridgeID, loginID, removeScopes, 4 more }` Signed-in identity for a bridge. One bridge login can contain multiple chat accounts. - `bridgeID: string` Bridge ID. - `loginID: string` Bridge login ID. - `removeScopes: array of "current-device" or "all-devices"` - `"current-device"` - `"all-devices"` - `status: "connected" or "connecting" or "needs_login" or 2 more` - `"connected"` - `"connecting"` - `"needs_login"` - `"logged_out"` - `"unknown"` - `accountIDs: optional array of string` Chat accounts that belong to this bridge login, when known. - `statusText: optional string` Human-friendly bridge login status text. - `user: optional User` User the account belongs to. - `stepID: optional string` - `error: optional APIError` - `code: string` - `message: string` - `details: optional map[unknown]` - `login: optional object { bridgeID, loginID, removeScopes, 4 more }` Signed-in identity for a bridge. One bridge login can contain multiple chat accounts. - `bridgeID: string` Bridge ID. - `loginID: string` Bridge login ID. - `removeScopes: array of "current-device" or "all-devices"` - `"current-device"` - `"all-devices"` - `status: "connected" or "connecting" or "needs_login" or 2 more` - `"connected"` - `"connecting"` - `"needs_login"` - `"logged_out"` - `"unknown"` - `accountIDs: optional array of string` Chat accounts that belong to this bridge login, when known. - `statusText: optional string` Human-friendly bridge login status text. - `user: optional User` User the account belongs to. - `loginID: optional string` Bridge login ID for reconnect flows, when known. ### Example ```http curl http://localhost:23373/v1/bridges/$BRIDGE_ID/login-sessions/$LOGIN_SESSION_ID/steps/$STEP_ID \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $BEEPER_ACCESS_TOKEN" \ -d '{ "type": "user_input" }' ``` #### 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" } ```