> ## 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.
# Changelog
> Product updates and announcements
## Features
**Project events**: You can use workflows or the API to record custom events such as outcomes, scores, labels, and other facts, then use those events to start follow-up workflows.
Add an Emit event node, enable the Agent node's `emit_event` tool, return events from a Function node or use the API to emit them.
Events can be queried later through the Platform API or used as a Project event trigger to start a workflow when a matching event is emitted, with an optional property filter.
See [Project events](/docs/platform/events) and [Use project events in workflows](/docs/flows/project-events).
## Features
**WhatsApp setup and recovery improvements**: WhatsApp setup now supports saved Meta apps, config-specific Meta app credentials, recovery tokens for restoring WhatsApp API access, and a clearer success state after connecting a number.
Add a Meta app once, then select it when manually configuring WhatsApp numbers or recovering access for an existing number. Recovery tokens validate the system-user token, WABA access, phone number access, and template access before Kapso saves the recovered connection.
Projects using Custom Twilio can also import existing Twilio numbers into project-owned phone number pools. Imported numbers are checked against the project's Twilio account, configured for Meta verification calls, and queued for preverification.
## API changes
**Platform log search API**: Platform API clients can now search project logs through `GET /platform/v1/log_search` and `POST /platform/v1/log_search`.
Search across API logs, Meta webhook events, workflow events, and webhook deliveries with a query, source, time period, exact filters, `problems_only`, and cursor pagination. Use `GET /platform/v1/log_search/catalog` to inspect available sources and filter keys.
## Tools & SDKs
**MCP log search tool**: Project MCP now includes `search_logs`, so connected agents can debug request IDs, WhatsApp message IDs, webhook deliveries, Meta events, and workflow execution IDs from redacted project log summaries.
## Features
**Embedded inbox language support**: Embedded inbox access tokens now include a `language` setting for the iframe UI.
Set `language` when creating or updating `/platform/v1/inbox_embeds`. The embedded inbox currently supports English (`en`) and Spanish (`es`), and iframe URLs can override the token default with `?language=es` or `?lang=es`.
See [Embedded inbox](/docs/platform/inbox/embedded).
## API changes
**WhatsApp usernames and BSUID sending**: Kapso now supports BSUID-targeted sends, phone number request messages, and WhatsApp business username management through the Meta proxy API.
Use `recipient` to send supported messages to a customer's BSUID or parent BSUID when you do not have their phone number. The `to` field remains for phone numbers and takes precedence when both fields are present.
You can also request a customer's phone number in-thread with `interactive.type: "request_contact_info"` or a `REQUEST_CONTACT_INFO` template button, and manage business usernames with the username and username suggestion endpoints.
See [Business-scoped user IDs](/docs/whatsapp/business-scoped-user-ids), [Request contact info](/docs/whatsapp/send-messages/request-contact-info), and [Business usernames](/docs/whatsapp/business-usernames).
## API changes
**WhatsApp broadcast controls**: Platform API broadcasts can now be stopped while sending, and draft or scheduled broadcasts can have all recipients cleared.
Use `PATCH /platform/v1/whatsapp/broadcasts/{broadcast_id}` with `status: "stopped"` to stop a sending broadcast. Use `DELETE /platform/v1/whatsapp/broadcasts/{broadcast_id}/recipients` to clear recipients.
Broadcast responses now include `stopped_at` when a broadcast has been stopped.
## Workflows
**Contact conversation history for agent nodes**: Agent nodes can now use the `contact_conversations` default tool to list and read older WhatsApp conversations for the current contact.
Enable the tool when an agent should use previous support context before replying to a returning WhatsApp contact.
```json theme={null}
{
"node_type": "agent",
"config": {
"enabled_default_tools": [
"get_whatsapp_context",
"contact_conversations",
"complete_task"
]
}
}
```
## Workflows
**Tool-only delivery for agent nodes**: Agent nodes can now keep normal assistant text internal and send user-visible WhatsApp messages only through tools.
Use `message_delivery_mode: "tool_only"` when the agent should send every customer-facing message through `send_notification_to_user`. This is useful when the agent needs tighter control over when it asks questions, sends multiple messages, or pauses with `enter_waiting`.
```json theme={null}
{
"node_type": "agent",
"config": {
"message_delivery_mode": "tool_only",
"enabled_default_tools": [
"complete_task",
"handoff_to_human",
"enter_waiting",
"send_notification_to_user"
]
}
}
```
## Integrations
**Agent and automation integrations**: New integration docs are available for n8n, Chat SDK, OpenClaw, and Hermes Agent.
Use the verified Kapso n8n node to trigger workflows from WhatsApp events and send replies or templates. Use the agent integrations to connect WhatsApp to Chat SDK, OpenClaw, or Hermes Agent.
See [n8n](/docs/whatsapp/n8n), [Chat SDK](/docs/whatsapp/chat-sdk), [OpenClaw](/docs/whatsapp/openclaw), and [Hermes Agent](/docs/whatsapp/hermes-agent).
## API changes
**WhatsApp carousel message support**: Kapso now preserves, validates, and renders WhatsApp interactive carousel payloads across Meta proxy sends, inbox message bubbles, and stored message metadata.
Carousel support is additive. Workflow send-interactive actions still reject `carousel`; use the raw Meta proxy for carousel payloads.
## Features
**Project home and billing improvements**: The project home screen now combines usage charts, period filtering, and a Kapso Agent panel. Project navigation was simplified, developer tools were consolidated, and billing now shows usage costs with clearer plan-change and cancellation previews.
## Bug fixes
**Template header variables in message content**: Fixed an issue where template header variables could render incorrectly in outbound message content across template sends, broadcasts, MCP sends, and persisted message views.
## Features
**Per-project audio transcription toggle**: Project settings now include an "Automatic audio transcription" switch that controls whether inbound WhatsApp audio messages are transcribed and whether transcripts are included in message content and webhooks.
Enabled by default. Find it under Project settings.
## Tools & SDKs
**Project MCP server**: AI agents can now manage Kapso projects through MCP.
Connect an MCP-capable agent to `https://api.kapso.ai/mcp` with a project API key to inspect status, search docs, manage customers and setup links, list WhatsApp numbers, read conversations and messages, send messages, manage templates, and configure webhooks.
Use Project MCP when your agent should operate Kapso directly without shell access. Use the CLI when the agent is working from a terminal.
See [MCP server](/docs/whatsapp/mcp).
## API changes
**Model-aware reasoning metadata**: `GET /platform/v1/provider_models` now returns additive model metadata for reasoning-capable models:
* `reasoning_model`
* `supported_reasoning_efforts`
* `default_reasoning_effort`
* `api_surface`
Workflow agent `reasoning_effort` now documents the full model-aware value set: `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Use each provider model's `supported_reasoning_efforts` before sending a value.
## API changes
**Cursor pagination for high-volume Platform API lists**: Public docs now show cursor pagination (`limit`, `after`, and `before`) for WhatsApp messages, conversations, webhook deliveries, API logs, workflow executions, conversation flow executions, and workflow execution events. Responses include a `paging` object with `cursors.before`, `cursors.after`, `next`, and `previous`.
Existing `page` / `per_page` integrations remain supported for compatibility with bounded estimated totals, but cursor pagination is the documented path for new integrations.
## API changes
**Inbox embed management via Platform API**: You can now create, list, update, and revoke inbox embeds through `/platform/v1/inbox_embeds`.
Create requests use public scopes: `project`, `customer`, and `phone_number`. The create response returns the raw `token` and `embed_url` once; subsequent list, get, and update responses omit secrets.
See [Embedded inbox](/docs/platform/inbox/embedded).
## API changes
**Reconnect setup links**: Setup links now accept a `reconnect_phone_number` to scope the WhatsApp onboarding flow to an existing customer number — useful when a token expires, the customer changes their Meta password, or a connection is otherwise revoked.
```json theme={null}
{
"setup_link": {
"reconnect_phone_number": "+14155551234"
}
}
```
When set, Kapso looks up the customer's existing WhatsApp config matching that number and refreshes credentials in place. `provision_phone_number` is forced to `false` and `allowed_connection_types` is locked to match the existing config (`["dedicated"]` or `["coexistence"]`). The number must already exist on a production WhatsApp config for the customer.
See [Setup links — Reconnect existing numbers](/docs/platform/setup-links#reconnect-existing-numbers).
## API changes
**Source sync support for flows and functions**: The Platform API now exposes the building blocks needed to mirror flows from an external source of truth.
* **Flow slugs**: `GET /platform/v1/workflows/...` responses include a `slug` field, and create/update accept it. Slugs are stable across renames — use them as your external sync key.
* **Function optimistic locking**: Function responses include a `lock_version` field. Pass it on update to detect concurrent modifications — stale updates return `409 Conflict`.
* **Bulk replace triggers**: New `PUT /platform/v1/workflows/{workflow_id}/triggers` endpoint atomically replaces the full set of triggers for a flow. Pass the complete desired set in `{ "triggers": [...] }`; existing triggers not in the list are removed.
All changes are additive. Existing integrations are unaffected.
## Workflows
**Remote sandbox for agent nodes**: Agent nodes can now mount GitHub repositories into a remote ephemeral sandbox.
You can:
* enable sandbox access per agent node
* attach GitHub repositories with a PAT
* control outbound sandbox access with `allow_all` or `allow_list`
* let the agent inspect and edit repository files with sandbox tools
v1 is GitHub-only. Remote sandbox is in beta, free during the beta, and pricing may change later.
See [Agent node](/docs/flows/step-types/agent-node) for the configuration reference.
## Features
**WhatsApp identities in the inbox**: Contact and conversation panels in the inbox now display business-scoped user IDs and usernames alongside (or in place of) phone numbers, matching the identity data that was already available via the API and webhooks.
## API changes
**WhatsApp BSUID fields on inbound and read surfaces**: Kapso now exposes additive WhatsApp identity fields across the relevant webhook, API, and workflow-context surfaces:
* `business_scoped_user_id`
* `parent_business_scoped_user_id`
* `username`
* Meta-style message fields like `from_user_id` and `to_user_id`
This is an additive rollout. Existing phone-based fields still exist, but `phone_number` and `wa_id` can now be nullable on some payloads when Meta only provides BSUID-based identity.
Outbound sending in Kapso remains phone-based for now. Keep using `to` when sending messages.
See [Business-scoped user IDs](/docs/whatsapp/business-scoped-user-ids) for the migration guide.
## API changes
**Public function endpoints**: Functions now expose a `public_endpoint` field in the Platform API.
For deployed Cloudflare functions:
* `public_endpoint: false` keeps the invoke URL private and requires `X-API-Key`
* `public_endpoint: true` allows invoke requests without an API key
* `endpoint_url` now returns the Kapso Platform API URL on `https://api.kapso.ai/platform/v1/functions/{function_id}/invoke`
* newly created functions default to `invoke_response_mode: passthrough`
* existing wrapped functions keep `invoke_response_mode: wrapped` so older integrations still receive successful JSON under `data`
Private and unknown functions both return `404` from the invoke route.
## Bug fixes
**WhatsApp broadcast delivery status accuracy**: Fixed an issue where broadcast message statuses could get stuck or incorrectly revert when WhatsApp delivery webhooks arrived out of order or with delays. Messages that temporarily failed now recover correctly when a subsequent delivery confirmation arrives, and late-arriving status updates no longer downgrade an already-delivered message.
## API changes
**Block users via WhatsApp proxy**: Three new endpoints for blocking and unblocking users on a phone number — `GET`, `POST`, and `DELETE` on `/{phone_number_id}/block_users`. These proxy directly to Meta's Block Users API.
**Contact erasure**: `DELETE /whatsapp/contacts/{identifier}` permanently erases a contact and all associated data (conversations, messages, media). The identifier can be the contact UUID or phone number. Erasure is processed asynchronously — a `204` response confirms the job was queued.
## Features
**Archive and restore workflows**: Workflows can now be archived to hide them from the active list without deleting them. Archived workflows are accessible from the new **Archived** tab and can be restored to draft status at any time — from the workflow settings panel or directly from the list.
## API changes
**Workflow definition endpoint**: Added documentation for `GET /platform/v1/workflows/{workflow_id}/definition`, which returns the workflow graph definition (`nodes` and `edges`) alongside workflow metadata.
## Features
**Delivery status indicators in inbox**: Message bubbles in the inbox now show real-time delivery status icons — pending, sent, delivered, read, and failed. Status updates are pushed instantly without a page refresh.
## API changes
**Authenticated media downloads**: The [Get media URL](/api-reference/meta/whatsapp/getMediaUrl) endpoint now returns two additional fields:
* `download_url` — a Kapso-hosted URL that downloads the media file without extra auth headers (token embedded in URL)
* `download_url_expires_at` — ISO 8601 expiry timestamp (4 minutes from issue)
```json theme={null}
{
"id": "2621233374848975",
"url": "https://lookaside.fbsbx.com/...",
"mime_type": "image/jpeg",
"file_size": "303833",
"sha256": "81d3bd8a8db4868c9...",
"download_url": "https://api.kapso.ai/meta/whatsapp/media_download?token=...",
"download_url_expires_at": "2026-03-13T12:34:56Z"
}
```
Use `download_url` when you need to serve or fetch media from a server or browser without forwarding your API key — the token is self-contained. Fall back to the `url` field if you prefer to handle Meta CDN downloads directly.
## Features
**1 free WhatsApp number for new users**: Free plan users can now claim one Kapso-managed WhatsApp number without a wallet deposit. The number is provisioned through the standard instant setup flow. If the number has no production messages within 30 days, it is automatically released.
## Features
**Bring your own Twilio for phone provisioning**: Projects can now use their own Twilio account for WhatsApp phone number provisioning.
This unlocks:
* local phone numbers outside the default US instant-setup path
* project-owned phone number pools, with one pool per country
* pre-verified project-owned numbers for faster onboarding in embedded signup and setup links
* plan-based access: included on Enterprise, or available as an add-on on Pro, Team, and Platform
Setup links and embedded signup now fall back cleanly:
* if a matching project pool has a ready pre-verified number, Kapso uses it
* if no matching pool exists, or the pool is empty, Kapso falls back to live provisioning through the project's Twilio account
## Features
**Contact notes in inbox**: Add, edit, and delete notes on contacts directly from the conversation sidebar. Notes are attached to the contact and visible across all their conversations.
## Features
**Bulk open/close conversations in inbox**: Select multiple conversations in the inbox and open or close them all at once.
## Features
**Embedded inbox filter query params**: Pre-set conversation filters when embedding the inbox via iframe by passing URL query parameters.
Supported parameters:
* `status=active|ended|all` — conversation status (default: `active`)
* `search=` — pre-fill the search box
* `whatsapp_config_id=|all` — filter by WhatsApp number
* `unread=1` — show only unread conversations
* `handoff=1` — show only conversations waiting for human handoff
```html theme={null}
```
## Features
**Contact thread in inbox**: The inbox now shows the full message history for a contact across all conversations — not just the current one. Select a contact in the inbox to see every message they've sent or received across all their conversations in one place.
## Features
**Unread message tracking in inbox**: Conversations in the inbox now show unread message counts. Mark conversations as read or unread manually, and filter the conversation list to show only conversations with unread messages.
## Bug fixes
**Template URL button parameters**: Fixed an issue where WhatsApp templates using named parameters with URL buttons would not correctly split body and header parameters, causing the template send to fail or use incorrect values.
## Features
**Automatic context compaction for AI agent chats**: Kapso AI agent chats now automatically manage their context window by summarizing older conversation history when it approaches capacity.
When a chat's context fills up, the agent pauses, summarizes the older messages, and continues seamlessly. The chat timeline shows inline **Compacting...** and **Compacted** notices so you can see when this happens.
No configuration needed — compaction runs automatically in the background and is transparent to end users.
## Features
**Assignee filter in inbox**: Filter inbox conversations by assignee directly from the URL.
Use `?assignee=me` to show only your conversations, `?assignee=unassigned` for unassigned ones, or `?assignee=` for a specific team member. The filter syncs with the UI as you change it, and is preserved when navigating between projects.
## Workflows
**Inbound message read behavior**: Control how a workflow marks inbound WhatsApp messages as read before responding.
Set `inbound_message_read_mode` on a workflow to one of:
* `disabled` — don't mark messages as read
* `read_only` — mark as read, no typing indicator
* `read_with_typing` — mark as read and show a typing indicator (default)
Configure from **Workflow Settings → General** in the dashboard, or via the API:
```http theme={null}
PATCH /platform/v1/workflows/{workflow_id}
{
"workflow": {
"inbound_message_read_mode": "read_only"
}
}
```
## Workflows
**Improved template node**: The Send Template node now has a searchable template picker with a live preview.
* **Config selector**: Search your WhatsApp connections by name or phone number.
* **Template selector**: Search templates by name or ID. Disabled until a config is selected.
* **Preview card**: Shows the template's header, body, footer, and expected parameters before you commit to it.
* **Test button**: Open the template test dialog directly from the node form.
## Workflows
**Copy/paste nodes in the flow canvas**: Select one or more nodes and copy/paste them within the canvas (Ctrl+C / Ctrl+V on Windows/Linux, ⌘C / ⌘V on Mac). Start nodes cannot be copied. Edges between copied nodes are preserved; edges to external nodes are dropped.
**Smarter edge routing**: Edges between nodes now automatically route from the most natural handle side based on node positions — bottom-to-top for vertical layouts, right-to-left for horizontal layouts. Nodes with multiple outgoing edges use a consistent exit side.
## Workflows
**Flow-level environment variables**: Environment variables can now be scoped to individual workflows, in addition to project-level variables.
Flow variables use the same `${ENV:VARIABLE_NAME}` syntax and support separate development and production values. Flow-level variables take precedence over project-level variables with the same key.
Set flow variables from **Workflow Settings → Environment variables**.
**Flow promotion**: Promote a workflow's definition to another workflow within the same project. Use this to manage dev→production deployments by maintaining separate workflow versions and promoting changes when ready.
Promote from **Workflow Settings → Promote**.
## Webhooks
**Automatic webhook pausing**: Kapso now automatically pauses webhooks that have persistent high failure rates.
If a webhook exceeds 85% failure rate (with at least 10 failures and 20 total deliveries in a 15-minute window), it is paused automatically. All project members receive an email notification with failure details.
To resume delivery: fix your endpoint, then re-enable the webhook from **Settings → Webhooks**.
See [Automatic pausing](/docs/platform/webhooks/advanced#automatic-pausing) for thresholds and recovery steps.
## Features
**WhatsApp business profile editor**: Edit your WhatsApp business profile directly from the Kapso dashboard.
Navigate to WhatsApp Settings → Profile to update your business information including about text, description, email, address, category (vertical), websites, and profile photo.
Changes are synced directly to your WhatsApp Business Account through Meta's API. Your updated profile is visible to customers who view your business information in WhatsApp.
Profile photo uploads support JPG and PNG formats up to 5MB.
## API changes
**Get message by ID**: Retrieve a single WhatsApp message by its message ID.
New endpoint in the Meta Proxy API:
```bash theme={null}
GET /meta/whatsapp/v24.0/{phone_number_id}/messages/{message_id}
```
Use this to fetch a specific message when you know its ID. The message must belong to the specified phone number. Returns all message fields including Kapso extensions (status, direction, processing state).
## API changes
**Get template by ID**: Fetch a single WhatsApp message template by its ID.
New endpoint in the Meta Proxy API:
```bash theme={null}
GET /meta/whatsapp/v24.0/{business_account_id}/message_templates/{template_id}
```
Use this when you already know the template ID and need its full details. For listing templates or searching by name, use the list endpoint instead.
The `template_id` must be numeric. Returns 400 for invalid format.
## API changes
**Conversation assignment filters**: Filter conversations by assignee in list endpoints.
The Platform API and Meta Proxy API now support filtering conversations by assignment:
```bash theme={null}
# Filter by assigned user
GET /platform/v1/whatsapp/conversations?assigned_user_id=USER_ID
# Filter unassigned conversations
GET /platform/v1/whatsapp/conversations?unassigned=true
```
Available in both APIs:
* Platform API: `/platform/v1/whatsapp/conversations`
* Meta Proxy API: `/meta/whatsapp/v24.0/{phone_number_id}/conversations`
The `assigned_user_id` must be a project member. Cannot combine `assigned_user_id` with `unassigned=true`.
## Inbox
**Jump to node**: Manually move a running workflow execution to a different node.
When viewing a conversation with an active workflow, open the workflow actions dropdown and select "Jump to node". Pick the target node from the list and the execution moves there immediately — status and variables are preserved.
Available from the inbox conversation sidebar and the execution detail panel. Requires the execution to be in `running`, `waiting`, or `handoff` status. Owner or admin role required.
Jump events appear in the workflow execution log with the actor who triggered them.
## Features
**Playbooks**: Pre-built templates for common workflows and AI agents.
Access playbooks from the new "Playbooks" section in your project dashboard. Each playbook includes step-by-step instructions that guide you through building common use cases like:
* Simple AI agents for WhatsApp
* Outbound feedback collection workflows
* Lead capture systems
* And more
Playbooks help you get started quickly by providing tested templates with best practices built in.
## API changes
**Broadcast scheduling**: Schedule WhatsApp broadcasts to send at a future time.
Use the new `/whatsapp/broadcasts/{id}/schedule` endpoint to schedule a broadcast. The broadcast must be in draft status with recipients added.
```json theme={null}
POST /api/platform/v1/whatsapp/broadcasts/{id}/schedule
{
"scheduled_at": "2025-10-12T17:00:00Z"
}
```
* `scheduled_at` must be an ISO-8601 timestamp with timezone
* Must be in the future
* Broadcast status changes to `scheduled`
Cancel scheduled broadcasts with `/whatsapp/broadcasts/{id}/cancel` to return them to draft status.
Recipients can be added or modified while a broadcast is scheduled.
## Webhooks
**WABA-level webhook forwarding**: WhatsApp webhook forwarding now handles business account-level events.
When Meta sends webhook events for your WhatsApp Business Account (WABA) that don't contain a specific phone number ID, Kapso now routes them to the correct WhatsApp configuration based on the business account ID.
This ensures webhook events like business verification updates, phone number name approvals, and other account-level notifications are properly forwarded to your configured webhook endpoints.
If you have multiple phone numbers under the same business account, each receives only the webhook events relevant to that specific phone number, preventing data leakage between configurations.
## Features
**GPT-5.2 reasoning effort control**: The Kapso Agent now supports GPT-5.2 with configurable reasoning effort levels.
Choose from three reasoning effort presets when using GPT-5.2:
* **Medium** - Balanced performance and cost (default)
* **High** - More thorough reasoning for complex tasks
* **XHigh** - Maximum reasoning depth for difficult problems
Select your preferred reasoning level from the model dropdown in the Kapso Agent chat interface. The agent maintains your chosen reasoning effort across follow-up messages in the same conversation.
## Workflows
**Agent pause and resume**: Agent nodes now support the `enter_waiting` built-in tool.
Agents can pause workflow execution mid-conversation using the `enter_waiting` tool. When called, the workflow enters waiting state and resumes when the user sends a new message. The agent retains full conversation context after resuming.
This enables agents to:
* Request additional information without completing the task
* Wait for user input at natural conversation breaks
* Handle multi-step processes where user input is needed between steps
The `enter_waiting` tool is required by default for new workflows. Legacy workflows can enable it as an optional tool.
See [Agent node built-in tools](/docs/flows/step-types/agent-node#built-in-tools) for details.
## Features
**Webhook latency tracking**: Webhook delivery logs now display response times in milliseconds.
View webhook latency metrics in the webhook logs to monitor delivery performance and identify slow endpoints. Response times are tracked for all webhook deliveries including successes, failures, and retries.
## API changes
**Setup link language support**: Setup links now support localization. Set the `language` field when creating or updating a setup link to display the onboarding page in your customer's language.
Supported languages: English (en), Spanish (es), Portuguese (pt), Hindi (hi), Indonesian (id), Arabic (ar).
If not specified, the setup link uses the customer's browser language.
```json theme={null}
{
"setup_link": {
"language": "es",
"provision_phone_number": true
}
}
```
## Workflows
**Wait for response timeouts**: Wait steps can now automatically continue if no user response is received within a specified time.
Configure timeouts from 10 seconds to 7 days. When a timeout fires, the workflow continues forward and sets `{{system.last_resume.reason}}` to `"timeout"` instead of `"user_input"`.
Use a Decide node after the wait step to branch based on whether the user responded or the wait timed out:
```javascript theme={null}
// In decide condition
system.last_resume.reason === "timeout"
```
If the user responds before the timeout, the timeout is automatically cancelled.
See [Wait for response node](/docs/flows/step-types/wait-for-response-node) for details.
## Features
**Cost tracking for workflows**: Workflow logs now display total AI token costs with advanced filtering.
The workflow logs view now includes:
* Total cost summaries for filtered results (both workflow executions and token usage logs)
* Filter token logs by date range, AI model, resource type, and resource ID
* Real-time cost calculations as you apply filters
This helps you monitor AI spending across workflows and identify cost patterns.
## Project pages
Build simple React pages inside Kapso — use them as dashboards or embed them in the inbox sidebar.
Pages are written in TSX and compiled on save into a sandboxed iframe. Call your deployed functions via `kapso.invokeFunction()` and access conversation context with `kapso.getContext()` when mounted in the inbox.
The easiest way to build a page is with the Kapso Agent — just ask it to create one and describe what you want.
See [Project pages docs](/docs/platform/project-pages).
## Bug fixes
**CTA URL button variable substitution**: Fixed an issue where variables in CTA URL buttons were not being substituted during workflow execution.
Interactive messages with `cta_url` action type now properly substitute variables in both the display text and URL fields. This allows dynamic button text and URLs like:
```json theme={null}
{
"display_text": "View order #{{vars.order_id}}",
"url": "https://example.com/orders/{{vars.order_id}}?token={{vars.access_token}}"
}
```
Previously, these variables would appear as literal text instead of being replaced with actual values.
## Kapso agent
**Enhanced sandbox tools**: The Kapso agent now has more powerful tools for working with files in the sandbox environment.
New capabilities:
* **Read multiple files**: Read multiple files at once (up to 20 files)
* **Write files**: Create new files or overwrite existing ones with automatic directory creation
* **List directories**: Explore directory contents recursively with configurable depth
* **Track plans**: Visual task tracking shows progress as the assistant works through multi-step tasks
These tools enable the agent to work more efficiently when building workflows and exploring agent skills, with improved UI showing file contents and task progress inline.
## API reference
Expanded Platform API documentation with the following endpoints:
**WhatsApp Flows** - Create, manage, and publish WhatsApp Flows. Includes version management, data endpoint configuration, encryption setup, and function logs.
**Integrations** - Manage Pipedream integrations programmatically. List available apps and actions, create integrations, configure action properties, and generate connect tokens.
**Conversations & Messages** - List and retrieve WhatsApp conversations and messages.
**Project Webhooks** - Full CRUD for project-level webhooks, plus a test endpoint to verify delivery.
**Logs** - Query API logs and webhook delivery history.
**Provider Models** - List available AI model providers and their models.
**Workflow variables** - New endpoint to retrieve available variables for a workflow, including fixed system variables and discovered user variables from execution history.
**Function invocations** - List invocation history for serverless functions.
## Workflows
**External input tagging for agent nodes**: Agent nodes now automatically distinguish between direct user messages and external inputs from APIs or integrations.
When workflows are resumed via the Platform API or receive input from sources like Slack replies, agents now receive these inputs wrapped in `` tags. This helps agents:
* Understand the input source (internal team vs. end user)
* Adapt their tone and responses appropriately
* Make better decisions about what to communicate to users
External inputs are automatically created when:
* Resuming workflows via Platform API with payloads
* Receiving Slack integration responses
* Triggering workflows via API with initial data
This improves agent behavior in multi-channel workflows where internal teams collaborate with AI agents before responding to customers.
## Workflows
**Flow token variable substitution**: The `flow_token` parameter in send interactive flow nodes now supports variable interpolation.
Use dynamic flow tokens to correlate flow responses with specific workflow instances or business entities:
```json theme={null}
{
"flow_token": "order_{{vars.order_id}}"
}
```
This allows you to track which workflow execution triggered each flow response, making it easier to handle multiple concurrent flows for different users or orders.
## API changes
**List project users**: New endpoint to retrieve all users who are members of your project.
Use `GET /platform/v1/users` to get a paginated list of project members with their roles and email addresses. Returns user IDs that can be used with conversation assignments and other user-related operations.
```bash theme={null}
curl "https://api.kapso.ai/platform/v1/users" \
-H "X-API-Key: YOUR_API_KEY"
```
Each user includes:
* `id` - User project membership ID
* `user_id` - User account ID (use this for assignments)
* `email` - User email address
* `name` - User display name
* `role` - Either `owner` or `member`
**Conversation assignments**: New endpoints to assign conversations to team members.
Use `POST /whatsapp/conversations/{id}/assignments` to assign a conversation to a user. Only one active assignment per conversation is allowed. The assigned user must be a member of your project.
```bash theme={null}
curl -X POST "https://api.kapso.ai/platform/v1/whatsapp/conversations/{conversation_id}/assignments" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assignment": {
"user_id": "f1e2d3c4-b5a6-9870-fedc-ba0987654321",
"notes": "Customer needs help with integration"
}
}'
```
Update assignments with `PATCH /whatsapp/conversations/{id}/assignments/{assignment_id}` to change notes, reassign to another user, or deactivate (unassign) by setting `active: false`.
List all assignments for a conversation with `GET /whatsapp/conversations/{id}/assignments` or retrieve a specific assignment with `GET /whatsapp/conversations/{id}/assignments/{assignment_id}`.
## Webhooks
**Phone number deleted event**: New webhook event `whatsapp.phone_number.deleted` fires when a WhatsApp phone number is removed from your project.
```json theme={null}
{
"phone_number_id": "123456789012345",
"project": {
"id": "990e8400-e29b-41d4-a716-446655440004"
},
"customer": {
"id": "880e8400-e29b-41d4-a716-446655440003"
}
}
```
Use this event to clean up resources or update external systems when phone numbers are disconnected. The event triggers at the start of the teardown process.
## Inbox
**Standalone inbox domain**: The inbox is now also available at `inbox.kapso.ai`, separate from the main app. Invite team members to handle conversations without giving them access to project settings, workflows, or API keys.
**Embedded inbox**: Embed the inbox into your own application via iframe.
Create access tokens in **Project → Inbox Embeds** to generate embeddable URLs. Each token has a scope that controls visible conversations:
* `project` - All conversations
* `whatsapp_config` - Conversations for a specific WhatsApp number
* `customer` - Conversations for a specific customer
Security features:
* **Allowed origins** - Whitelist domains that can embed (supports wildcards)
* **Expiration** - Optional token expiration date
```html theme={null}
```
Real-time updates via WebSocket included. See [Embedded inbox docs](/docs/platform/inbox/embedded).
## API changes
**Message ordering enforcement**: The send message endpoint now prevents concurrent messages to the same recipient.
When sending a message while another message is already being processed for the same recipient, you'll receive a `409 Conflict` error. Implement retry logic with a short delay (1-2 seconds) to handle this:
```json theme={null}
{
"error": "Another message is already in-flight for this conversation. Please retry shortly."
}
```
This ensures messages are sent in order and prevents race conditions when multiple systems send messages simultaneously.
## API changes
**Update WhatsApp templates**: New PUT endpoint to update existing message templates.
Use `PUT /{business_account_id}/message_templates?hsm_id={template_id}` to modify template components, text, or properties. Requires the template's `hsm_id` identifier.
```bash theme={null}
curl -X PUT "https://api.kapso.io/api/meta/v21.0/123456/message_templates?hsm_id=1627019861106475" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "updated_template",
"components": [
{"type": "HEADER", "format": "TEXT", "text": "Updated Header"},
{"type": "BODY", "text": "Updated body text"}
],
"language": "en_US",
"category": "MARKETING"
}'
```
After a successful update, templates are automatically synced from Meta to keep Kapso's cache current.
## API changes
**Meta webhook forwarding**: New webhook type that forwards raw Meta payloads alongside existing event-based webhooks.
Create a webhook with `kind: "meta"` to receive the exact payload Meta sends, without event filtering or buffering. Useful when you need direct access to Meta's webhook structure or want to process all events without Kapso's transformations.
```json theme={null}
{
"whatsapp_webhook": {
"kind": "meta",
"url": "https://your-app.com/webhooks/meta",
"active": true
}
}
```
Meta webhooks include an `X-Idempotency-Key` header (SHA256 hash of the payload) for deduplication. Only one meta webhook allowed per phone number.
The default `kind: "kapso"` continues to work as before with event subscriptions, buffering, and Kapso payload format.
## Inbox
**Workflow status in conversation list**: The inbox conversation list now shows workflow execution status.
When a workflow is running for a conversation, you'll see its current state: Running, Waiting, Handoff, or Failed. This helps you quickly identify conversations where workflows are active or need attention.
## Workflows
**App integration tools**: AI agent steps can now call pre-configured app integrations as tools.
Connect to HubSpot, Slack, Google Sheets, Notion, Airtable, and 2,700+ other apps via Pipedream. Attach integrations to agent steps and let the agent invoke them during conversations.
Each tool has:
* **Name**: Tool identifier the agent calls
* **Description**: Tells the agent when to use this tool
* **App integration**: Select a pre-configured integration
The agent provides runtime values for fields marked as "Passed by agent" in the integration config. Pre-configured values are sent automatically.
## Workflows
**AI agent function tools**: AI agent steps can now call your custom functions as tools during execution.
When configuring an AI agent step in the workflow builder, you can now attach function tools that the agent can invoke when needed. The agent receives:
* Function name and description
* Input schema (JSON Schema)
* Full workflow execution context
* Recent flow events and WhatsApp conversation history (if applicable)
Your function returns data that can update workflow variables (`vars`) for use in subsequent steps.
This enables agents to:
* Look up data from external APIs
* Perform calculations or transformations
* Query databases or search systems
* Integrate with any external service
**Ask about file tool**: New built-in tool for analyzing files.
Agents can now use `ask_about_file` to answer questions about PDFs, images, and Office documents (.docx, .xlsx, .pptx). Get file URLs from WhatsApp messages via `get_whatsapp_context`, then call the tool with your question.
Limits: 30MB max, legacy formats (.doc/.xls/.ppt) need conversion to modern format.
## Inbox
**Message replies and reactions**: Inbox now displays emoji reactions and reply context for WhatsApp messages.
When viewing conversation threads, you'll now see:
* Emoji reactions on individual messages
* Reply indicators showing which message is being replied to
* Sender name and preview text for replied-to messages
You can also send replies with context from the inbox by replying to specific messages.
## Kapso Agent
**API mode with webhook management**: Kapso Agent can now configure and manage webhooks through chat.
The API mode (formerly "debugging") now includes:
* Create, update, and delete webhooks through natural language
* Test webhook deliveries and view recent delivery logs
* Configure project-level and phone-number-level webhooks
* Set up buffering, custom headers, and retry policies
Ask the agent to "create a webhook for new messages" or "list my webhooks" from any page. The agent will guide you through configuration and validate your setup.
Mobile improvements:
* Floating action button for quick agent access on mobile
* Full-screen mobile sheet interface
* Improved responsiveness across all screen sizes
## API changes
**Location request interactive message**: New interactive message type to request user's location.
Send `location_request_message` interactive type to display a "Send Location" button. Users can share their current location with one tap.
```json theme={null}
{
"type": "interactive",
"interactive": {
"type": "location_request_message",
"body": {
"text": "Please share your location"
},
"action": {
"name": "send_location"
}
}
}
```
Now available in:
* WhatsApp API (REST and TypeScript SDK)
* Workflow builder (Send Interactive step)
See the [location request guide](/docs/whatsapp/send-messages/location-request) for details.
## Features
**WhatsApp Ads tracking (CTWA)**: New tracking and analytics for Click-to-WhatsApp campaigns.
When users start conversations through Meta ads or click-to-WhatsApp buttons, Kapso now automatically captures referral data including:
* Ad headline, body, and media
* Campaign source and click ID (ctwa\_clid)
* Custom reference parameters
View all referrals in the new "Ads (CTWA)" section under your WhatsApp project. Filter by date range and export to CSV for deeper analysis.
Conversations with referral data now show a "CTWA" badge in the inbox for quick identification.
## API changes
**WhatsApp AUTHENTICATION templates**: Fixed and improved support for OTP authentication templates.
Changes:
* **ONE\_TAP autofill**: Now uses `supported_apps` array format (replaces deprecated `package_name`/`signature_hash` fields)
* **ZERO\_TAP**: Added support for no-button OTP auto-read
* **Button text**: OTP buttons no longer accept `text` field (Meta generates button text)
* **Validation**: Added proper validation for AUTHENTICATION template structure
```json theme={null}
{
"type": "OTP",
"otp_type": "ONE_TAP",
"supported_apps": [
{
"package_name": "com.example.app",
"signature_hash": "K8a%2FAINcGX7"
}
]
}
```
See the [Authentication templates guide](/docs/whatsapp/templates/authentication) for complete documentation.
## Kapso Agent
**Global agent with mode switching**: Kapso Agent is now available across your entire dashboard and can switch between specialized modes.
Available modes:
* `auto` - General assistant with documentation access (default)
* `debugging` - Health checks, error analysis, message troubleshooting
* `whatsapp_templates` - Template creation, submission to Meta, sending messages
* `whatsapp_flow` - WhatsApp Flows JSON editing, data endpoints
The agent automatically detects your current page and adjusts its context. Use the mode selector in the chat sidebar or let the agent switch modes based on your request.
## Kapso Agent
**Debug mode**: Kapso Agent can now help you diagnose WhatsApp integration issues directly from the dashboard.
Available debugging tools:
* `get_project_overview` - Health snapshot with connected numbers, plan status, 24h activity
* `check_whatsapp_health` - Token validity, messaging health, webhook status
* `get_project_errors` - Recent errors from message delivery, API calls, webhooks
* `get_api_logs` - External API call logs with status codes and response times
* `get_webhook_deliveries` - Webhook delivery attempts to your endpoints
* `get_recent_messages` - Recent WhatsApp messages with status
* `get_message_details` - Full message lifecycle including delivery errors
* `lookup_conversation` - Find conversations by phone number
Access debug mode from the Logs page or Messages page in your project dashboard.
## API changes
**Update workflow execution status**: New PATCH endpoint to manually control workflow lifecycle.
```bash theme={null}
PATCH /workflow_executions/{execution_id}
```
```json theme={null}
{
"workflow_execution": {
"status": "ended"
}
}
```
Allowed transitions: `ended`, `handoff`, `waiting`. Use this to end workflows from external triggers, transfer to human agents, or pause executions programmatically.
## Workflows
**Observer mode chat**: Agent steps now support interactive chat when running in observer mode (outbound messages disabled).
New `observer_prompt_mode` setting:
* `interactive_chat` (default) - Chat with the agent via the Workflow Chat sidebar in the inbox
* `analysis_only` - Agent runs non-interactively, no chat interface
Use interactive mode for workflows that need human review or operator input. The Workflow Chat sidebar appears in the inbox when viewing conversations with active observer-mode executions.
## Workflows
**Send data to WhatsApp Flows**: The send interactive step now supports passing dynamic data to WhatsApp Flows via `flow_action_payload`.
```json theme={null}
{
"node_type": "send_interactive",
"config": {
"interactive_type": "flow",
"body_text": "Complete checkout",
"flow_id": "123456789012345",
"flow_cta": "Continue",
"flow_action": "navigate",
"flow_action_payload": {
"screen": "CHECKOUT",
"data": {
"phone_number": "{{context.phone_number}}",
"cart_total": "{{vars.total}}"
}
}
}
}
```
Variables in `flow_action_payload` are automatically substituted from the workflow context. Useful for pre-filling forms, passing user data, or customizing the flow experience based on conversation state.
## API changes
**Resume workflow with variables**: The resume endpoint now accepts optional `variables` parameter to update execution context when resuming a waiting workflow.
```json theme={null}
POST /workflow_executions/{id}/resume
{
"message": {
"data": "yes, proceed"
},
"variables": {
"estado": "retomado",
"user_choice": "confirmed"
}
}
```
Variables are merged into the execution context's `vars` section. Existing variables with the same key are overwritten. Useful for capturing user responses or updating workflow state when resuming from a wait step.
## Workflows
**Call workflow step**: New step type for executing workflows as subroutines.
```json theme={null}
{
"node_type": "call",
"config": {
"workflow_id": "abc123",
"save_error_to": "validation_error"
}
}
```
Parent workflow pauses while child executes. Variables automatically merge back on completion. Includes recursion protection (max depth 10) and cycle detection. Use for reusable validation, multi-step processes, and conditional sub-workflows.
## API changes
**Template sync pagination**: Fixed template sync to retrieve all templates from Meta. Previously, sync would only fetch the first 100 templates when you had more than 100 approved templates in your WhatsApp Business Account.
If you have more than 100 templates, re-run sync to import all templates:
```bash theme={null}
POST /whatsapp_templates/sync
```
This fix ensures complete template synchronization regardless of template count.
## Workflows
**Template parameters**: Send Template nodes now support Meta's native components format for template parameters.
```json theme={null}
{
"parameters": [
{
"type": "BODY",
"parameters": [
{ "type": "text", "text": "{{user_name}}" },
{ "type": "text", "text": "{{order_id}}" }
]
}
]
}
```
Use this format for multi-component templates (header, body, buttons) and named parameters. Legacy array format still supported.
## Webhooks
**Status history**: `message.kapso.statuses` now includes ordered history of raw Meta status events.
```json theme={null}
{
"message": {
"kapso": {
"status": "failed",
"statuses": [
{ "status": "sent", "timestamp": "1700000000", ... },
{ "status": "delivered", "timestamp": "1700000005", ... },
{ "status": "failed", "timestamp": "1700000010", "errors": [...] }
]
}
}
}
```
Track full message lifecycle and understand failure causes. Array only appears when status events exist.
## API changes
**Workflow execution ID**: `POST /workflows/{id}/executions` now returns an `id` field in addition to `tracking_id`. Use the execution ID to retrieve full execution details or resume waiting executions.
```json theme={null}
{
"data": {
"message": "Workflow execution initiated",
"workflow_id": "uuid",
"id": "uuid",
"tracking_id": "uuid"
}
}
```
The `id` field is the execution identifier you can use with:
* `GET /workflow_executions/{id}` - Retrieve full execution details
* `POST /workflow_executions/{id}/resume` - Resume waiting executions
## WhatsApp Flows
Build interactive forms that run natively inside WhatsApp. Users tap through screens, fill out fields, and submit data - all without leaving the chat.
* **Static flows** - Define all content in Flow JSON, no server required
* **Dynamic flows** - Fetch data at runtime using Kapso Functions as your data endpoint
* **Automatic encryption** - Kapso handles Meta's encryption requirements
* **Response collection** - Receive completions via webhooks or view in dashboard
Use cases: lead capture, appointment booking, surveys, order forms, customer intake.
Get started with WhatsApp Flows
## Inbox
**Browser notifications** - Enable desktop notifications to get alerted when new messages arrive.
## Workflows
**Execution webhooks** - Get notified when workflow executions require human intervention or fail.
New project webhook events:
* `workflow.execution.handoff` - Workflow handed off to human agent
* `workflow.execution.failed` - Workflow execution failed
Configure in **Project → Webhooks → Project webhooks**. See [webhook event types](/docs/platform/webhooks/event-types#project-webhook-events) for payload structures.
## API changes
**New endpoint**: `GET /whatsapp/conversations/{id}/flow_executions` - List workflow executions for a WhatsApp conversation. Filter by `status`.
```json theme={null}
{
"data": [
{
"id": "uuid",
"status": "running",
"tracking_id": "uuid",
"whatsapp_conversation_id": "uuid",
"started_at": "2025-12-05T17:20:00Z",
"last_event_at": "2025-12-05T17:25:00Z",
"ended_at": null,
"workflow": { "id": "uuid", "name": "Order Support", "status": "active" },
"current_step": { "identifier": "wait_response", "stepable_type": "FlowWaitStep" }
}
]
}
```
## Workflows
Agent steps: MCP server URLs and headers now support variable substitution:
```
https://api.example.com/mcp/{{system.customer.external_customer_id}}
Authorization: Bearer ${ENV:MCP_API_KEY}
```
Supported: `{{vars.*}}`, `{{system.*}}`, `{{context.*}}`, `${ENV:KEY}`
## Workflows
**New `system.customer` context** - WhatsApp-triggered workflows now automatically include customer data when the WhatsApp config is linked to a Customer:
```
{{system.customer.id}} # Customer UUID
{{system.customer.external_customer_id}} # Your external ID
{{system.customer.name}} # Customer name
```
## Webhooks
**New fields in `message.kapso`**:
* `content` - LLM-ready text representation of any message type (includes caption, file info, and transcript for audio)
* `transcript` - Speech-to-text transcription for audio messages with shape `{ text: "..." }`
## API changes
Workflow execution responses now include `whatsapp_conversation_id` to link executions to their WhatsApp conversation.
```json theme={null}
{
"id": "uuid",
"status": "running|waiting|completed|failed|stopped|handoff",
"tracking_id": "custom-tracking-id",
"whatsapp_conversation_id": "uuid",
"started_at": "2025-11-27T10:00:00Z",
"last_event_at": "2025-11-27T10:05:00Z",
"ended_at": null,
"workflow": {
"id": "uuid",
"name": "My Workflow"
},
"current_step": {
"id": "uuid",
"stepable_type": "FlowAgentStep"
}
}
```
Available in list, show, and resume endpoints. You can also filter executions by `whatsapp_conversation_id` in the list endpoint.
## Workflows
**New features**
* Duplicate flows - Clone existing flows via the canvas UI
* Wait step `save_response_to` - Save user response to a custom variable
* Failure email notifications - Automatic alerts when flow executions fail
**Fixes**
* Handle non-JSON webhook bodies in flow webhooks
* Fix edge case where AI returns strings with backslash characters
## Functions
Function logs - Debug your serverless functions with built-in logging. View logs filtered by invocation, time range, and request ID.
## Billing & projects
* Multiple projects - Create up to 6 projects
* Free digital phone number - Free plan now includes a digital phone number
## UI/UX
* Mobile inbox - Improved mobile experience
* Triggers UI - Improved design for workflow triggers