# Zaptura WA

> The Autonomous WhatsApp Cloud API & Automation Engine. Unlimited messaging, multi-session isolation, webhooks, and AI agent integration with zero per-message fees.

## Overview
Zaptura WA is an enterprise-grade, high-throughput, self-hosted and cloud-ready WhatsApp REST API gateway. It provides full programmatic control over WhatsApp messaging via native Baileys and WWebJS engine drivers, supporting multi-tenant sessions, incoming message webhooks, interactive buttons, list messages, media attachments, template engines, and AI workflow automations.

## Quick Links
- [Website](https://zapturawa.com)
- [Pricing](https://zapturawa.com/pricing)
- [Documentation & Quickstart](https://zapturawa.com/docs)
- [API Reference (Swagger UI)](https://zapturawa.com/api/docs)
- [OpenAPI Specification (JSON)](https://zapturawa.com/api/docs-json)
- [Full LLM Specification](https://zapturawa.com/llms-full.txt)

## Base API URL
- Production Default: `https://zapturawa.com/api`

## Authentication
Every authenticated API request must include an API key in the request headers:
- Header: `X-API-Key: <your-api-key>`
- Or Header: `Authorization: Bearer <your-jwt-token>` (for account session endpoints)

---

## Core API Endpoints

### System & Health
- `GET /health` - System health, database, and Redis connectivity
- `GET /api/health/live` - Liveness probe for orchestrators
- `GET /api/health/ready` - Readiness probe (verifies database connections)
- `GET /api/docs` - Interactive Swagger/OpenAPI UI
- `GET /api/docs-json` - OpenAPI 3.0 specification in JSON format

### Account & API Key Management
- `POST /api/account/register` - Register a new user account
- `POST /api/account/login` - Authenticate account and receive JWT credentials
- `GET /api/account/me` - Retrieve current account profile, plan, and limits
- `PATCH /api/account/profile` - Update account profile (name)
- `PATCH /api/account/password` - Change account password
- `GET /api/account/plans` - List available subscription plans
- `PATCH /api/account/plan` - Change current plan
- `POST /api/auth/validate` - Validate an API key and inspect permissions
- `GET /api/auth/api-keys` - List generated API keys
- `POST /api/auth/api-keys` - Create a new API key with optional session scoping
- `GET /api/auth/api-keys/{id}` - Get API key details
- `PUT /api/auth/api-keys/{id}` - Update API key details
- `DELETE /api/auth/api-keys/{id}` - Delete an API key
- `POST /api/auth/api-keys/{id}/revoke` - Revoke an API key

### WhatsApp Session Management
- `GET /api/sessions` - List all WhatsApp sessions
- `POST /api/sessions` - Provision a new WhatsApp session
- `GET /api/sessions/{sessionId}` - Get session connection and engine details
- `DELETE /api/sessions/{sessionId}` - Delete session and credentials
- `POST /api/sessions/{sessionId}/start` - Start session connection and initiate QR/pairing
- `POST /api/sessions/{sessionId}/stop` - Stop session connection
- `POST /api/sessions/{sessionId}/logout` - Log out of WhatsApp (unlink device) and stop session
- `POST /api/sessions/{sessionId}/force-kill` - Force-kill a stuck session process
- `GET /api/sessions/{sessionId}/qr` - Get pairing QR code
- `GET /api/sessions/{sessionId}/screenshot` - Screen capture of WhatsApp Web session
- `POST /api/sessions/{sessionId}/pairing-code` - Request 8-character pairing code by phone number
- `GET /api/sessions/{sessionId}/config` - Get session configuration
- `PATCH /api/sessions/{sessionId}/config` - Update session configuration
- `GET /api/sessions/{sessionId}/proxy` - Get session proxy settings
- `PATCH /api/sessions/{sessionId}/proxy` - Update session proxy settings
- `GET /api/sessions/stats/overview` - Multi-session monitoring overview

### Messaging
- `GET /api/sessions/{sessionId}/messages` - Query session message history
- `POST /api/sessions/{sessionId}/messages/send-text` - Send plain text message
- `POST /api/sessions/{sessionId}/messages/send-image` - Send image attachment
- `POST /api/sessions/{sessionId}/messages/send-video` - Send video attachment
- `POST /api/sessions/{sessionId}/messages/send-audio` - Send audio / voice message (PTT)
- `POST /api/sessions/{sessionId}/messages/send-document` - Send document / file / PDF
- `POST /api/sessions/{sessionId}/messages/send-location` - Send GPS location
- `POST /api/sessions/{sessionId}/messages/send-contact` - Send contact vCard
- `POST /api/sessions/{sessionId}/messages/send-sticker` - Send sticker
- `POST /api/sessions/{sessionId}/messages/send-poll` - Send native WhatsApp poll
- `POST /api/sessions/{sessionId}/messages/send-bulk` - Enqueue batch messages (async)
- `POST /api/sessions/{sessionId}/messages/send-template` - Send stored template message
- `POST /api/sessions/{sessionId}/messages/reply` - Reply directly to a message
- `POST /api/sessions/{sessionId}/messages/react` - Add or remove emoji reaction
- `POST /api/sessions/{sessionId}/messages/edit` - Edit a sent message text
- `POST /api/sessions/{sessionId}/messages/delete` - Revoke / delete message for everyone
- `POST /api/sessions/{sessionId}/messages/forward` - Forward message to another chat
- `POST /api/sessions/{sessionId}/messages/pin` - Pin message in chat
- `POST /api/sessions/{sessionId}/messages/unpin` - Unpin message in chat
- `POST /api/sessions/{sessionId}/messages/star` - Star or unstar a message
- `GET /api/sessions/{sessionId}/messages/{chatId}/history` - Fetch live chat history from WhatsApp
- `GET /api/sessions/{sessionId}/messages/{chatId}/{messageId}/media` - Download stored message media

### Chats & Contacts
- `GET /api/sessions/{sessionId}/chats` - List active chats
- `POST /api/sessions/{sessionId}/chats/read` - Mark chat as read
- `POST /api/sessions/{sessionId}/chats/unread` - Mark chat as unread
- `POST /api/sessions/{sessionId}/chats/archive` - Archive or unarchive chat
- `POST /api/sessions/{sessionId}/chats/mute` - Mute or unmute chat
- `POST /api/sessions/{sessionId}/chats/pin` - Pin or unpin chat in chat list
- `POST /api/sessions/{sessionId}/chats/delete` - Delete chat from chat list
- `POST /api/sessions/{sessionId}/chats/typing` - Send typing or recording presence
- `DELETE /api/sessions/{sessionId}/chats/{chatId}/messages` - Clear all messages in a chat
- `GET /api/sessions/{sessionId}/contacts` - List synced contacts
- `GET /api/sessions/{sessionId}/contacts/{contactId}` - Get contact details
- `PUT /api/sessions/{sessionId}/contacts/{contactId}` - Save or update contact in addressbook
- `DELETE /api/sessions/{sessionId}/contacts/{contactId}` - Remove contact from addressbook
- `GET /api/sessions/{sessionId}/contacts/check/{number}` - Check if phone number exists on WhatsApp
- `GET /api/sessions/{sessionId}/contacts/{contactId}/profile-picture` - Get contact profile picture
- `POST /api/sessions/{sessionId}/contacts/{contactId}/block` - Block contact
- `DELETE /api/sessions/{sessionId}/contacts/{contactId}/block` - Unblock contact

### Groups & Newsletters
- `GET /api/sessions/{sessionId}/groups` - List joined groups
- `POST /api/sessions/{sessionId}/groups` - Create a new group
- `GET /api/sessions/{sessionId}/groups/{groupId}` - Get group metadata and member list
- `POST /api/sessions/{sessionId}/groups/{groupId}/participants` - Add participants to group
- `DELETE /api/sessions/{sessionId}/groups/{groupId}/participants` - Remove participants from group
- `POST /api/sessions/{sessionId}/groups/{groupId}/participants/promote` - Promote member to admin
- `POST /api/sessions/{sessionId}/groups/{groupId}/participants/demote` - Demote member from admin
- `GET /api/sessions/{sessionId}/groups/{groupId}/invite-code` - Get group invite link
- `POST /api/sessions/{sessionId}/groups/{groupId}/invite-code/revoke` - Revoke group invite link
- `GET /api/sessions/{sessionId}/groups/join-info` - Preview group from invite code
- `POST /api/sessions/{sessionId}/groups/join` - Join group via invite code
- `POST /api/sessions/{sessionId}/groups/{groupId}/leave` - Leave group
- `GET /api/sessions/{sessionId}/channels` - List subscribed channels / newsletters
- `POST /api/sessions/{sessionId}/channels` - Create a channel
- `GET /api/sessions/{sessionId}/channels/{channelId}/messages` - Get channel messages

### Webhooks
- `GET /api/webhooks` - List webhooks visible to calling API key
- `POST /api/sessions/{sessionId}/webhooks` - Register webhook for a session
- `GET /api/sessions/{sessionId}/webhooks` - List webhooks for a session
- `GET /api/sessions/{sessionId}/webhooks/{id}` - Get webhook by ID
- `PUT /api/sessions/{sessionId}/webhooks/{id}` - Update webhook configuration
- `DELETE /api/sessions/{sessionId}/webhooks/{id}` - Delete webhook
- `POST /api/sessions/{sessionId}/webhooks/{id}/test` - Test webhook delivery
- `GET /api/webhooks/delivery-failures` - List permanently failed webhook deliveries

### Status / Stories
- `GET /api/sessions/{sessionId}/status` - Get all contact status stories
- `POST /api/sessions/{sessionId}/status/send-text` - Post a text status story
- `POST /api/sessions/{sessionId}/status/send-image` - Post an image status story
- `POST /api/sessions/{sessionId}/status/send-video` - Post a video status story
- `POST /api/sessions/{sessionId}/status/send-voice` - Post an audio status story
- `DELETE /api/sessions/{sessionId}/status/{id}` - Delete own status story

### Templates & Automations
- `GET /api/sessions/{sessionId}/templates` - List message templates
- `POST /api/sessions/{sessionId}/templates` - Create reusable message template
- `GET /api/sessions/{sessionId}/templates/{id}` - Get template by ID
- `PUT /api/sessions/{sessionId}/templates/{id}` - Update template
- `DELETE /api/sessions/{sessionId}/templates/{id}` - Delete template
- `GET /api/sessions/{sessionId}/automation-rules` - List automated keyword rules
- `POST /api/sessions/{sessionId}/automation-rules` - Create auto-reply keyword rule
- `GET /api/sessions/{sessionId}/automation-rules/{ruleId}` - Get automation rule
- `PUT /api/sessions/{sessionId}/automation-rules/{ruleId}` - Update automation rule
- `DELETE /api/sessions/{sessionId}/automation-rules/{ruleId}` - Delete automation rule

### Plugins & Integrations
- `GET /api/plugins` - List installed plugins
- `POST /api/plugins/install` - Install plugin from zip package
- `POST /api/plugins/install-url` - Install plugin from URL
- `POST /api/plugins/{id}/enable` - Enable plugin
- `POST /api/plugins/{id}/disable` - Disable plugin
- `PUT /api/plugins/{id}/config` - Update plugin configuration
- `GET /api/ingress/{pluginId}/{instanceId}/{path}` - Inbound ingress webhook

### Infrastructure (Admin Only)
- `GET /api/infra/status` - Live cluster service health and resource metrics
- `GET /api/infra/config` - Get saved infrastructure configurations (.env)
- `PUT /api/infra/config` - Update infrastructure configuration
- `POST /api/infra/restart` - Trigger server restart with orchestration