Sending Messages

All examples assume Basic Auth admin:changeme, a slot called my-device, and GOWA on localhost:3000.

export GOWA=http://localhost:3000
export AUTH=admin:changeme
export DEVICE=my-device

Recipients

phone accepts:

A number with country code, no +, spaces or dashes: 628123456789 (a leading + is stripped).
A user JID: 628123456789@s.whatsapp.net.
A group JID: 120363025246125486@g.us.
status@broadcast to post a status update.

With WHATSAPP_ACCOUNT_VALIDATION=true (default), GOWA checks that a number is on WhatsApp before sending. Check one yourself with GET /user/check?phone=628123456789.

Text

curl -u $AUTH -X POST $GOWA/send/message \
  -H "Content-Type: application/json" -H "X-Device-Id: $DEVICE" \
  -d '{"phone": "628123456789", "message": "Hello!"}'

Optional fields:

Field	Description
`reply_message_id`	Quote an earlier message.
`mentions`	Phone numbers to mention, for example `["628111111111"]`; `"@everyone"` mentions every group member. Mentions do not need `@` in the text.
`is_forwarded`	Show the “Forwarded” label.
`duration`	Disappearing-message timer in seconds: `0`, `86400` (24 h), `604800` (7 d) or `7776000` (90 d).
`allow_reshare`	Status posts only (`phone` = `status@broadcast`).

Successful sends return the WhatsApp message ID:

{"code": "SUCCESS", "message": "Success", "results": {"message_id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "status": "Message sent to 628123456789 (server timestamp: ...)"}}

Media

Media endpoints take multipart/form-data. Upload a file, or pass a URL that GOWA downloads (*_url).

curl -u $AUTH -X POST $GOWA/send/image -H "X-Device-Id: $DEVICE" \
  -F phone=628123456789 \
  -F caption="Product photo" \
  -F image=@photo.jpg \
  -F compress=true

curl -u $AUTH -X POST $GOWA/send/image -H "X-Device-Id: $DEVICE" \
  -F phone=628123456789 \
  -F image_url=https://example.com/photo.jpg

curl -u $AUTH -X POST $GOWA/send/file -H "X-Device-Id: $DEVICE" \
  -F phone=628123456789 \
  -F caption="Invoice" \
  -F file=@invoice.pdf

curl -u $AUTH -X POST $GOWA/send/video -H "X-Device-Id: $DEVICE" \
  -F phone=628123456789 \
  -F caption="Demo" \
  -F video=@demo.mp4

curl -u $AUTH -X POST $GOWA/send/audio -H "X-Device-Id: $DEVICE" \
  -F phone=628123456789 \
  -F audio=@note.ogg \
  -F ptt=true

curl -u $AUTH -X POST $GOWA/send/sticker -H "X-Device-Id: $DEVICE" \
  -F phone=628123456789 \
  -F sticker=@cat.png

Endpoint	File field / URL field	Extra fields
`/send/image`	`image` / `image_url`	`caption`, `view_once`, `compress`, `hd`, `mentions`
`/send/video`	`video` / `video_url`	`caption`, `view_once`, `compress`, `hd`, `gif_playback`, `mentions`
`/send/file`	`file` / `file_url`	`caption`, `mentions`
`/send/audio`	`audio` / `audio_url`	`ptt` (send as voice note)
`/send/sticker`	`sticker` / `sticker_url`	JPG, PNG, WebP or GIF; converted to WebP

All media endpoints also accept reply_message_id, is_forwarded and duration. See Media handling for size limits and formats.

Contact, location, link, poll

curl -u $AUTH -X POST $GOWA/send/contact \
  -H "Content-Type: application/json" -H "X-Device-Id: $DEVICE" \
  -d '{"phone": "628123456789", "contact_name": "Jane Doe", "contact_phone": "628987654321"}'

curl -u $AUTH -X POST $GOWA/send/location \
  -H "Content-Type: application/json" -H "X-Device-Id: $DEVICE" \
  -d '{"phone": "628123456789", "latitude": "-6.200000", "longitude": "106.816666"}'

curl -u $AUTH -X POST $GOWA/send/link \
  -H "Content-Type: application/json" -H "X-Device-Id: $DEVICE" \
  -d '{"phone": "628123456789", "link": "https://github.com", "caption": "Check this out"}'

curl -u $AUTH -X POST $GOWA/send/poll \
  -H "Content-Type: application/json" -H "X-Device-Id: $DEVICE" \
  -d '{"phone": "628123456789", "question": "Lunch?", "options": ["Pizza", "Sushi", "Salad"], "max_answer": 1}'

Presence and typing

# account-wide presence: available | unavailable
curl -u $AUTH -X POST $GOWA/send/presence \
  -H "Content-Type: application/json" -H "X-Device-Id: $DEVICE" \
  -d '{"type": "available"}'

# typing indicator in one chat: start | stop
curl -u $AUTH -X POST $GOWA/send/chat-presence \
  -H "Content-Type: application/json" -H "X-Device-Id: $DEVICE" \
  -d '{"phone": "628123456789", "action": "start"}'

After sending

Task	Endpoint
Edit	`POST /message/{message_id}/update` with `phone`, `message`
React	`POST /message/{message_id}/reaction` with `phone`, `emoji`
Delete for everyone	`POST /message/{message_id}/revoke` with `phone`
Delete for me	`POST /message/{message_id}/delete` with `phone`
Forward	`POST /message/{message_id}/forward` with `phone` (destination). The source message must be in GOWA’s local chat storage.
Star / unstar	`POST /message/{message_id}/star`, `/unstar` with `phone`

Send later

Add scheduled_at and timezone to any send request to schedule it instead. See Scheduled sends.

Sending to many recipients

GOWA has no broadcast endpoint. Loop over recipients in your code, send one request at a time with a delay, and stop on WA_REACHOUT_TIMELOCK errors. Read Sending limits before sending in volume.

Getting Started

Core Concepts

Usage Examples

Integrations

Advanced

Recipients

Text

Media

Contact, location, link, poll

Presence and typing

After sending

Send later

Sending to many recipients

​Recipients

​Text

​Media

​Contact, location, link, poll

​Presence and typing

​After sending

​Send later

​Sending to many recipients

Recipients

Text

Media

Contact, location, link, poll

Presence and typing

After sending

Send later

Sending to many recipients