# Bridges

## List available bridges

`$client->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

- `BridgeListResponse`

  - `list<Bridge> items`

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$bridges = $client->bridges->list();

var_dump($bridges);
```

#### 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

`$client->bridges->retrieve(string bridgeID): BridgeGetResponse`

**get** `/v1/bridges/{bridgeID}`

Get one bridge, including the chat accounts connected through it.

### Parameters

- `bridgeID: string`

  Bridge ID.

### Returns

- `BridgeGetResponse`

  - `string id`

    Bridge ID. Use with bridge endpoints.

  - `list<Account> accounts`

    Connected accounts for this bridge. Uses the same Account schema as GET /v1/accounts.

  - `int activeAccountCount`

    Number of active accounts for this network on this device.

  - `string displayName`

    Human-friendly bridge name shown in Beeper.

  - `Provider provider`

    Where accounts for this bridge run: on this device or in Beeper Cloud.

  - `Status status`

    Whether this bridge can currently be used to connect new accounts.

  - `bool supportsMultipleAccounts`

    Whether this bridge can have multiple active accounts for the same network.

  - `string type`

    Underlying bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter.

  - `?string network`

    Network grouping used for account counts and limits.

  - `?string statusText`

    Human-friendly status text matching Beeper account management language.

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$bridge = $client->bridges->retrieve('local-whatsapp');

var_dump($bridge);
```

#### 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

`$client->bridges->retrieveCapabilities(string bridgeID): 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

- `bridgeID: string`

  Bridge ID.

### Returns

- `ProvisioningCapabilities`

  - `array<string,GroupTypeCapabilities> groupCreation`

  - `ResolveIdentifierCapabilities resolveIdentifier`

    Identifier lookup capabilities for this bridge.

  - `?bool imagePackImport`

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$provisioningCapabilities = $client->bridges->retrieveCapabilities(
  'local-whatsapp'
);

var_dump($provisioningCapabilities);
```

#### 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`

  - `string id`

    Bridge ID. Use with bridge endpoints.

  - `list<Account> accounts`

    Connected accounts for this bridge. Uses the same Account schema as GET /v1/accounts.

  - `int activeAccountCount`

    Number of active accounts for this network on this device.

  - `string displayName`

    Human-friendly bridge name shown in Beeper.

  - `Provider provider`

    Where accounts for this bridge run: on this device or in Beeper Cloud.

  - `Status status`

    Whether this bridge can currently be used to connect new accounts.

  - `bool supportsMultipleAccounts`

    Whether this bridge can have multiple active accounts for the same network.

  - `string type`

    Underlying bridge type, such as matrix, discordgo, slackgo, whatsapp, telegram, or twitter.

  - `?string network`

    Network grouping used for account counts and limits.

  - `?string statusText`

    Human-friendly status text matching Beeper account management language.

### Cookie Field

- `CookieField`

  - `string id`

    Field ID to send back in the fields object.

  - `?string name`

    Cookie, header, or local storage key to collect.

  - `?Type type`

    Browser storage source for this value.

### Disappearing Timer Capability

- `DisappearingTimerCapability`

  - `list<Type> types`

  - `?true omitEmptyTimer`

  - `?list<int> timers`

### Group Field Capability

- `GroupFieldCapability`

  - `bool allowed`

  - `?int maxLength`

  - `?int minLength`

  - `?bool required`

  - `?DisappearingTimerCapability settings`

    Disappearing-message timer capability.

### Group Type Capabilities

- `GroupTypeCapabilities`

  - `string typeDescription`

  - `?GroupFieldCapability avatar`

    Group creation field capability.

  - `?GroupFieldCapability disappear`

    Group creation field capability.

  - `?GroupFieldCapability name`

    Group creation field capability.

  - `?GroupFieldCapability parent`

    Group creation field capability.

  - `?GroupFieldCapability participants`

    Group creation field capability.

  - `?GroupFieldCapability topic`

    Group creation field capability.

  - `?GroupFieldCapability username`

    Group creation field capability.

### Login Flow

- `LoginFlow`

  - `string id`

    Flow ID to pass when creating a bridge login session.

  - `?string description`

    Short explanation for when to use this flow, when provided.

  - `?string name`

    Display name for the flow, when provided.

### Login Input Field

- `LoginInputField`

  - `string id`

    Field ID to send back in the fields object.

  - `?string initialValue`

    Initial field value, when provided by the network.

  - `?string label`

    Field label to show to the user.

  - `?bool optional`

    True if the user can leave this field empty.

  - `?string placeholder`

    Placeholder text to show when the field is empty.

  - `?string type`

    Suggested input type, such as text, password, or email.

### Login Session

- `LoginSession`

  - `string bridgeID`

    Bridge ID.

  - `string loginSessionID`

    Temporary bridge login session ID.

  - `Status status`

  - `?Account account`

    A chat account added to Beeper.

  - `?string accountID`

    Chat account ID for reconnect flows, when known.

  - `?CurrentStep currentStep`

    Step the client should show or complete next. Omitted when the session is complete, cancelled, or failed.

  - `?APIError error`

  - `?Login login`

    Signed-in identity for a bridge. One bridge login can contain multiple chat accounts.

  - `?string loginID`

    Bridge login ID for reconnect flows, when known.

### Provisioning Capabilities

- `ProvisioningCapabilities`

  - `array<string,GroupTypeCapabilities> groupCreation`

  - `ResolveIdentifierCapabilities resolveIdentifier`

    Identifier lookup capabilities for this bridge.

  - `?bool imagePackImport`

