Automate Whatsapp

1---
2name: automate-whatsapp
3description: "Build WhatsApp automations with Kapso workflows: configure WhatsApp triggers, edit workflow graphs, manage executions, deploy functions, and use databases/integrations for state. Use when automating WhatsApp conversations and event handling."
4---
5 
6# Automate WhatsApp
7 
8## When to use
9 
10Use this skill to build and run WhatsApp automations: workflow CRUD, graph edits, triggers, executions, function management, app integrations, and D1 database operations.
11 
12## Setup
13 
14Env vars:
15- `KAPSO_API_BASE_URL` (host only, no `/platform/v1`)
16- `KAPSO_API_KEY`
17 
18## How to
19 
20### Edit a workflow graph
21 
221. Fetch graph: `node scripts/get-graph.js <workflow_id>` (note the `lock_version`)
232. Edit the JSON (see graph rules below)
243. Validate: `node scripts/validate-graph.js --definition-file <path>`
254. Update: `node scripts/update-graph.js <workflow_id> --expected-lock-version <n> --definition-file <path>`
265. Re-fetch to confirm
27 
28For small edits, use `edit-graph.js` with `--old-file` and `--new-file` instead.
29 
30If you get a lock_version conflict: re-fetch, re-apply changes, retry with new lock_version.
31 
32### Manage triggers
33 
341. List: `node scripts/list-triggers.js <workflow_id>`
352. Create: `node scripts/create-trigger.js <workflow_id> --trigger-type <type> --phone-number-id <id>`
363. Toggle: `node scripts/update-trigger.js --trigger-id <id> --active true|false`
374. Delete: `node scripts/delete-trigger.js --trigger-id <id>`
38 
39For inbound_message triggers, first run `node scripts/list-whatsapp-phone-numbers.js` to get `phone_number_id`.
40 
41### Debug executions
42 
431. List: `node scripts/list-executions.js <workflow_id>`
442. Inspect: `node scripts/get-execution.js <execution-id>`
453. Get value: `node scripts/get-context-value.js <execution-id> --variable-path vars.foo`
464. Events: `node scripts/list-execution-events.js <execution-id>`
47 
48### Create and deploy a function
49 
501. Write code with handler signature (see function rules below)
512. Create: `node scripts/create-function.js --name <name> --code-file <path>`
523. Deploy: `node scripts/deploy-function.js --function-id <id>`
534. Verify: `node scripts/get-function.js --function-id <id>`
54 
55### Set up agent node with app integrations
56 
571. Find model: `node scripts/list-provider-models.js`
582. Find account: `node scripts/list-accounts.js --app-slug <slug>` (use `pipedream_account_id`)
593. Find action: `node scripts/search-actions.js --query <word> --app-slug <slug>` (action_id = key)
604. Create integration: `node scripts/create-integration.js --action-id <id> --app-slug <slug> --account-id <id> --configured-props <json>`
615. Add tools to agent node via `flow_agent_app_integration_tools`
62 
63### Database CRUD
64 
651. List tables: `node scripts/list-tables.js`
662. Query: `node scripts/query-rows.js --table <name> --filters <json>`
673. Create/update/delete with row scripts
68 
69## Graph rules
70 
71- Exactly one start node with `id` = `start`
72- Never change existing node IDs
73- Use `{node_type}_{timestamp_ms}` for new node IDs
74- Non-decide nodes have 0 or 1 outgoing `next` edge
75- Decide edge labels must match `conditions[].label`
76- Edge keys are `source`/`target`/`label` (not `from`/`to`)
77 
78For full schema details, see `references/graph-contract.md`.
79 
80## Function rules
81 
82```js
83async function handler(request, env) {
84  // Parse input
85  const body = await request.json();
86  // Use env.KV and env.DB as needed
87  return new Response(JSON.stringify({ result: "ok" }));
88}
89```
90 
91- Do NOT use `export`, `export default`, or arrow functions
92- Return a `Response` object
93 
94## Execution context
95 
96Always use this structure:
97- `vars` - user-defined variables
98- `system` - system variables
99- `context` - channel data
100- `metadata` - request metadata
101 
102## Scripts
103 
104### Workflows
105 
106| Script | Purpose |
107|--------|---------|
108| `list-workflows.js` | List workflows (metadata only) |
109| `get-workflow.js` | Get workflow metadata |
110| `create-workflow.js` | Create a workflow |
111| `update-workflow-settings.js` | Update workflow settings |
112 
113### Graph
114 
115| Script | Purpose |
116|--------|---------|
117| `get-graph.js` | Get workflow graph + lock_version |
118| `edit-graph.js` | Patch graph via string replacement |
119| `update-graph.js` | Replace entire graph |
120| `validate-graph.js` | Validate graph structure locally |
121 
122### Triggers
123 
124| Script | Purpose |
125|--------|---------|
126| `list-triggers.js` | List triggers for a workflow |
127| `create-trigger.js` | Create a trigger |
128| `update-trigger.js` | Enable/disable a trigger |
129| `delete-trigger.js` | Delete a trigger |
130| `list-whatsapp-phone-numbers.js` | List phone numbers for trigger setup |
131 
132### Executions
133 
134| Script | Purpose |
135|--------|---------|
136| `list-executions.js` | List executions |
137| `get-execution.js` | Get execution details |
138| `get-context-value.js` | Read value from execution context |
139| `update-execution-status.js` | Force execution state |
140| `resume-execution.js` | Resume waiting execution |
141| `list-execution-events.js` | List execution events |
142 
143### Functions
144 
145| Script | Purpose |
146|--------|---------|
147| `list-functions.js` | List project functions |
148| `get-function.js` | Get function details + code |
149| `create-function.js` | Create a function |
150| `update-function.js` | Update function code |
151| `deploy-function.js` | Deploy function to runtime |
152| `invoke-function.js` | Invoke function with payload |
153| `list-function-invocations.js` | List function invocations |
154 
155### App integrations
156 
157| Script | Purpose |
158|--------|---------|
159| `list-apps.js` | Search integration apps |
160| `search-actions.js` | Search actions (action_id = key) |
161| `get-action-schema.js` | Get action JSON schema |
162| `list-accounts.js` | List connected accounts |
163| `create-connect-token.js` | Create OAuth connect link |
164| `configure-prop.js` | Resolve remote_options for a prop |
165| `reload-props.js` | Reload dynamic props |
166| `list-integrations.js` | List saved integrations |
167| `create-integration.js` | Create an integration |
168| `update-integration.js` | Update an integration |
169| `delete-integration.js` | Delete an integration |
170 
171### Databases
172 
173| Script | Purpose |
174|--------|---------|
175| `list-tables.js` | List D1 tables |
176| `get-table.js` | Get table schema + sample rows |
177| `query-rows.js` | Query rows with filters |
178| `create-row.js` | Create a row |
179| `update-row.js` | Update rows |
180| `upsert-row.js` | Upsert a row |
181| `delete-row.js` | Delete rows |
182 
183### OpenAPI
184 
185| Script | Purpose |
186|--------|---------|
187| `openapi-explore.mjs` | Explore OpenAPI (search/op/schema/where) |
188 
189Install deps (once):
190```bash
191npm i
192```
193 
194Examples:
195```bash
196node scripts/openapi-explore.mjs --spec workflows search "variables"
197node scripts/openapi-explore.mjs --spec workflows op getWorkflowVariables
198node scripts/openapi-explore.mjs --spec platform op queryDatabaseRows
199```
200 
201## Notes
202 
203- Prefer file paths over inline JSON (`--definition-file`, `--code-file`)
204- `action_id` is the same as `key` from `search-actions`
205- `--account-id` uses `pipedream_account_id` from `list-accounts`
206- Variable CRUD (`variables-set.js`, `variables-delete.js`) is blocked - Platform API doesn't support it
207- Raw SQL execution is not supported via Platform API
208 
209## References
210 
211Read before editing:
212- [references/graph-contract.md](references/graph-contract.md) - Graph schema, computed vs editable fields, lock_version
213- [references/node-types.md](references/node-types.md) - Node types and config shapes
214- [references/workflow-overview.md](references/workflow-overview.md) - Execution flow and states
215 
216Other references:
217- [references/execution-context.md](references/execution-context.md) - Context structure and variable substitution
218- [references/triggers.md](references/triggers.md) - Trigger types and setup
219- [references/app-integrations.md](references/app-integrations.md) - App integration and variable_definitions
220- [references/functions-reference.md](references/functions-reference.md) - Function management
221- [references/functions-payloads.md](references/functions-payloads.md) - Payload shapes for functions
222- [references/databases-reference.md](references/databases-reference.md) - Database operations
223 
224## Assets
225 
226| File | Description |
227|------|-------------|
228| `workflow-linear.json` | Minimal linear workflow |
229| `workflow-decision.json` | Minimal branching workflow |
230| `workflow-agent-simple.json` | Minimal agent workflow |
231| `workflow-customer-support-intake-agent.json` | Customer support intake |
232| `workflow-interactive-buttons-decide-function.json` | Interactive buttons + decide (function) |
233| `workflow-interactive-buttons-decide-ai.json` | Interactive buttons + decide (AI) |
234| `workflow-api-template-wait-agent.json` | API trigger + template + agent |
235| `function-decide-route-interactive-buttons.json` | Function for button routing |
236| `agent-app-integration-example.json` | Agent node with app integrations |
237 
238## Related skills
239 
240- `integrate-whatsapp` - Onboarding, webhooks, messaging, templates, flows
241- `observe-whatsapp` - Debugging, logs, health checks
242 
243<!-- FILEMAP:BEGIN -->
244```text
245[automate-whatsapp file map]|root: .
246|.:{package.json,SKILL.md}
247|assets:{agent-app-integration-example.json,databases-example.json,function-decide-route-interactive-buttons.json,functions-example.json,workflow-agent-simple.json,workflow-api-template-wait-agent.json,workflow-customer-support-intake-agent.json,workflow-decision.json,workflow-interactive-buttons-decide-ai.json,workflow-interactive-buttons-decide-function.json,workflow-linear.json}
248|references:{app-integrations.md,databases-reference.md,execution-context.md,function-contracts.md,functions-payloads.md,functions-reference.md,graph-contract.md,node-types.md,triggers.md,workflow-overview.md,workflow-reference.md}
249|scripts:{configure-prop.js,create-connect-token.js,create-function.js,create-integration.js,create-row.js,create-trigger.js,create-workflow.js,delete-integration.js,delete-row.js,delete-trigger.js,deploy-function.js,edit-graph.js,get-action-schema.js,get-context-value.js,get-execution-event.js,get-execution.js,get-function.js,get-graph.js,get-table.js,get-workflow.js,invoke-function.js,list-accounts.js,list-apps.js,list-execution-events.js,list-executions.js,list-function-invocations.js,list-functions.js,list-integrations.js,list-provider-models.js,list-tables.js,list-triggers.js,list-whatsapp-phone-numbers.js,list-workflows.js,openapi-explore.mjs,query-rows.js,reload-props.js,resume-execution.js,search-actions.js,update-execution-status.js,update-function.js,update-graph.js,update-integration.js,update-row.js,update-trigger.js,update-workflow-settings.js,upsert-row.js,validate-graph.js,variables-delete.js,variables-list.js,variables-set.js}
250|scripts/lib/databases:{args.js,filters.js,kapso-api.js}
251|scripts/lib/functions:{args.js,kapso-api.js}
252|scripts/lib/workflows:{args.js,kapso-api.js,result.js}
253```
254<!-- FILEMAP:END -->
255 
256