# WhatsApp Business API

> Complete WhatsApp Business Cloud API for messages, templates, media, webhooks, flows, and business profiles.

- Skill: `modbender/whatsapp-business-api` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds add modbender/whatsapp-business-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/modbender/whatsapp-business-api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: modbender (https://skillmd.com/u/modbender)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/modbender/whatsapp-business-api

---


# WhatsApp Business API

Official Meta Cloud API integration. See auxiliary files for detailed operations.

## Quick Start

```bash
curl -X POST "https://graph.facebook.com/v21.0/$WHATSAPP_PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messaging_product":"whatsapp","to":"1234567890","type":"text","text":{"body":"Hello!"}}'
```

## Setup

On first use, read `setup.md`. Preferences stored in `~/whatsapp-business-api/memory.md`.

## When to Use

Any WhatsApp Business operation: send messages, templates, media, interactive elements, manage webhooks, handle conversations, update business profiles.

## Architecture

```
~/whatsapp-business-api/
├── memory.md      # Account context + phone numbers
├── templates.md   # Approved templates reference
└── webhooks.md    # Webhook configurations
```

## Quick Reference

| Topic | File |
|-------|------|
| Setup & memory | `setup.md`, `memory-template.md` |
| Messages (text, media, interactive) | `messages.md` |
| Templates (create, manage, send) | `templates.md` |
| Media (upload, download, manage) | `media.md` |
| Webhooks & Events | `webhooks.md` |
| Business Profile & Phone Numbers | `business.md` |
| Flows (interactive forms) | `flows.md` |
| Best practices & limits | `best-practices.md` |

## Core Rules

1. **International format** — Phone numbers without `+` or leading zeros: `1234567890`
2. **24-hour window** — Free replies within 24h of customer message; templates required to initiate
3. **Template approval** — Templates need Meta approval (24-48h); test in sandbox first
4. **Idempotency** — Use `biz_opaque_callback_data` to track message state
5. **Webhook verification** — Always verify webhook signature with app secret
6. **Rate limits** — 80 messages/second per phone number; 1000 template messages/day (tier 1)
7. **Media limits** — Images <5MB, videos <16MB, documents <100MB

## Authentication

**Required environment variables:**
- `WHATSAPP_ACCESS_TOKEN` — System User access token (permanent) or User access token (60-day)
- `WHATSAPP_PHONE_NUMBER_ID` — Your registered phone number ID
- `WHATSAPP_BUSINESS_ACCOUNT_ID` — Your WABA ID (for templates)
- `WHATSAPP_APP_SECRET` — App secret for webhook verification

```bash
curl "https://graph.facebook.com/v21.0/$WHATSAPP_PHONE_NUMBER_ID" \
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN"
```

### Token Types

| Type | Duration | Use Case |
|------|----------|----------|
| System User Token | Permanent | Production apps |
| User Token | 60 days | Development, testing |
| Temporary Token | 24 hours | Quick tests |

## Common Traps

- Phone format with `+` or `00` → API rejects
- Missing `messaging_product: "whatsapp"` → 400 error
- Template not approved → message fails silently
- Webhook signature not verified → security vulnerability
- Sending outside 24h window without template → blocked

## External Endpoints

| Endpoint | Purpose |
|----------|---------|
| `https://graph.facebook.com/v21.0/*` | Cloud API |

## Security & Privacy

**Environment variables used:**
- `WHATSAPP_ACCESS_TOKEN` — for API authentication
- `WHATSAPP_APP_SECRET` — for webhook signature verification

**Sent to Meta:** Messages, media, customer phone numbers via graph.facebook.com
**Stays local:** Tokens (never logged), ~/whatsapp-business-api/ preferences
**Never:** Log message content, skip webhook verification, store tokens in code

## Trust

This skill sends data to Meta (facebook.com/whatsapp).

## Related Skills
Install with `clawhub install <slug>` if user confirms:
- `api` — REST API patterns
- `webhook` — Webhook handling
- `chat` — Conversational patterns

## Feedback

- If useful: `clawhub star whatsapp-business-api`
- Stay updated: `clawhub sync`