API Reference

Base URL, authentication, device selection, request formats and the response envelope for the GOWA REST API.

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 ([e-mail], [e-mail]).

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).