> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sending Messages

> Send text, media, contacts, locations, links, polls and presence with the /send endpoints.

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

```bash theme={null}
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

```bash theme={null}
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:

```json theme={null}
{"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`).

```bash Image theme={null}
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
```

```bash Image from URL theme={null}
curl -u $AUTH -X POST $GOWA/send/image -H "X-Device-Id: $DEVICE" \
  -F phone=628123456789 \
  -F image_url=https://example.com/photo.jpg
```

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

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

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

```bash Sticker theme={null}
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](https://gowa-docs.mintlify.site/examples/media-handling.md) for size limits and formats.

## Contact, location, link, poll

```bash Contact theme={null}
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"}'
```

```bash Location theme={null}
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"}'
```

```bash Link theme={null}
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"}'
```

```bash Poll theme={null}
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

```bash theme={null}
# 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](https://gowa-docs.mintlify.site/examples/scheduled-sends.md).

## 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](https://gowa-docs.mintlify.site/advanced/rate-limiting.md) before sending in volume.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.