# Connect sessions

> Hosted Embedded Signup links for your own customers.

Canonical: https://docs.whabuzz.com/api/connect-sessions/

Hosted Embedded Signup links for your own customers.

Base URL `https://api.whabuzz.com`. Every request needs `Authorization: Bearer <key>` unless the operation says otherwise; see [Authentication](https://docs.whabuzz.com/authentication.md). Errors follow the [two-source contract](https://docs.whabuzz.com/errors.md).

Operations on this page:

- [`POST /v1/connect-sessions`](#createConnectSession): Create a hosted Embedded Signup link
- [`GET /v1/connect-sessions/{session_id}`](#getConnectSession): Get a Connect session

## Create a hosted Embedded Signup link {#createConnectSession}

`POST /v1/connect-sessions`

Send your customer to `url`. After Meta's flow they return to `return_url?session_id=…&status=connected|failed`. Links expire after one hour.

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `createConnectSession`.

**Request body** (`application/json`, required)

| Field | Type | Required | Description |
|---|---|---|---|
| `return_url` | string (uri) | yes |  |

Request example:

```json
{
  "return_url": "https://app.example.com/settings/whatsapp"
}
```

cURL:

```bash
curl -X POST "https://api.whabuzz.com/v1/connect-sessions" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "return_url": "https://app.example.com/settings/whatsapp"
}'
```

**Responses**

**201** Session

```json
{
  "id": "cs_01JAB3N2R5T8W1Y4A7C0E3G6J9",
  "url": "https://app.whabuzz.com/connect/9fK2mQ7xL4pV1sN8cR3t",
  "expires_at": "2026-10-16T11:00:00Z",
  "status": "open"
}
```

## Get a Connect session {#getConnectSession}

`GET /v1/connect-sessions/{session_id}`

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `getConnectSession`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `session_id` | path | string | yes |  |

cURL:

```bash
curl -X GET "https://api.whabuzz.com/v1/connect-sessions/$SESSION_ID" \
  -H "Authorization: Bearer $WHABUZZ_KEY"
```

**Responses**

**200** Session

```json
{
  "id": "cs_01JAB3N2R5T8W1Y4A7C0E3G6J9",
  "status": "connected",
  "result": {
    "waba_id": "26059971920328384",
    "phone_number_ids": [
      "1013622581841046"
    ]
  },
  "expires_at": "2026-10-16T11:00:00Z"
}
```