integrate-whatsapp

Name: integrate-whatsapp
Author: gokapso

2.9kinstalls19forks

How to install integrate-whatsapp?

gokapso/agent-skills/integrate-whatsapp

$npx -y skills add gokapso/agent-skills --skill integrate-whatsapp

Installs into the current project.

Summary

Connect WhatsApp to your product with Kapso: onboard customers with setup links, detect connections, receive events via webhooks, and send messages/templates/media. Also manage WhatsApp Flows (create/update/publish, data endpoints, encryption). Use when integrating WhatsApp end-t

Files · 1

View on GitHub

SKILL.md

1	# Integrate WhatsApp
2
3	## Setup
4
5	Preferred path:
6	- Kapso CLI installed and authenticated (`kapso login`)
7	- Use `kapso status` to confirm project access before onboarding or messaging
8
9	Fallback path:
10	Env vars:
11	- `KAPSO_API_BASE_URL` (host only, no `/platform/v1`)
12	- `KAPSO_API_KEY`
13	- `META_GRAPH_VERSION` (optional, default `v24.0`)
14
15	Auth header (direct API calls):
16	```
17	X-API-Key: <api_key>
18	```
19
20	Install deps (once):
21	```bash
22	npm i
23	```
24
25	## Connect WhatsApp (setup links)
26
27	Preferred onboarding path (CLI):
28
29	1. Start onboarding: `kapso setup`
30	2. If setup is blocked, resolve context with:
31	- `kapso projects list`
32	- `kapso projects use <project-id>`
33	- `kapso customers list`
34	- `kapso customers new --name "<customer-name>" --external-id <external-id>`
35	- `kapso setup --customer <customer-id>`
36	3. Complete the hosted onboarding URL
37	4. Confirm connected numbers: `kapso whatsapp numbers list --output json`
38	5. Resolve the exact number you want to operate: `kapso whatsapp numbers resolve --phone-number "<display-number>" --output json`
39
40	Fallback onboarding flow (direct API):
41
42	1. Create customer: `POST /platform/v1/customers`
43	2. Generate setup link: `POST /platform/v1/customers/:id/setup_links`
44	3. Customer completes embedded signup
45	4. Use `phone_number_id` to send messages and configure webhooks
46
47	Detect connection:
48	- Project webhook `whatsapp.phone_number.created` (recommended)
49	- Success redirect URL query params (use for frontend UX)
50
51	Recommended Kapso setup-link defaults:
52	```json
53	{
54	"setup_link": {
55	"allowed_connection_types": ["dedicated"],
56	"provision_phone_number": true,
57	"phone_number_country_isos": ["US"]
58	}
59	}
60	```
61
62	Notes:
63	- `kapso setup` and `kapso whatsapp numbers new` use dedicated plus provisioning by default.
64	- Keep `phone_number_country_isos`, `phone_number_area_code`, `language`, and redirect URLs as optional overrides.
65
66	- Platform API base: `/platform/v1`
67	- Meta proxy base: `/meta/whatsapp/v24.0` (messaging, templates, media)
68	- Use `phone_number_id` as the primary WhatsApp identifier
69
70	## Receive events (webhooks)
71
72	Use webhooks to receive:
73	- Project events (connection lifecycle, workflow events)
74	- Phone-number events (messages, conversations, delivery status)
75
76	Scope rules:
77	- Project webhooks: only project-level events (connection lifecycle, workflow events)
78	- Phone-number webhooks: only WhatsApp message + conversation events for that `phone_number_id`
79	- WhatsApp message/conversation events (`whatsapp.message.`, `whatsapp.conversation.`) are phone-number only
80
81	Create a webhook:
82	- Project-level: `node scripts/create.js --scope project --url <https://...> --events <csv>`
83	- Phone-number: `node scripts/create.js --phone-number-id <id> --url <https://...> --events <csv>`
84
85	Common flags for create/update:
86	- `--url <https://...>` - webhook destination
87	- `--events <csv\|json-array>` - event types (Kapso webhooks)
88	- `--kind <kapso\|meta>` - Kapso (event-based) vs raw Meta forwarding
89	- `--payload-version <v1\|v2>` - payload format (`v2` recommended)
90	- `--buffer-enabled <true\|false>` - enable buffering for `whatsapp.message.received`
91	- `--buffer-window-seconds <n>` - 1-60 seconds
92	- `--max-buffer-size <n>` - 1-100
93	- `--active <true\|false>` - enable/disable
94
95	Test delivery:
96	```bash
97	node scripts/test.js --webhook-id <id>
98	```
99
100	Always verify signatures. See:
101	- `references/webhooks-overview.md`
102	- `references/webhooks-reference.md`
103
104	## Send and read messages
105
106	### Discover IDs first
107
108	Two Meta IDs are needed for different operations:
109
110	\| ID \| Used for \| How to discover \|
111	\|----\|----------\|-----------------\|
112	\| `business_account_id` (WABA) \| Template CRUD \| `kapso whatsapp numbers resolve --phone-number "<display-number>" --output json` or `node scripts/list-platform-phone-numbers.mjs` \|
113	\| `phone_number_id` \| Sending messages, media upload \| `kapso whatsapp numbers resolve --phone-number "<display-number>" --output json` or `node scripts/list-platform-phone-numbers.mjs` \|
114
115	### Operate with the CLI first
116
117	Common commands:
118	```bash
119	kapso whatsapp numbers list --output json
120	kapso whatsapp numbers resolve --phone-number "<display-number>" --output json
121	kapso whatsapp messages send --phone-number-id <PHONE_NUMBER_ID> --to <wa-id> --text "Hello from Kapso"
122	kapso whatsapp messages list --phone-number-id <PHONE_NUMBER_ID> --limit 50 --output json
123	kapso whatsapp messages get <MESSAGE_ID> --phone-number-id <PHONE_NUMBER_ID> --output json
124	kapso whatsapp conversations list --phone-number-id <PHONE_NUMBER_ID> --output json
125	kapso whatsapp templates list --phone-number-id <PHONE_NUMBER_ID> --output json
126	kapso whatsapp templates get <TEMPLATE_ID> --phone-number-id <PHONE_NUMBER_ID> --output json

People who liked this also viewed

6 picks

Type

integrate-whatsapp

2.9kinstalls19forks

View on GitHub

How to install integrate-whatsapp?

gokapso/agent-skills/integrate-whatsapp

$npx -y skills add gokapso/agent-skills --skill integrate-whatsapp

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Integrate WhatsApp
2
3	## Setup
4
5	Preferred path:
6	- Kapso CLI installed and authenticated (`kapso login`)
7	- Use `kapso status` to confirm project access before onboarding or messaging
8
9	Fallback path:
10	Env vars:
11	- `KAPSO_API_BASE_URL` (host only, no `/platform/v1`)
12	- `KAPSO_API_KEY`
13	- `META_GRAPH_VERSION` (optional, default `v24.0`)
14
15	Auth header (direct API calls):
16	```
17	X-API-Key: <api_key>
18	```
19
20	Install deps (once):
21	```bash
22	npm i
23	```
24
25	## Connect WhatsApp (setup links)
26
27	Preferred onboarding path (CLI):
28
29	1. Start onboarding: `kapso setup`
30	2. If setup is blocked, resolve context with:
31	- `kapso projects list`
32	- `kapso projects use <project-id>`
33	- `kapso customers list`
34	- `kapso customers new --name "<customer-name>" --external-id <external-id>`
35	- `kapso setup --customer <customer-id>`
36	3. Complete the hosted onboarding URL
37	4. Confirm connected numbers: `kapso whatsapp numbers list --output json`
38	5. Resolve the exact number you want to operate: `kapso whatsapp numbers resolve --phone-number "<display-number>" --output json`
39
40	Fallback onboarding flow (direct API):
41
42	1. Create customer: `POST /platform/v1/customers`
43	2. Generate setup link: `POST /platform/v1/customers/:id/setup_links`
44	3. Customer completes embedded signup
45	4. Use `phone_number_id` to send messages and configure webhooks
46
47	Detect connection:
48	- Project webhook `whatsapp.phone_number.created` (recommended)
49	- Success redirect URL query params (use for frontend UX)
50
51	Recommended Kapso setup-link defaults:
52	```json
53	{
54	"setup_link": {
55	"allowed_connection_types": ["dedicated"],
56	"provision_phone_number": true,
57	"phone_number_country_isos": ["US"]
58	}
59	}
60	```
61
62	Notes:
63	- `kapso setup` and `kapso whatsapp numbers new` use dedicated plus provisioning by default.
64	- Keep `phone_number_country_isos`, `phone_number_area_code`, `language`, and redirect URLs as optional overrides.
65
66	- Platform API base: `/platform/v1`
67	- Meta proxy base: `/meta/whatsapp/v24.0` (messaging, templates, media)
68	- Use `phone_number_id` as the primary WhatsApp identifier
69
70	## Receive events (webhooks)
71
72	Use webhooks to receive:
73	- Project events (connection lifecycle, workflow events)
74	- Phone-number events (messages, conversations, delivery status)
75
76	Scope rules:
77	- Project webhooks: only project-level events (connection lifecycle, workflow events)
78	- Phone-number webhooks: only WhatsApp message + conversation events for that `phone_number_id`
79	- WhatsApp message/conversation events (`whatsapp.message.`, `whatsapp.conversation.`) are phone-number only
80
81	Create a webhook:
82	- Project-level: `node scripts/create.js --scope project --url <https://...> --events <csv>`
83	- Phone-number: `node scripts/create.js --phone-number-id <id> --url <https://...> --events <csv>`
84
85	Common flags for create/update:
86	- `--url <https://...>` - webhook destination
87	- `--events <csv\|json-array>` - event types (Kapso webhooks)
88	- `--kind <kapso\|meta>` - Kapso (event-based) vs raw Meta forwarding
89	- `--payload-version <v1\|v2>` - payload format (`v2` recommended)
90	- `--buffer-enabled <true\|false>` - enable buffering for `whatsapp.message.received`
91	- `--buffer-window-seconds <n>` - 1-60 seconds
92	- `--max-buffer-size <n>` - 1-100
93	- `--active <true\|false>` - enable/disable
94
95	Test delivery:
96	```bash
97	node scripts/test.js --webhook-id <id>
98	```
99
100	Always verify signatures. See:
101	- `references/webhooks-overview.md`
102	- `references/webhooks-reference.md`
103
104	## Send and read messages
105
106	### Discover IDs first
107
108	Two Meta IDs are needed for different operations:
109
110	\| ID \| Used for \| How to discover \|
111	\|----\|----------\|-----------------\|
112	\| `business_account_id` (WABA) \| Template CRUD \| `kapso whatsapp numbers resolve --phone-number "<display-number>" --output json` or `node scripts/list-platform-phone-numbers.mjs` \|
113	\| `phone_number_id` \| Sending messages, media upload \| `kapso whatsapp numbers resolve --phone-number "<display-number>" --output json` or `node scripts/list-platform-phone-numbers.mjs` \|
114
115	### Operate with the CLI first
116
117	Common commands:
118	```bash
119	kapso whatsapp numbers list --output json
120	kapso whatsapp numbers resolve --phone-number "<display-number>" --output json
121	kapso whatsapp messages send --phone-number-id <PHONE_NUMBER_ID> --to <wa-id> --text "Hello from Kapso"
122	kapso whatsapp messages list --phone-number-id <PHONE_NUMBER_ID> --limit 50 --output json
123	kapso whatsapp messages get <MESSAGE_ID> --phone-number-id <PHONE_NUMBER_ID> --output json
124	kapso whatsapp conversations list --phone-number-id <PHONE_NUMBER_ID> --output json
125	kapso whatsapp templates list --phone-number-id <PHONE_NUMBER_ID> --output json
126	kapso whatsapp templates get <TEMPLATE_ID> --phone-number-id <PHONE_NUMBER_ID> --output json

People who liked this also viewed

6 picks

Type