> For the complete documentation index, see [llms.txt](https://docs.openalgo.in/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openalgo.in/api-documentation/v1/utilities-api/whatsapp.md).

# WhatsApp

Send a WhatsApp message — text, image, document, or any combination — to yourself, a single recipient, or a small group (up to 5). This is the single trader-facing send endpoint; everything you might do with `wa.send()` in a script is exposed here.

### Endpoint URL

```http
Local Host   :  POST http://127.0.0.1:5000/api/v1/whatsapp/notify
Ngrok Domain :  POST https://<your-ngrok-domain>.ngrok-free.app/api/v1/whatsapp/notify
Custom Domain:  POST https://<your-custom-domain>/api/v1/whatsapp/notify
```

### Sample API Requests

#### Send to yourself (paired device's own number)

```json
{
  "apikey": "<your_app_apikey>",
  "self": true,
  "message": "Build #482 finished in 1m 23s"
}
```

#### Send to a single phone number

```json
{
  "apikey": "<your_app_apikey>",
  "phone": "919876543210",
  "message": "Order placed: BUY RELIANCE x 10 @ MARKET"
}
```

#### Send to a linked OpenAlgo user

```json
{
  "apikey": "<your_app_apikey>",
  "username": "rajan",
  "message": "Daily summary attached",
  "document_path": "/srv/reports/2026-05-17.pdf",
  "filename": "summary.pdf"
}
```

#### Small broadcast (max 5 recipients)

```json
{
  "apikey": "<your_app_apikey>",
  "phones": ["919876543210", "919812345678", "919900112233"],
  "image_path": "/srv/charts/nifty.png",
  "caption": "NIFTY EOD chart"
}
```

### Sample cURL Request

```bash
curl -X POST http://127.0.0.1:5000/api/v1/whatsapp/notify \
  -H 'Content-Type: application/json' \
  -d '{
    "apikey": "<your_app_apikey>",
    "self": true,
    "message": "Alert from OpenAlgo"
  }'
```

### Sample API Response

#### Fire-and-forget (default)

```json
{
  "status": "success",
  "message": "Queued for 1 recipient(s)",
  "queued": 1
}
```

#### `wait_for_delivery: true`

```json
{
  "status": "success",
  "message": "Delivered to 2, failed 0",
  "data": {
    "sent":    ["919876543210@s.whatsapp.net", "919812345678@s.whatsapp.net"],
    "failed":  [],
    "skipped": 0
  }
}
```

### Request Body

| Parameter           | Type             | Description                                                                                       |
| ------------------- | ---------------- | ------------------------------------------------------------------------------------------------- |
| `apikey`            | string           | OpenAlgo API key. **Mandatory.**                                                                  |
| `self`              | boolean          | If `true`, send to the paired device's own number.                                                |
| `username`          | string           | OpenAlgo username — resolves through the linked-users table.                                      |
| `phone`             | string           | Single E.164 digit string (e.g. `919876543210`).                                                  |
| `phones`            | array of strings | Up to 5 E.164 digit strings (small broadcast). Anything beyond 5 is dropped.                      |
| `message`           | string           | Text body. Optional if `image_path` or `document_path` is set. Max 4096 chars.                    |
| `image_path`        | string           | Server-local path to an image file.                                                               |
| `document_path`     | string           | Server-local path to a document file (PDF, CSV, etc.).                                            |
| `caption`           | string           | Caption attached to the image. For documents, sent as a follow-up text.                           |
| `filename`          | string           | Override the document's display name on the recipient's device.                                   |
| `wait_for_delivery` | boolean          | Default `false`. When `true`, block until wars returns and include per-recipient delivery report. |

Exactly one recipient form is required: `self`, `username`, `phone`, or `phones`. Combining is not supported.

### Response Fields (async)

| Field     | Type   | Description                                       |
| --------- | ------ | ------------------------------------------------- |
| `status`  | string | `success` or `error`                              |
| `message` | string | Human-readable summary                            |
| `queued`  | int    | Number of recipients dispatched to the alert pool |

### Response Fields (`wait_for_delivery: true`)

`data` contains the per-recipient report from `send_sync`:

| Field     | Type  | Description                                  |
| --------- | ----- | -------------------------------------------- |
| `sent`    | array | JIDs that wars confirmed accepted            |
| `failed`  | array | `[{ "to": "<jid>", "error": "<msg>" }, ...]` |
| `skipped` | int   | Recipients trimmed by the 5-recipient cap    |

### Notes

* The bot must be paired and connected for `notify` to deliver. Connect / disconnect lives on the `/whatsapp` admin web UI; this REST namespace intentionally does not expose those controls. If the bot is paused, the message is queued in `whatsapp_notification_queue` for a later retry.
* Image / document paths are read from the OpenAlgo server's filesystem, not uploaded by the API call. Place files in a server-readable location first.
* **Attachment path allowlist.** For security, only paths inside the directories listed in the `WHATSAPP_ATTACHMENT_ROOTS` env var are accepted. The default (when unset) is `<openalgo>/db/attachments/` only. Anything outside the allowlist returns `400 image_path is not allowed`. Set `WHATSAPP_ATTACHMENT_ROOTS` to a comma-separated list of absolute directories to expand it. Paths containing `..`, paths under sensitive system trees (`/etc`, `/proc`, `/sys`, `/root`, `/var/log`, `C:\Windows`, `C:\Users\Default`), and symlinks that resolve outside the allowlist are always rejected.
* The 5-recipient cap is a ToS-safety guardrail — bulk-messaging patterns can get the paired device unlinked by Meta. Use the official WhatsApp Business API for genuine mass-messaging use cases.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.openalgo.in/api-documentation/v1/utilities-api/whatsapp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.