README.md

# Kapso

## Description

Kapso is the WhatsApp API for developers. This plugin helps agents build, integrate, and observe WhatsApp automations, Project Event workflows, and recurring project Findings through Kapso skills, helper scripts, examples, and a remote MCP connection.

## Features

- Connect WhatsApp to products with setup links, connection detection, webhooks, sends, templates, media, and WhatsApp Flows.
- Build Kapso workflows with WhatsApp and Project Event triggers, Project Event emissions, AI steps, functions, app integrations, data tables, and execution controls.
- Observe production issues with Findings and unified project log search across API calls, Meta events, workflow events, webhook deliveries, message delivery, template health, number health, and error patterns.
- Use bundled examples and references so agents can act with product-specific context instead of generic WhatsApp guidance.
- Keep risky operations behind explicit user approval for sends, Project Event emissions, deploys, deletes, webhook changes, template creation, setup links, workflow mutations, and Finding lifecycle changes.

## Installation

Install from the Cursor marketplace:

```text
/add-plugin kapso
```

Codex users can install from the custom marketplace:

```bash
codex plugin marketplace add gokapso/agent-plugins
codex plugin add app-69e50baf29a48191847ceec3bfd887a4@kapso
```

## Components

- Skills:
  - `integrate-whatsapp`: connect WhatsApp to products, onboard customers, configure webhooks, send messages, manage templates, and work with WhatsApp Flows.
  - `automate-whatsapp`: build workflows with WhatsApp and Project Event triggers, event emissions, functions, agents, app integrations, and database-backed automations.
  - `observe-whatsapp`: investigate recurring Findings, search unified project logs, inspect delivery, webhook retries, API errors, workflow events, number health, templates, and operational incidents.
- Rule:
  - `kapso-safety`: classifies read-only, local write, and high-risk write operations, and requires explicit approval before high-risk writes.
- MCP:
  - `kapso`: remote authenticated MCP server at `https://api.kapso.ai/mcp`, including grouped project Findings actions when used for Findings work.

## Prerequisites

- Sign in or create a Kapso account during the host's Connect account flow, then approve project access.
- Node.js 20+ for the bundled helper scripts.
- Optional: Kapso CLI installed and authenticated.

```bash
npm install -g @kapso/cli
kapso login
```

Installing through the Codex UI requests account connection. No API key is needed.
Start with **Open Kapso** after approving project access. The plugin checks the
connected project and opens the inbox when a production WhatsApp number exists,
or the setup UI when the first number still needs connecting. An explicit request
to connect another number opens setup even when a number already exists. Other
requests, such as unread conversations or building an agent, keep their own flow.
The UI tools must be advertised by the connected server; otherwise the plugin
explains the limitation and uses supported read-only tools.
For CLI-installed plugins that still need authentication:

```bash
codex mcp login kapso
```

Project API keys remain useful for direct API fallback scripts:

```bash
export KAPSO_API_KEY="..."
export KAPSO_API_BASE_URL="https://api.kapso.ai"
```

## MCP

The bundled MCP config points to:

```text
https://api.kapso.ai/mcp
```

Cursor users can authenticate the remote MCP server from Cursor after the plugin is installed:

1. Open Cursor settings for MCP servers.
2. Find the `kapso` server.
3. Start the connection or authentication flow.
4. Complete the Kapso login and approval flow in the browser window Cursor opens.
5. Return to Cursor and confirm the `kapso` MCP server is connected.

If Cursor prompts for a server URL during manual setup, use:

```text
https://api.kapso.ai/mcp
```

Codex users connect their account during UI installation or through the plugin's Connect account control. For a CLI installation that needs manual authentication:

```bash
codex mcp login kapso
```

Maintainer note: the plugin includes both `mcp.json` and `.mcp.json` because different agent hosts look for different MCP config filenames. They intentionally point to the same Kapso remote MCP endpoint.

## Examples

### Onboard a Customer to WhatsApp

User prompt: "Create a setup link for this customer and tell me how to detect when they finish connecting WhatsApp."

Expected behavior:

- The agent uses the `integrate-whatsapp` skill.
- It checks for a customer record or creates one when appropriate.
- It generates a setup link, explains redirect handling, and points to webhook or API-based connection detection.

### Build a WhatsApp Support Workflow

User prompt: "Build a WhatsApp support intake workflow that asks for order ID, classifies the issue, and routes urgent cases."

Expected behavior:

- The agent uses the `automate-whatsapp` skill.
- It drafts or updates a workflow graph with WhatsApp trigger, wait, decide, function, and agent nodes.
- It validates the graph before suggesting deployment.

### React to a Project Event

User prompt: "When a conversation gets a CSAT score under 3, open a recovery workflow and notify the team."

Expected behavior:

- The agent uses the `automate-whatsapp` skill.
- It creates or updates a `project_event` trigger with event-name and property filters.
- It uses Project Events for durable scores or labels, and avoids emitting more events from a project-event-triggered workflow.

### Debug a Failed Message

User prompt: "Why did this WhatsApp message fail, and did the webhook retry?"

Expected behavior:

- The agent uses the `observe-whatsapp` skill.
- It starts with unified log search, then gathers message details, delivery history, API errors, webhook deliveries, and number health as needed.
- It returns a concise diagnosis with next actions and escalation paths.

### Review a Recurring Project Problem

User prompt: "Review the recurring problems in my project and investigate the most important one."

Expected behavior:

- The agent uses the `observe-whatsapp` skill and the Kapso MCP `findings` tool.
- It lists Findings, reads the selected Finding and its bounded evidence, and distinguishes the Finding's aggregate signal from the underlying Project Events and operational Logs.
- It asks for approval before starting the specialized investigation, then verifies the resulting investigation state.

## Safety

Read-only inspection and local validation are safe defaults. Real sends, Project Event emissions, flow publishes, deletes, webhook updates, template creates, function deploys, trigger changes, customer/setup-link writes, starting or retrying Finding investigations, dismissing Findings, and marking Findings addressed require explicit user approval.

The integration helper scripts require HTTPS and reject authenticated request redirects. Use `KAPSO_ALLOW_INSECURE_HTTP=true` only for a trusted development endpoint. They redact recognized credential fields; set `KAPSO_SECRET_OUTPUT_FILE` to a new file in a private directory to capture a one-time secret with owner-only permissions. See the integration skill's [credential handling](skills/integrate-whatsapp/references/webhooks-reference.md#credential-handling).

## Privacy Policy

See: https://kapso.com/privacy

## Support

- Documentation: https://docs.kapso.ai
- Issues and plugin requests: https://github.com/gokapso/agent-plugins/issues