> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedded inbox

> Embed the inbox into your own application via iframe

Embed the inbox into your own application via iframe. Useful for CRM integrations, customer portals, or internal tools.

## Setup

### API

Create an embed:

```bash theme={null}
curl -X POST https://api.kapso.ai/platform/v1/inbox_embeds \
  -H "X-API-Key: $KAPSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_embed": {
      "name": "Support inbox",
      "scope_type": "phone_number",
      "scope_id": "1234567890",
      "allowed_origins": ["https://app.example.com"],
      "default_mode": "system",
      "language": "es"
    }
  }'
```

The create response returns `token` and `embed_url` once. Store the `embed_url`; list, get, and update responses do not return it.

Scope types:

| Scope          | `scope_id`                 |
| -------------- | -------------------------- |
| `project`      | Leave blank                |
| `customer`     | Customer UUID              |
| `phone_number` | WhatsApp `phone_number_id` |

Manage embeds:

```bash theme={null}
curl https://api.kapso.ai/platform/v1/inbox_embeds \
  -H "X-API-Key: $KAPSO_API_KEY"

curl -X PATCH https://api.kapso.ai/platform/v1/inbox_embeds/{id} \
  -H "X-API-Key: $KAPSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_embed": {
      "allowed_origins": ["https://app.example.com"],
      "default_mode": "dark",
      "language": "es"
    }
  }'

curl -X DELETE https://api.kapso.ai/platform/v1/inbox_embeds/{id} \
  -H "X-API-Key: $KAPSO_API_KEY"
```

### Dashboard

1. Go to **Project → Inbox Embeds**
2. Create an access token with a name and scope
3. Choose the default UI language for the embedded inbox
4. Copy the embed URL or iframe snippet

## Embed code

```html theme={null}
<iframe
  src="https://inbox.kapso.ai/embed/{token}"
  style="width: 100%; height: 100%; border: 0;"
></iframe>
```

Real-time message updates work automatically via WebSocket.

## Scopes

Control which conversations are visible:

| Scope          | Conversations shown                          |
| -------------- | -------------------------------------------- |
| `project`      | All conversations in the project             |
| `phone_number` | Conversations for a specific WhatsApp number |
| `customer`     | Conversations for a specific customer        |

### Filter by assignee

Optionally set `assigned_user_id` on the token to only show conversations assigned to a specific team member. The token will only return conversations with an active assignment to that user.

## Security

### Allowed origins

Whitelist domains that can embed the inbox. Supports wildcards (`*.example.com`). Leave empty to allow any origin.

Allowed origins are enforced via both CORS validation on API requests and `Content-Security-Policy: frame-ancestors` on the iframe page.

### Token expiration

Optionally set an expiration date on the token. Expired tokens return a 401 error.

## Query parameters

Pre-set filters and theme by passing query parameters to the embed URL. These apply as initial state when the iframe loads.

### Filters

| Parameter            | Values                   | Default  | Description                                       |
| -------------------- | ------------------------ | -------- | ------------------------------------------------- |
| `status`             | `active`, `ended`, `all` | `active` | Conversation status filter                        |
| `search`             | string                   | `""`     | Pre-fill the search box                           |
| `whatsapp_config_id` | UUID or `all`            | `all`    | Filter by a specific WhatsApp number              |
| `unread`             | `1`, `true`, or omit     | `all`    | Show only unread conversations                    |
| `handoff`            | `1`, `true`, or omit     | `all`    | Show only conversations waiting for human handoff |

Example — open the inbox pre-filtered to unread handoff conversations:

```
https://inbox.kapso.ai/embed/{token}?status=active&unread=1&handoff=1
```

### Theme

Set the default theme when creating the token: `system`, `light`, or `dark`.

Override the theme via the `mode` parameter:

```
https://inbox.kapso.ai/embed/{token}?mode=dark
```

The user's choice is persisted in localStorage for subsequent visits.

### Language

Set the default UI language when creating or updating the token:

| Value | Language |
| ----- | -------- |
| `en`  | English  |
| `es`  | Spanish  |

Override the token default for a specific iframe URL with `language` or `lang`:

```
https://inbox.kapso.ai/embed/{token}?language=es
```

## Feature differences

### Disabled in embedded inbox

* Assignments
* Starting new conversations
* Browser notifications
* Contact notes (hidden entirely)

### Available in embedded inbox

* Status, WhatsApp number, and search filters
* Send text, media, and interactive messages
* Workflow handoff (Handoff button works)
* Contact display name editing
* Real-time WebSocket updates