> ## 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 **Slack**: Any member of a workspace can now connect a channel to a project the workspace is already connected to, without a Kapso account. The channel runs as the owner or admin who connected the workspace, or as the person clicking when their own Kapso account manages the project. When the workspace is connected to several projects, the connect prompt lists one button per project. Members of other workspaces in a Slack Connect channel cannot connect channels. See [Slack integration](/docs/kapso-agent/slack). **Kapso Agent**: The project agent now has its own docs. It builds workflows, debugs APIs and logs, configures the inbox, manages templates and WhatsApp Flows, and investigates findings from the project home, the side panel, the inbox, Slack, or the API. See [Kapso Agent](/docs/kapso-agent/overview). **Custom modes**: Create modes with your own instructions, model, capabilities, and resources under **Kapso Agent → Modes**. Assign MCP connections, GitHub repositories, and encrypted environment variables, and give a mode a sandbox with read-only or command execution. See [Modes](/docs/kapso-agent/modes) and [Resources](/docs/kapso-agent/resources). **Slack**: Add the Kapso Slack app and mention `@Kapso` in a channel or message it directly. Each thread is a session, approvals are handled with cards in the thread, and **Integrations → Slack** sets the default mode, tool approvals, model, and reasoning effort. See [Slack integration](/docs/kapso-agent/slack). ## API changes **Kapso Agent API**: Trigger runs with `POST /platform/v1/kapso-agent/runs`, poll them, pause, resume, cancel, and approve or reject tool calls. List modes and sessions, and subscribe project webhooks to `kapso_agent.run.approval_required`, `kapso_agent.run.completed`, `kapso_agent.run.failed`, and `kapso_agent.run.cancelled`. See [Agent API](/docs/kapso-agent/api). ## Features **Duplicate a broadcast**: Copy an existing broadcast from the broadcast list or its details page. The duplicate keeps the template, template parameters, agent, and every recipient with their personalized values, and starts as a new draft with delivery state reset. Large lists are copied in the background. The copy reports a new `copying` status until every recipient has been written, and cannot be edited, sent, or scheduled until it becomes `draft` — or `failed`, if the copy could not be completed. The source broadcast is locked the same way until its copy finishes. ```json theme={null} { "data": { "id": "5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c", "name": "July promo (Copy)", "status": "copying" } } ``` See [Duplicate a broadcast](/docs/platform/broadcasts/overview#duplicate-a-broadcast). ## API changes **Findings Platform API**: [Findings](/docs/platform/findings) are now reachable from the Platform API with a project-scoped `X-API-Key`. List findings, read one with its investigation, pull the evidence behind it, queue an investigation, dismiss it, or mark it as addressed. ```bash theme={null} curl 'https://api.kapso.ai/platform/v1/findings?limit=20' \ -H 'X-API-Key: ' ``` Listing is cursor paginated (`limit` is 1-25, defaults to 20) and keeps grouped findings on the same page. Starting an investigation returns `202` and runs asynchronously. See [Findings from the API](/docs/platform/findings#from-the-api). ## Features **Contact property filters in the inbox**: Filter the conversation list by the custom properties stored on a contact. Add up to 3 filters at once, each matching a property that equals a value, has any value, or is empty. Suggested values are offered for properties already in use. Filters are kept in the URL under `contact_properties`, so a filtered view can be bookmarked or shared, and the same parameter works on the [embedded inbox](/docs/platform/inbox/embedded#filters) URL. See [Inbox filters](/docs/platform/inbox/overview#contact-properties). ## Features **Findings**: Kapso now reviews your completed WhatsApp conversations with AI and surfaces the problems that keep happening. A managed evaluator turns each ended conversation into structured events — user frustration, unresolved requests, wrong agent answers, positive outcomes, prompt injection attempts — and Kapso groups the recurring ones into findings. Open a finding to see the conversations behind it, then run the Kapso Agent Investigator. It compares affected and successful conversations, follows them into workflow executions, searches your logs, and reads any repository connected to the project. It comes back with the cause, the confidence behind it, up to three suggested fixes with linked evidence, and what it could not verify. The investigation is read-only. Apply a fix and mark the finding as addressed: Kapso monitors new conversations and either resolves the finding or reopens it if the signal comes back. Turn it on from **Findings** in the sidebar. Setup creates the evaluator workflow and the investigator agent, and can review up to 50 conversations from the last 7 days so you get findings right away. Findings works on your own project events too, not just the default ones. It requires project events on your plan, and both components use AI credits when they run. Agents can reach the same data through the new `findings` MCP tool: `list`, `get`, `read_evidence`, `start_investigation`, `dismiss`, and `mark_addressed`. See [Findings](/docs/platform/findings). ## Features **Message retention**: Paid projects can now delete WhatsApp history on a schedule. Pick a window in **Project settings > Message retention** — 30 days, 90 days, 6 months, 12 months, or a custom number of days — and Kapso permanently deletes ended conversations older than that window, along with their messages, media, and message logs. Messages that never belonged to a conversation are deleted on the same window. Contacts, calls and broadcast records are kept. Project events recorded against a deleted conversation go with it; the rest follow the retention window from your plan. Before a shorter window is saved, Kapso shows what it would delete right now — conversations, messages and media — and asks you to type the project name. The change then waits 48 hours before the first deletion, and project owners get an email when it is scheduled. Widening the window, or going back to keeping everything, applies immediately. Free projects keep everything, as before. Downgrading to a plan without retention suspends the policy instead of dropping it: your settings are kept and resume automatically if you upgrade again. See [WhatsApp data](/docs/platform/whatsapp-data#retention). ## Webhooks **WhatsApp account enforcement events**: Project webhooks can subscribe to four new events reporting Meta enforcement against a WhatsApp Business Account: `whatsapp.account.disabled`, `whatsapp.account.restricted`, `whatsapp.account.reinstated` and `whatsapp.account.violation`. They require payload version `v2` and are delivered once per project and WABA, listing every affected number. ```json theme={null} { "event": "whatsapp.account.restricted", "business_account_id": "102290129340398", "phone_numbers": [ { "id": "123456789012345", "display_phone_number": "+1 555 010 1234" } ], "restrictions": [ { "type": "RESTRICTED_BIZ_INITIATED_MESSAGING", "expires_at": "2026-09-14T12:00:00Z" } ] } ``` See [Project webhooks](/docs/platform/webhooks/project-webhooks). ## Features **Account enforcement status in the dashboard**: WhatsApp numbers now show when Meta has banned, restricted, or flagged a violation on their business account, and project members receive an email when an enforcement is detected. **WhatsApp marketing opt-outs**: When a contact taps *Stop promotions* in WhatsApp, Kapso now records the preference per number and refuses marketing template sends to that contact on that number with error code `marketing_preference_stopped`. Refused sends are never charged. Utility and authentication templates and free-form session messages are unaffected, and only the contact can opt back in, inside WhatsApp. Broadcasts skip stopped contacts instead of failing them: recipients get the new `suppressed` status, broadcasts expose `suppressed_count`, and suppressed recipients are excluded from delivery and failure rates. ## API changes **Marketing preference endpoints**: Read a contact's preference with `GET /whatsapp/contacts/{identifier}/marketing_preferences` (one entry per number) or `GET /whatsapp/contacts/{identifier}/marketing_preferences/{phone_number_id}`. Read-only — there is no API to set or clear a preference. **New webhook event**: Subscribe to `whatsapp.contact.marketing_preference_changed` to mirror opt-outs and resumes into your own system. It fires only on real transitions and carries a monotonic `sequence` for ordering. See [Marketing opt-outs](/docs/whatsapp/templates/marketing-opt-outs). ## Features **Connect repositories with a GitHub App**: Projects can now connect the Kapso GitHub App instead of pasting a Personal Access Token. Connected repositories are available to Kapso Agent modes and AI Agent sandbox nodes. GitHub controls repository access, while Personal Access Tokens and public repositories continue to work. Agent node repository resources accept a new `auth_type` of `pat`, `github_app`, or `public`. With `github_app`, pass `github_app_installation_id` for an active project connection that grants access to the repository. Definition responses now include `auth_type`, `has_github_app`, and `github_app_installation_id`. ```json theme={null} { "resource_type": "github_repository", "repo_url": "https://github.com/org/repo", "branch": "main", "auth_type": "github_app", "github_app_installation_id": "0f2f7b1e-2a4c-4a2f-9d6f-7c8f1b2a3c4d" } ``` Duplicating or importing workflows across projects does not carry App connections; those resources return `imported_missing_github_app: true` until reconfigured. See [Agent node](/docs/flows/step-types/agent-node). ## API changes **Cached WhatsApp phone number health checks**: `GET /whatsapp/phone_numbers/{phone_number_id}/health` now serves results from a 3 minute cache instead of calling Meta on every request. Read `timestamp` to see when the underlying check ran. The cache is invalidated early when the number's configuration changes. If another health check for the same number is already in flight and does not finish within 15 seconds, the endpoint responds with `status: error` and a message asking you to retry. ```json theme={null} { "status": "error", "error": "Another health check is already in progress. Try again shortly.", "timestamp": "2026-08-19T14:25:30Z" } ``` ## Features **Kapso credits for non-USD WhatsApp accounts**: Paying Meta message fees with Kapso credits is no longer limited to WhatsApp Business Accounts billed in USD. Kapso enables non-USD account currencies one at a time; eligible accounts are charged Meta's published USD price plus an FX margin (5% at launch), shown on the WhatsApp billing card. Project balances and charges stay in USD. See [Meta message billing](/docs/whatsapp/meta-message-billing). ## Features **Reclaim a sandbox number**: A phone number already active in another sandbox session can now be moved. Creating a session for it returns `pending_activation`; sending the activation code from WhatsApp activates the new session, marks the previous one `superseded`, and closes its open sandbox conversations. Creation no longer fails with "already has an active sandbox session". Sandbox session `status` can now be `superseded` in addition to `pending_activation` and `active`. Activation codes expire 15 minutes after the session is created, and `status` is no longer accepted when creating a session through the API — new sessions always start as `pending_activation`. See [Use Kapso Sandbox](/docs/how-to/whatsapp/use-sandbox-for-testing). ## Webhooks **Phone number connection lifecycle events**: Project webhooks can now subscribe to `whatsapp.phone_number.offboarded`, `whatsapp.phone_number.disconnected`, and `whatsapp.phone_number.reconnected` to react when Meta offboards a number, removes partner access, or restores the Cloud API connection. Requires payload version `v2`. ```json theme={null} { "event": "whatsapp.phone_number.disconnected", "phone_number_id": "123456789012345", "connection_type": "dedicated", "source": { "provider": "meta", "event": "PARTNER_REMOVED", "business_account_id": "102290129340398" }, "disconnection": { "reason": "primary_inactivity", "initiated_by": "system" } } ``` See [Project webhooks](/docs/platform/webhooks/project-webhooks). ## Features **AI prompts in quick replies**: Quick reply bodies can now contain `{{prompt: "..."}}` sections that an AI fills in when the reply is inserted into the composer. ```text theme={null} Your refund ID is {{prompt: "Find the refund ID in this conversation"}}. ``` Prompts are answered from the recent conversation history, read-only inbox lookups, and public web search for current public facts. Generated text is written to fit the surrounding sentence, and text outside the prompt is left unchanged. Sending is blocked while generation is running. Up to 10 prompts per reply, 2,000 characters each. Resolution consumes AI credits. Works in both the main and [embedded inbox](/docs/platform/inbox/embedded). See [Quick replies](/docs/platform/inbox/messaging#quick-replies). ## API changes **Prompt cache TTL on agent nodes**: Agent nodes accept a `prompt_cache_ttl` of `5m` (default) or `1h`. `1h` keeps reusable prompt content cached longer at a higher cache-write cost, and is only accepted for Anthropic models, including Anthropic models served through OpenRouter. `GET /platform/v1/provider_models` now returns `supported_prompt_cache_ttls` and `default_prompt_cache_ttl` so you can check what a model accepts before setting it. The setting is also available on the agent node form in the flow editor. ```json theme={null} { "node_type": "agent", "config": { "provider_model_id": "uuid", "prompt_cache_ttl": "1h" } } ``` ## Bug fixes **Broadcast media headers**: For broadcasts using a template with a media header, the header URL is no longer substituted into the first positional body parameter of the message stored in the Inbox. The header media and the body parameters are now rendered separately, matching what Meta actually delivers. This applies to broadcasts sent from now on; messages already stored for completed broadcasts are unchanged. ## API changes **Extended thinking metadata on provider models**: `GET /platform/v1/provider_models` now returns two additive fields: * `thinking_mode` — `disabled`, `manual`, `adaptive`, or `always_adaptive` * `supports_custom_sampling` — whether the model accepts sampling parameters such as `temperature` Models with `adaptive` thinking size their own thinking budget from the reasoning effort you pass. Sampling parameters are ignored while extended thinking is active, so check `supports_custom_sampling` before relying on `temperature`. ```json theme={null} { "id": "0f8f...", "name": "claude-opus-5", "provider": "Anthropic", "reasoning_model": true, "thinking_mode": "adaptive", "supports_custom_sampling": false, "supported_reasoning_efforts": ["low", "medium", "high", "xhigh", "max"], "default_reasoning_effort": "high", "api_surface": "provider_default" } ``` ## Bug fixes **BSUID identity changes**: Meta delivers business-scoped user ID rotations as `user_changed_number` and `user_changed_user_id` system messages on the `messages` field, with flat `previous_user_id` / `previous_parent_user_id` values. Kapso now reconciles both onto the existing contact, conversation, and sandbox session before any other processing, and emits `whatsapp.contact.identity_changed`. These control messages no longer reach `whatsapp.message.received`, workflows, or agents. See [Business-scoped user IDs](/docs/whatsapp/business-scoped-user-ids). ```json theme={null} { "type": "system", "system": { "type": "user_changed_number", "wa_id": "12195555358", "user_id": "US.99225512874400319256", "previous_user_id": "US.13491208655302741918" } } ``` ## Bug fixes **Static phone number buttons**: Templates with a `PHONE_NUMBER` button no longer include a `button` component for it in the send-time payload. The button is defined by the approved template, so sending a component for it could be rejected by Meta. Other buttons keep their template position as `index`. See [Buttons](/docs/whatsapp/templates/buttons). ## API changes **Start workflows by BSUID**: `POST /platform/v1/workflows/{id}/executions` now accepts `recipient` (a business-scoped user ID or parent BSUID) instead of `phone_number`. One of the two is required; if both are sent, the phone number routes the conversation and the BSUID is kept as the participant identity. The new [Start and resume via API](/docs/workflows/start-and-resume-via-api) page covers both execution endpoints end to end. ```json theme={null} { "workflow_execution": { "recipient": "US.13491208655302741918", "phone_number_id": "15551234567" } } ``` ## Features **Quick replies in the inbox**: Save reusable message templates and insert them in the composer by typing `/` followed by a shortcut. Replies can be personal or shared with the project, support `{{contact.first_name}}`, `{{contact.name}}`, and `{{contact.phone_number}}` variables, and can be duplicated or archived from the new **Quick replies** page in the inbox sidebar. The `/` picker also works in the embedded inbox. See [Messaging](/docs/platform/inbox/messaging). ## API changes **Resume returns 409 on contention**: `POST /platform/v1/workflow_executions/{id}/resume` now responds `409 Conflict` immediately when the execution is already being processed by another request, instead of blocking until the other request finishes. Retry after a short delay. ```json theme={null} { "error": "Flow execution 0f2b... is already locked: could not obtain lock on row" } ``` ## API changes **Send Pix order messages**: The WhatsApp API now accepts interactive `order_details` messages with the `review_and_pay` action and `order_status` messages with the `review_order` action. Action parameters, including `pix_dynamic_code` payment settings, are forwarded to Meta unchanged. ```json theme={null} { "messaging_product": "whatsapp", "to": "5511999999999", "type": "interactive", "interactive": { "type": "order_details", "body": { "text": "Order details" }, "action": { "name": "review_and_pay", "parameters": { "reference_id": "pix-order-123", "payment_type": "br", "currency": "BRL", "total_amount": { "value": 1000, "offset": 100 } } } } } ``` See [Pix order messages](/docs/whatsapp/send-messages/pix-orders). ## API changes **Address WhatsApp contacts by BSUID**: `GET`, `PATCH`, and `DELETE` on `/platform/v1/whatsapp/contacts/{identifier}` now accept a business-scoped user ID (`US.13491208655302741918`) or parent business-scoped user ID (`US.ENT.11815799212886844830`) in addition to the contact UUID and phone number. A parent BSUID can match several contacts in a project; the most recently created one is returned. ```bash theme={null} curl https://api.kapso.ai/platform/v1/whatsapp/contacts/US.13491208655302741918 \ -H "X-API-Key: $KAPSO_API_KEY" ``` See [Business-scoped user IDs](/docs/whatsapp/business-scoped-user-ids). ## Features **Telephony provider settings**: Projects with the custom telephony add-on can configure credentials per provider in **Project settings → Telephony**, with their own secrets, allowed countries, and per-country configuration. One provider is selected as the project default for number search, provisioning, and pool maintenance. Telnyx is enabled per project by Kapso. **Setup links accept non-US countries with any telephony provider**: `phone_number_country_isos` outside `["US"]` previously required custom Twilio credentials. Any configured and selected telephony provider now satisfies the check, on both the Platform API and the legacy `api/v1` endpoint. See [Provide local numbers](/docs/platform/phone-numbers/provide-local-numbers). ## Webhooks **New `whatsapp.contact.identity_changed` event**: Subscribe a phone number webhook to be notified when a contact receives a new business-scoped user ID. The payload includes the updated `contact` and the `previous` business-scoped user IDs. ```json theme={null} { "contact": { "id": "contact_123", "customer_id": "customer_456", "wa_id": "15551234567", "business_scoped_user_id": "US.13491208655302741918", "parent_business_scoped_user_id": "US.ENT.506847293015824" }, "previous": { "business_scoped_user_id": "US.OLD.13491208655302741918", "parent_business_scoped_user_id": "US.OLD.ENT.506847293015824" }, "phone_number_id": "123456789012345" } ``` See [Message events](/docs/platform/webhooks/message-events). ## API changes **`max` reasoning effort**: `reasoning_effort` now accepts `max` in addition to `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. It applies to custom agents, custom agent chats, and flow agent steps. Check a provider model's `supported_reasoning_efforts` before sending it. ## Features **Phone number management restricted to owners and admins**: Connecting a WhatsApp number is now limited to project owners and admins. Members see the action disabled with an explanation. ## Bug fixes **Setup falls back to direct Meta billing**: When a WhatsApp Business Account already has its own Meta payment method, requesting Kapso credit billing no longer leaves the account flagged for attention or pauses paid sends. The account stays on direct Meta billing and the setup link switches to `customer_managed`. See [Meta message billing](/docs/whatsapp/meta-message-billing). ## Bug fixes **Stale wait timeouts no longer resume workflows**: When a workflow execution returns to a wait step it already visited, the timeout scheduled for the earlier visit is now ignored. Only the timeout belonging to the current visit can resume the execution, so loops through a wait step no longer time out early. ## Bug fixes **Flow responses link correctly with custom flow tokens**: Kapso now attributes a WhatsApp Flow response to its flow using the outbound message the reply responds to, instead of matching the `flow_token` against the flow ID. Custom `flow_token` values no longer break response collection, and flows sent through a template `FLOW` button are attributed too. Responses that still can't be matched to a flow are stored instead of dropped. See [Sending & receiving flows](/docs/whatsapp/flows/sending-flows). ## Features **Inbox keyboard shortcuts**: Navigate conversations with `J` and `K`, open the focused conversation with `Enter`, focus the message composer with `R`, and start a new conversation with `C`. The `C` shortcut is not available in the embedded inbox. ## Features **Meta message billing with Kapso credits**: Kapso can pay Meta's WhatsApp message fees and deduct Meta's published USD price from project credits, with no added fee. WABAs can also continue paying Meta directly. ## API changes **Setup-link billing policy**: Set `meta_billing_mode` to `partner_managed` when creating a setup link to request Kapso billing. Omitting it keeps the default `customer_managed` policy. See [Meta message billing](/docs/whatsapp/meta-message-billing) and [Setup links](/docs/platform/setup-links/create-and-configure). ## Features **Project event lifecycle management**: Archive event definitions to hide them from event tools and workflow selectors while retaining recorded events, or permanently delete a definition and its event history. ## API changes **Archive and delete event definitions**: Use `PATCH /platform/v1/event-definitions/{id}` with `archived: true` or `false`, include archived definitions with `include_archived=true`, and use `DELETE /platform/v1/event-definitions/{id}` to queue permanent deletion. Deletion returns `202 Accepted` and runs asynchronously. Event definition responses now include `archived_at`. See [Project events](/docs/platform/events). ## 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/manage#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/meta/whatsapp/media/get-media-url) 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. ## 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/project-webhooks) 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