Whatsapp messaging

WhatsApp Messaging

Base URL: https://api.zaphook.cloud Auth: Authorization: Bearer zph_...

All endpoints require channel_id (uuid) and to (phone number, international format, digits only, 10-15 chars).

Commands

Send Text

node scripts/send-text.mjs --channel-id <uuid> --to 5511999999999 --body "Hello!"

POST /api/public/v1/messages/send-text Body: { "channel_id": "uuid", "to": "phone", "text": { "body": "msg", "preview_url": false } }

Send Buttons (1-3 buttons)

node scripts/send-buttons.mjs --channel-id <uuid> --to <phone> --body "Choose:" --buttons '[{"id":"yes","title":"Yes"},{"id":"no","title":"No"}]'

POST /api/public/v1/messages/send-buttons Body: { "channel_id", "to", "body", "buttons": [{"id","title"}], "header?", "footer?" }

Send List

node scripts/send-list.mjs --channel-id <uuid> --to <phone> --body "Select:" --button-text "Menu" --sections '[{"title":"S1","rows":[{"id":"1","title":"Item","description":"desc"}]}]'

POST /api/public/v1/messages/send-list Body: { "channel_id", "to", "body", "button_text", "sections": [{"title","rows":[{"id","title","description?"}]}], "header?", "footer?" }

Send Image

node scripts/send-image.mjs --channel-id <uuid> --to <phone> --link "https://..." [--caption "text"]

POST /api/public/v1/messages/send-image Body: { "channel_id", "to", "image": {"link":"url"} or {"id":"media_id"}, "caption?" }

Send Video

node scripts/send-video.mjs --channel-id <uuid> --to <phone> --link "https://..." [--caption "text"]

POST /api/public/v1/messages/send-video

Send Audio

node scripts/send-audio.mjs --channel-id <uuid> --to <phone> --link "https://..."

POST /api/public/v1/messages/send-audio

Send Document

node scripts/send-document.mjs --channel-id <uuid> --to <phone> --link "https://..." [--filename "doc.pdf"] [--caption "text"]

POST /api/public/v1/messages/send-document

Send Sticker (.webp, 512x512, max 100KB static / 500KB animated)

node scripts/send-sticker.mjs --channel-id <uuid> --to <phone> --link "https://..."

POST /api/public/v1/messages/send-sticker

Send Location

node scripts/send-location.mjs --channel-id <uuid> --to <phone> --lat -23.55 --lng -46.63 [--name "Place"] [--address "Street"]

POST /api/public/v1/messages/send-location Body: { "channel_id", "to", "location": {"latitude","longitude","name?","address?"} }

Request Location

POST /api/public/v1/messages/request-location Body: { "channel_id", "to", "body": "Please share your location" }

Send Contact

POST /api/public/v1/messages/send-contact Body: { "channel_id", "to", "contacts": [{"name":{"formatted_name","first_name","last_name?"},"phones":[{"phone","type?"}],"emails?","urls?","addresses?","org?","birthday?"}] }

Send Reaction

node scripts/send-reaction.mjs --channel-id <uuid> --to <phone> --message-id "wamid.x" --emoji "👍"

POST /api/public/v1/messages/send-reaction Body: { "channel_id", "to", "message_id", "emoji" } (empty emoji to remove)

Mark as Read

node scripts/mark-as-read.mjs --channel-id <uuid> --message-id "wamid.x"

POST /api/public/v1/messages/mark-as-read Body: { "channel_id", "message_id" }

Send Template

node scripts/send-template.mjs --channel-id <uuid> --to <phone> --name "hello_world" --language "pt_BR" [--components '[{"type":"body","parameters":[{"type":"text","text":"João"}]}]']

POST /api/public/v1/messages/send-template Body: { "channel_id", "to", "template": {"name","language","components?"} }

Typing Indicator

node scripts/typing.mjs --channel-id <uuid> --message-id "wamid.x"

POST /api/public/v1/messages/typing Body: { "channel_id", "message_id" } (also marks as read, shows typing ~25s)

Response Format

{ "data": { "message_id": "wamid.xxx", "status": "sent" }, "meta": { "request_id": "uuid", "timestamp": "ISO8601" } }

Troubleshooting

If a message send fails:

1. Check channel health: use zaphook-api skill → node scripts/channel-status.mjs --channel-id <id>
2. If channel is inactive or not found: verify channel exists with node scripts/get-channel.mjs --channel-id <id>
3. Check delivery logs: use observe-whatsapp skill → node scripts/list-events.mjs --has-errors true --channel-id <id>
4. Inspect specific failure: use observe-whatsapp skill → node scripts/get-event.mjs --event-id <uuid>
5. If 401: API key invalid or expired → run npx zaphook-skills configure
6. If 429: rate limit exceeded → wait and retry (built-in exponential backoff handles this automatically)
7. If 422: check required fields and phone number format (digits only, 10-15 chars, international format)

Related skills

• zaphook-api — Channel and destination management
• observe-whatsapp — Monitor events and delivery status

Agent Rules

• Never send a message without explicit user permission. Always confirm before executing any send command.
• Portuguese (pt-BR): Always use proper accents and special characters (ã, ç, é, ê, í, ó, ú, à, ü) when composing messages in Portuguese. Never omit diacritics.
• English: Use standard English without localization issues.
• Use --dry-run to preview payloads before sending when unsure about parameters.