### Resolve Identifier Capabilities

- `ResolveIdentifierCapabilities`

  - `bool anyPhone`

  - `bool contactList`

  - `bool createDM`

  - `bool lookupEmail`

  - `bool lookupPhone`

  - `bool lookupUsername`

  - `bool search`

# Login Flows

## List login flows

`$client->bridges->loginFlows->list(string bridgeID): 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

- `bridgeID: string`

  Bridge ID.

### Returns

- `LoginFlowListResponse`

  - `list<LoginFlow> items`

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$loginFlows = $client->bridges->loginFlows->list('local-whatsapp');

var_dump($loginFlows);
```

#### Response

```json
{
  "items": [
    {
      "id": "id",
      "description": "description",
      "name": "name"
    }
  ]
}
```

# Connections

# Login Sessions

## Create bridge login session

`$client->bridges->loginSessions->create(string bridgeID, ?string accountID, ?string flowID, ?string loginID): 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

- `bridgeID: string`

  Bridge ID.

- `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`

  - `string bridgeID`

    Bridge ID.

  - `string loginSessionID`

    Temporary bridge login session ID.

  - `Status status`

  - `?Account account`

    A chat account added to Beeper.

  - `?string accountID`

    Chat account ID for reconnect flows, when known.

  - `?CurrentStep currentStep`

    Step the client should show or complete next. Omitted when the session is complete, cancelled, or failed.

  - `?APIError error`

  - `?Login login`

    Signed-in identity for a bridge. One bridge login can contain multiple chat accounts.

  - `?string loginID`

    Bridge login ID for reconnect flows, when known.

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$loginSession = $client->bridges->loginSessions->create(
  'local-whatsapp', accountID: 'x', flowID: 'x', loginID: 'x'
);

var_dump($loginSession);
```

#### 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

`$client->bridges->loginSessions->retrieve(string loginSessionID, string bridgeID): LoginSession`

**get** `/v1/bridges/{bridgeID}/login-sessions/{loginSessionID}`

Get the current state of a temporary bridge login session.

### Parameters

- `bridgeID: string`

  Bridge ID.

- `loginSessionID: string`

  Temporary bridge login session ID.

### Returns

- `LoginSession`

  - `string bridgeID`

    Bridge ID.

  - `string loginSessionID`

    Temporary bridge login session ID.

  - `Status status`

  - `?Account account`

    A chat account added to Beeper.

  - `?string accountID`

    Chat account ID for reconnect flows, when known.

  - `?CurrentStep currentStep`

    Step the client should show or complete next. Omitted when the session is complete, cancelled, or failed.

  - `?APIError error`

  - `?Login login`

    Signed-in identity for a bridge. One bridge login can contain multiple chat accounts.

  - `?string loginID`

    Bridge login ID for reconnect flows, when known.

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$loginSession = $client->bridges->loginSessions->retrieve(
  '123', bridgeID: 'local-whatsapp'
);

var_dump($loginSession);
```

#### 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

`$client->bridges->loginSessions->cancel(string loginSessionID, string bridgeID): LoginSessionCancelResponse`

**delete** `/v1/bridges/{bridgeID}/login-sessions/{loginSessionID}`

Cancel a temporary bridge login session.

### Parameters

- `bridgeID: string`

  Bridge ID.

- `loginSessionID: string`

  Temporary bridge login session ID.

### Returns

- `LoginSessionCancelResponse`

  - `string bridgeID`

  - `string loginSessionID`

  - `"cancelled" status`

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$response = $client->bridges->loginSessions->cancel(
  '123', bridgeID: 'local-whatsapp'
);

var_dump($response);
```

#### Response

```json
{
  "bridgeID": "bridgeID",
  "loginSessionID": "loginSessionID",
  "status": "cancelled"
}
```

# Steps

## Submit login step

`$client->bridges->loginSessions->steps->submit(string stepID, string bridgeID, string loginSessionID, Type type, ?array<string,string> fields, ?string lastURL, ?Source source): LoginSession`

**post** `/v1/bridges/{bridgeID}/login-sessions/{loginSessionID}/steps/{stepID}`

Submit input for the current step of a bridge login session.

### Parameters

- `bridgeID: string`

  Bridge ID.

- `loginSessionID: string`

  Temporary bridge login session ID.

- `stepID: string`

  Current bridge login session step ID.

- `type: Type`

- `fields?:optional array<string,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 Source`

  How the step was completed. Omit unless the client needs to distinguish an embedded webview or browser extension.

### Returns

- `LoginSession`

  - `string bridgeID`

    Bridge ID.

  - `string loginSessionID`

    Temporary bridge login session ID.

  - `Status status`

  - `?Account account`

    A chat account added to Beeper.

  - `?string accountID`

    Chat account ID for reconnect flows, when known.

  - `?CurrentStep currentStep`

    Step the client should show or complete next. Omitted when the session is complete, cancelled, or failed.

  - `?APIError error`

  - `?Login login`

    Signed-in identity for a bridge. One bridge login can contain multiple chat accounts.

  - `?string loginID`

    Bridge login ID for reconnect flows, when known.

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$loginSession = $client->bridges->loginSessions->steps->submit(
  'x',
  bridgeID: 'local-whatsapp',
  loginSessionID: '123',
  type: 'user_input',
  fields: ['foo' => 'string'],
  lastURL: 'lastURL',
  source: 'api',
);

var_dump($loginSession);
```

#### 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"
}
```