API Reference

Base URL

http://<host>:3000<APP_BASE_PATH>

The default is http://localhost:3000. With APP_BASE_PATH=/gowa, every route moves under /gowa except /health.

Authentication

When APP_BASIC_AUTH is set, every route requires HTTP Basic Auth, except /health, /statics/*, the Chatwoot webhook and the MCP OAuth endpoints. See Authentication.

Device selection

Most routes act on one WhatsApp device. Choose it with the X-Device-Id header (slot ID or JID), or the device_id query parameter. When the server has exactly one device you may omit it; with more, it is required.

Device-scoped	Not device-scoped
`/app/` (except `/app/info`), `/send/`, `/message/`, `/chat/`, `/chats`, `/user/`, `/group/`, `/newsletter/`, `/call/`	`/devices`, `/app/info`, `/health`, `/mcp`, `/chatwoot/`

See Multi-device.

Endpoint groups

Group	Purpose
Devices	Create, list, log in, log out and delete device slots; per-device webhooks and Chatwoot configs.
App	Login (QR, pairing code, passkey), logout, reconnect, status, server info.
Send	Text, media, contact, location, link, poll, presence; scheduling.
Message	React, edit, revoke, delete, read, star, forward, download media.
Chat	List chats and messages; pin, archive, disappearing timer, history request.
User	Profile info, avatar, push name, privacy, contacts, groups, number check.
Group	Create, participants, admins, join requests, settings, invite links.
Newsletter	Followed channels and their messages.
Call	Reject incoming calls.

The endpoint pages in this tab are generated from GOWA’s OpenAPI specification. The authoritative, up-to-date spec is docs/openapi.yaml in the repository.

Requests

JSON bodies: Content-Type: application/json.
File uploads: multipart/form-data.
Phone numbers: digits with country code (628123456789) or a full JID (...@s.whatsapp.net, ...@g.us).

Responses

{
  "code": "SUCCESS",
  "message": "Success",
  "results": {}
}

code is SUCCESS or an error code; results holds the data. See Errors.

Example

curl -u admin:changeme -X POST http://localhost:3000/send/message \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: my-device" \
  -d '{"phone": "628123456789", "message": "Hello from GOWA"}'

Other interfaces

WebSocket at /ws for live dashboard events.
MCP at /mcp for AI agents (MCP server).
Webhooks pushed to your URLs (Webhooks).

WhatsApp API

Overview

Client Examples

Base URL

Authentication

Device selection

Endpoint groups

Requests

Responses

Example

Other interfaces

​Base URL

​Authentication

​Device selection

​Endpoint groups

​Requests

​Responses

​Example

​Other interfaces

Base URL

Authentication

Device selection

Endpoint groups

Requests

Responses

Example

Other interfaces