Skip to main content
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"
    }
  }'
The create response returns token and embed_url once. Store the embed_url; list, get, and update responses do not return it. Scope types:
Scopescope_id
projectLeave blank
customerCustomer UUID
phone_numberWhatsApp 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"
    }
  }'

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. 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:
ScopeConversations shown
projectAll conversations in the project
phone_numberConversations for a specific WhatsApp number
customerConversations 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

ParameterValuesDefaultDescription
statusactive, ended, allactiveConversation status filter
searchstring""Pre-fill the search box
whatsapp_config_idUUID or allallFilter by a specific WhatsApp number
unread1, true, or omitallShow only unread conversations
handoff1, true, or omitallShow 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.

​
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