/automate-whatsapp

name: automate-whatsapp
description: Build and debug Kapso WhatsApp workflows, triggers, functions, and executions.

Automate WhatsApp

When to use

Use this skill to build and run WhatsApp automations: workflow CRUD, graph edits, WhatsApp and Project Event triggers, Project Event emissions, executions, function management, webhook tools, and MCP tools.

Setup

Preferred path:

• Kapso CLI installed and authenticated (`kapso login`)
• For workflow and function edits, use source-controlled projects with `kapso link`, `kapso pull`, `kapso build`, and `kapso push`
• For workflow code, use `@kapso/workflows` and export a `Workflow` instance from `workflow.js` or `workflow.ts`

Fallback path: Env vars:

• `KAPSO_API_BASE_URL` (host only, no `/platform/v1`)
• `KAPSO_API_KEY`

How to

Edit workflows locally

Use this path first when the user is working in, or can create, a local repo.

npm install -g @kapso/cli
npm install --save-dev @kapso/workflows
kapso login
kapso link --project <project-id>
kapso pull

Edit `workflows/<workflow-slug>/workflow.js` or `workflow.ts` with `@kapso/workflows`:

import { START, Workflow } from "@kapso/workflows";

const workflow = new Workflow("inbound-support", {
  name: "Inbound Support",
  status: "draft",
});

workflow.addTrigger({
  type: "inbound_message",
  phoneNumberId: "<phone-number-id>",
});

workflow.addNode(START, {
  position: { x: 100, y: 100 },
});

workflow.addNode("reply", {
  type: "send_text",
  message: "Thanks for reaching out.",
});

workflow.addEdge(START, "reply");

export default workflow;

Build and push:

kapso build
kapso push --dry-run
kapso push workflow <workflow-slug>

Use `kapso push` to push every local function and workflow. See `references/local-workflow-source.md` for repo layout, source-file behavior, and JSON-only editing.

Discover phone numbers first

Preferred path: 1. Check project state: `kapso status` 2. List connected numbers: `kapso whatsapp numbers list --output json` 3. Resolve a display number when needed: `kapso whatsapp numbers resolve --phone-number "<display-number>" --output json`

Fallback path: 1. List number configs for triggers: `node scripts/list-whatsapp-phone-numbers.js`

Edit a workflow graph through API scripts

Prefer local source sync for workflow edits. Use these scripts as a fallback for debugging, direct graph inspection, or API-only environments.

1. Fetch graph: `node scripts/get-graph.js <workflow_id>` (note the `lock_version`) 2. Edit the JSON (see graph rules below) 3. Validate: `node scripts/validate-graph.js --definition-file <path>` 4. Update: `node scripts/update-graph.js <workflow_id> --expected-lock-version <n> --definition-file <path>` 5. Re-fetch to confirm

For small edits, use `edit-graph.js` with `--old-file` and `--new-file` instead.

If you get a lock_version conflict: re-fetch, re-apply changes, retry with new lock_version.

Manage triggers

1. List: `node scripts/list-triggers.js <workflow_id>` 2. Create: `node scripts/create-trigger.js <workflow_id> --trigger-type <type> --phone-number-id <id>` 3. Toggle: `node scripts/update-trigger.js --trigger-id <id> --active true|false` 4. Delete: `node scripts/delete-trigger.js --trigger-id <id>`

For inbound_message triggers, prefer `kapso whatsapp numbers resolve --phone-number "<display-number>" --output json` to get the exact `phone_number_id`. Fall back to `node scripts/list-whatsapp-phone-numbers.js` when the CLI is unavailable.

For project_event triggers, register or update the Project Event definition first when the user is defining an event type/schema:

node scripts/project-event-definitions.js create \
  --name conversation.csat_scored \
  --description "Customer satisfaction score for a conversation" \
  --property-schema '{"score":{"type":"number"},"reason":{"type":"string"}}'

Then create the trigger:

node scripts/create-trigger.js <workflow_id> \
  --trigger-type project_event \
  --triggerable-attributes '{"event_name":"conversation.csat_scored","property_key":"score","operator":"gte","property_value":4}'

Definitions are metadata only. Do not emit a sample event just to register a name unless the user explicitly accepts that side effect.

Manage Project Event definitions

Use definitions for event names, descriptions, and flat scalar property schemas. Emitted events are separate records created by `POST /platform/v1/events`, `emit_event` nodes, Function node `project_events`, or Agent node `emit_event`.

1. List: `node scripts/project-event-definitions.js list` 2. Create/update by name: `node scripts/project-event-definitions.js create --name <event.name> [--description <text>] [--property-schema <json>]` 3. Update by ID: `node scripts/project-event-definitions.js update --definition-id <id> [--name <event.name>] [--description <text>] [--property-schema <json>]`

Build workflows with Project Events

Use this checklist when a workflow needs to remember or react to durable business facts:

1. Define the event first when the user is introducing a new event name or schema. 2. Use `project_event` triggers when a workflow should react to an emitted event. 3. Use an `emit_event` node for deterministic workflow-step emission. 4. Use Function node `project_events` when emission depends on function code output. 5. Use Agent node `emit_event` only when the agent should decide whether/when to record the fact. Enable the `emit_event` default tool and configure allowed event definitions before relying on it.

Project-event-triggered workflows are observers and cannot emit Project Events. Do not add event emission to a workflow that starts from a Project Event trigger.

Debug executions

1. Search workflow logs first when you have an execution ID: `kapso logs search --query "<execution-id>" --source flow_event --filter flow_execution_id=<execution-id> --period 7d --limit 20 --output json` 2. List: `node scripts/list-executions.