Embedded inbox

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

Setup

API

Create an embed:

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:

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

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

Embed code

<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

Getting started

Connect

Operate

Extend

API Reference

Customers

Setup Links

Webhooks

Phone Numbers

Broadcasts

Messages

Conversations

Display Names

Media

Contacts

Users

Webhook Deliveries

Events

API Logs

Log Search

Provider Models

Inbox Embeds

WhatsApp Flows

Setup

API

Dashboard

Embed code

Scopes

Filter by assignee

Security

Allowed origins

Token expiration

Query parameters

Filters

Theme

Language

Feature differences

Disabled in embedded inbox

Available in embedded inbox

​Setup

​API

​Dashboard

​Embed code

​Scopes

​Filter by assignee

​Security

​Allowed origins

​Token expiration

​Query parameters

​Filters

​Theme

​Language

​Feature differences

​Disabled in embedded inbox

​Available in embedded inbox

Setup

API

Dashboard

Embed code

Scopes

Filter by assignee

Security

Allowed origins

Token expiration

Query parameters

Filters

Theme

Language

Feature differences

Disabled in embedded inbox

Available in embedded inbox