# Sending messages

> Docs index: https://wahasend.com/llms.txt · Everything in one file: https://wahasend.com/docs.md · API base URL: https://app.wahasend.com/api/v1

One text message comes with every product. Photos, files, voice notes, contacts, locations, links, polls, forwarding, editing and deleting come with **Developer** (feature `media`).

<a id="alert-send"></a>

### Send a text message

`POST /api/v1/alert/send`

Queues one text message. It goes out a few seconds later with a typing indicator, like a person would send it (`high` priority skips that). The number is checked on WhatsApp first.

- Unlocked by: every product (`send`)
- Per-number key: yes

> Follow the message with `GET /messages` or the `message.*` [webhook events](https://wahasend.com/docs/webhooks.md). `messageId` is WahaSend's id, not WhatsApp's. `containerId` is the number it is queued on; with [several numbers](https://wahasend.com/docs/phone-numbers.md#several-numbers) it can move to another number of the group if that one goes down, and `GET /messages` and the webhooks then show the number that really sent it.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phone` | string | yes | International phone number (`+22212345678`) or a WhatsApp id ending in `@lid`. See [Phone numbers](https://wahasend.com/docs/phone-numbers.md). |
| `message` | string | yes | The text, 1–4096 characters. Links get a preview. |
| `priority` | "high" \| "normal" \| "low" | no | Default `normal`. `high` jumps the queue and skips the typing simulation; use it for time-critical alerts only. |
| `containerId` | uuid | no | Which of your WhatsApp numbers to use; it always wins. Default: your default number (else any connected one), or a number of the group when [several numbers](https://wahasend.com/docs/phone-numbers.md#several-numbers) is on. Ignored with a per-number key, which always uses its own number. |

**Example**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/alert/send \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+22212345678",
  "message": "Your order #1042 is ready for pickup.",
  "priority": "normal"
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/alert/send', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "phone": "+22212345678",
    "message": "Your order #1042 is ready for pickup.",
    "priority": "normal"
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/alert/send",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "phone": "+22212345678",
        "message": "Your order #1042 is ready for pickup.",
        "priority": "normal",
    },
)
print(r.json())
```

**Response 201**

```json
{
  "success": true,
  "messageId": "4f0c6a1e-2b7d-4c1a-9e35-7d8f2a6b1c90",
  "status": "queued",
  "priority": "normal",
  "containerId": "6d2b9c1e-8f4a-4e37-a5c2-1b9e7d3f0a64"
}
```

**Errors to expect**

- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NUMBER_NOT_ON_WHATSAPP`](https://wahasend.com/docs/errors.md#number_not_on_whatsapp) (400): This number is not on WhatsApp.
- [`NUMBER_VALIDATION_UNAVAILABLE`](https://wahasend.com/docs/errors.md#number_validation_unavailable) (503): Numbers cannot be checked right now. Try again shortly.
- [`NO_SESSION_CONFIGURED`](https://wahasend.com/docs/errors.md#no_session_configured) (400): This account has no connected WhatsApp number.
- [`NOT_FOUND`](https://wahasend.com/docs/errors.md#not_found) (404): Not found.

<a id="alert-send-image"></a>

### Send a photo

`POST /api/v1/alert/send-image`

Sends an image from a link, with an optional caption.

- Unlocked by: Developer (`media`)
- Per-number key: yes

> Sent right away through your number (no queue, no typing simulation) and recorded in `GET /messages` as `sent`, so `message.delivered` / `message.read` [events](https://wahasend.com/docs/webhooks.md) follow. `messageId` is WahaSend's id (use it to edit, delete or forward the message); `wahaMessageId` is WhatsApp's.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phone` | string | yes | International phone number (`+22212345678`) or a WhatsApp id ending in `@lid`. See [Phone numbers](https://wahasend.com/docs/phone-numbers.md). |
| `imageUrl` | string (URL) | yes | Link to the image (JPEG, PNG or WebP). Must be a public address: private and local addresses are refused. |
| `caption` | string | no | Text under the file, up to 1024 characters. |
| `filename` | string | no | File name shown to the contact, up to 255 characters. |
| `mimetype` | string | no | MIME type, e.g. `application/pdf` (up to 100 characters). Guessed when missing. |
| `containerId` | uuid | no | Which of your WhatsApp numbers to use; it always wins. Default: your default number (else any connected one), or a number of the group when [several numbers](https://wahasend.com/docs/phone-numbers.md#several-numbers) is on. Ignored with a per-number key, which always uses its own number. |

**Example**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/alert/send-image \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+22212345678",
  "imageUrl": "https://example.com/menu.jpg",
  "caption": "Today'\''s menu"
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/alert/send-image', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "phone": "+22212345678",
    "imageUrl": "https://example.com/menu.jpg",
    "caption": "Today's menu"
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/alert/send-image",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "phone": "+22212345678",
        "imageUrl": "https://example.com/menu.jpg",
        "caption": "Today's menu",
    },
)
print(r.json())
```

**Response 201**

```json
{
  "success": true,
  "messageId": "3d7f1b2c-5e8a-4c69-b0d3-8f2a6c4e1b95",
  "wahaMessageId": "true_22212345678@c.us_3EB0C767D26A1D2E5A8F",
  "containerId": "6d2b9c1e-8f4a-4e37-a5c2-1b9e7d3f0a64"
}
```

**Errors to expect**

- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NO_SESSION_CONFIGURED`](https://wahasend.com/docs/errors.md#no_session_configured) (400): This account has no connected WhatsApp number.
- [`WAHA_ERROR`](https://wahasend.com/docs/errors.md#waha_error) (502): WhatsApp could not complete the request. Try again.
- [`WAHA_SESSION_ERROR`](https://wahasend.com/docs/errors.md#waha_session_error) (503): WhatsApp is not connected.
- [`PRODUCT_REQUIRED`](https://wahasend.com/docs/errors.md#product_required) (403): This feature is not included in your products.

<a id="alert-send-video"></a>

### Send a video

`POST /api/v1/alert/send-video`

Sends an MP4 video from a link.

- Unlocked by: Developer (`media`)
- Per-number key: yes

> Sent right away through your number (no queue, no typing simulation) and recorded in `GET /messages` as `sent`, so `message.delivered` / `message.read` [events](https://wahasend.com/docs/webhooks.md) follow. `messageId` is WahaSend's id (use it to edit, delete or forward the message); `wahaMessageId` is WhatsApp's.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phone` | string | yes | International phone number (`+22212345678`) or a WhatsApp id ending in `@lid`. See [Phone numbers](https://wahasend.com/docs/phone-numbers.md). |
| `videoUrl` | string (URL) | yes | Link to the MP4 file. Must be a public address: private and local addresses are refused. |
| `caption` | string | no | Text under the file, up to 1024 characters. |
| `filename` | string | no | File name shown to the contact, up to 255 characters. |
| `mimetype` | string | no | MIME type, e.g. `application/pdf` (up to 100 characters). Guessed when missing. |
| `containerId` | uuid | no | Which of your WhatsApp numbers to use; it always wins. Default: your default number (else any connected one), or a number of the group when [several numbers](https://wahasend.com/docs/phone-numbers.md#several-numbers) is on. Ignored with a per-number key, which always uses its own number. |

**Example**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/alert/send-video \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+22212345678",
  "videoUrl": "https://example.com/demo.mp4",
  "caption": "How it works"
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/alert/send-video', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "phone": "+22212345678",
    "videoUrl": "https://example.com/demo.mp4",
    "caption": "How it works"
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/alert/send-video",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "phone": "+22212345678",
        "videoUrl": "https://example.com/demo.mp4",
        "caption": "How it works",
    },
)
print(r.json())
```

**Response 201**

```json
{
  "success": true,
  "messageId": "3d7f1b2c-5e8a-4c69-b0d3-8f2a6c4e1b95",
  "wahaMessageId": "true_22212345678@c.us_3EB0C767D26A1D2E5A8F",
  "containerId": "6d2b9c1e-8f4a-4e37-a5c2-1b9e7d3f0a64"
}
```

**Errors to expect**

- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NO_SESSION_CONFIGURED`](https://wahasend.com/docs/errors.md#no_session_configured) (400): This account has no connected WhatsApp number.
- [`WAHA_ERROR`](https://wahasend.com/docs/errors.md#waha_error) (502): WhatsApp could not complete the request. Try again.
- [`WAHA_SESSION_ERROR`](https://wahasend.com/docs/errors.md#waha_session_error) (503): WhatsApp is not connected.
- [`PRODUCT_REQUIRED`](https://wahasend.com/docs/errors.md#product_required) (403): This feature is not included in your products.

<a id="alert-send-file"></a>

### Send a file

`POST /api/v1/alert/send-file`

Sends a document (PDF, spreadsheet…) from a link.

- Unlocked by: Developer (`media`)
- Per-number key: yes

> Sent right away through your number (no queue, no typing simulation) and recorded in `GET /messages` as `sent`, so `message.delivered` / `message.read` [events](https://wahasend.com/docs/webhooks.md) follow. `messageId` is WahaSend's id (use it to edit, delete or forward the message); `wahaMessageId` is WhatsApp's.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phone` | string | yes | International phone number (`+22212345678`) or a WhatsApp id ending in `@lid`. See [Phone numbers](https://wahasend.com/docs/phone-numbers.md). |
| `fileUrl` | string (URL) | yes | Link to the file. Must be a public address: private and local addresses are refused. |
| `filename` | string | no | File name shown to the contact, up to 255 characters. |
| `caption` | string | no | Text under the file, up to 1024 characters. |
| `mimetype` | string | no | MIME type, e.g. `application/pdf` (up to 100 characters). Guessed when missing. |
| `containerId` | uuid | no | Which of your WhatsApp numbers to use; it always wins. Default: your default number (else any connected one), or a number of the group when [several numbers](https://wahasend.com/docs/phone-numbers.md#several-numbers) is on. Ignored with a per-number key, which always uses its own number. |

**Example**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/alert/send-file \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+22212345678",
  "fileUrl": "https://example.com/invoice-1042.pdf",
  "filename": "invoice-1042.pdf",
  "caption": "Your invoice"
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/alert/send-file', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "phone": "+22212345678",
    "fileUrl": "https://example.com/invoice-1042.pdf",
    "filename": "invoice-1042.pdf",
    "caption": "Your invoice"
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/alert/send-file",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "phone": "+22212345678",
        "fileUrl": "https://example.com/invoice-1042.pdf",
        "filename": "invoice-1042.pdf",
        "caption": "Your invoice",
    },
)
print(r.json())
```

**Response 201**

```json
{
  "success": true,
  "messageId": "3d7f1b2c-5e8a-4c69-b0d3-8f2a6c4e1b95",
  "wahaMessageId": "true_22212345678@c.us_3EB0C767D26A1D2E5A8F",
  "containerId": "6d2b9c1e-8f4a-4e37-a5c2-1b9e7d3f0a64"
}
```

**Errors to expect**

- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NO_SESSION_CONFIGURED`](https://wahasend.com/docs/errors.md#no_session_configured) (400): This account has no connected WhatsApp number.
- [`WAHA_ERROR`](https://wahasend.com/docs/errors.md#waha_error) (502): WhatsApp could not complete the request. Try again.
- [`WAHA_SESSION_ERROR`](https://wahasend.com/docs/errors.md#waha_session_error) (503): WhatsApp is not connected.
- [`PRODUCT_REQUIRED`](https://wahasend.com/docs/errors.md#product_required) (403): This feature is not included in your products.

<a id="alert-send-voice"></a>

### Send a voice note

`POST /api/v1/alert/send-voice`

Sends an audio file as a voice note. Use OGG/Opus for it to play as a voice note.

- Unlocked by: Developer (`media`)
- Per-number key: yes

> Sent right away through your number (no queue, no typing simulation) and recorded in `GET /messages` as `sent`, so `message.delivered` / `message.read` [events](https://wahasend.com/docs/webhooks.md) follow. `messageId` is WahaSend's id (use it to edit, delete or forward the message); `wahaMessageId` is WhatsApp's.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phone` | string | yes | International phone number (`+22212345678`) or a WhatsApp id ending in `@lid`. See [Phone numbers](https://wahasend.com/docs/phone-numbers.md). |
| `audioUrl` | string (URL) | yes | Link to the audio file. Must be a public address: private and local addresses are refused. |
| `containerId` | uuid | no | Which of your WhatsApp numbers to use; it always wins. Default: your default number (else any connected one), or a number of the group when [several numbers](https://wahasend.com/docs/phone-numbers.md#several-numbers) is on. Ignored with a per-number key, which always uses its own number. |

**Example**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/alert/send-voice \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+22212345678",
  "audioUrl": "https://example.com/welcome.ogg"
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/alert/send-voice', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "phone": "+22212345678",
    "audioUrl": "https://example.com/welcome.ogg"
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/alert/send-voice",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "phone": "+22212345678",
        "audioUrl": "https://example.com/welcome.ogg",
    },
)
print(r.json())
```

**Response 201**

```json
{
  "success": true,
  "messageId": "3d7f1b2c-5e8a-4c69-b0d3-8f2a6c4e1b95",
  "wahaMessageId": "true_22212345678@c.us_3EB0C767D26A1D2E5A8F",
  "containerId": "6d2b9c1e-8f4a-4e37-a5c2-1b9e7d3f0a64"
}
```

**Errors to expect**

- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NO_SESSION_CONFIGURED`](https://wahasend.com/docs/errors.md#no_session_configured) (400): This account has no connected WhatsApp number.
- [`WAHA_ERROR`](https://wahasend.com/docs/errors.md#waha_error) (502): WhatsApp could not complete the request. Try again.
- [`WAHA_SESSION_ERROR`](https://wahasend.com/docs/errors.md#waha_session_error) (503): WhatsApp is not connected.
- [`PRODUCT_REQUIRED`](https://wahasend.com/docs/errors.md#product_required) (403): This feature is not included in your products.

<a id="alert-send-contact"></a>

### Share contacts

`POST /api/v1/alert/send-contact`

Sends 1 to 10 contact cards.

- Unlocked by: Developer (`media`)
- Per-number key: yes

> Sent right away through your number (no queue, no typing simulation) and recorded in `GET /messages` as `sent`, so `message.delivered` / `message.read` [events](https://wahasend.com/docs/webhooks.md) follow. `messageId` is WahaSend's id (use it to edit, delete or forward the message); `wahaMessageId` is WhatsApp's.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phone` | string | yes | International phone number (`+22212345678`) or a WhatsApp id ending in `@lid`. See [Phone numbers](https://wahasend.com/docs/phone-numbers.md). |
| `contacts` | array | yes | 1–10 contacts. |
| `contacts[].fullName` | string | yes | Name, 1–255 characters. |
| `contacts[].phoneNumber` | string | yes | Their number, 5–20 characters. |
| `containerId` | uuid | no | Which of your WhatsApp numbers to use; it always wins. Default: your default number (else any connected one), or a number of the group when [several numbers](https://wahasend.com/docs/phone-numbers.md#several-numbers) is on. Ignored with a per-number key, which always uses its own number. |

**Example**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/alert/send-contact \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+22212345678",
  "contacts": [
    {
      "fullName": "Front desk",
      "phoneNumber": "+22245250000"
    }
  ]
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/alert/send-contact', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "phone": "+22212345678",
    "contacts": [
      {
        "fullName": "Front desk",
        "phoneNumber": "+22245250000"
      }
    ]
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/alert/send-contact",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "phone": "+22212345678",
        "contacts": [
            {
                "fullName": "Front desk",
                "phoneNumber": "+22245250000",
            },
        ],
    },
)
print(r.json())
```

**Response 201**

```json
{
  "success": true,
  "messageId": "3d7f1b2c-5e8a-4c69-b0d3-8f2a6c4e1b95",
  "wahaMessageId": "true_22212345678@c.us_3EB0C767D26A1D2E5A8F",
  "containerId": "6d2b9c1e-8f4a-4e37-a5c2-1b9e7d3f0a64"
}
```

**Errors to expect**

- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NO_SESSION_CONFIGURED`](https://wahasend.com/docs/errors.md#no_session_configured) (400): This account has no connected WhatsApp number.
- [`WAHA_ERROR`](https://wahasend.com/docs/errors.md#waha_error) (502): WhatsApp could not complete the request. Try again.
- [`WAHA_SESSION_ERROR`](https://wahasend.com/docs/errors.md#waha_session_error) (503): WhatsApp is not connected.
- [`PRODUCT_REQUIRED`](https://wahasend.com/docs/errors.md#product_required) (403): This feature is not included in your products.

<a id="alert-send-location"></a>

### Send a location

`POST /api/v1/alert/send-location`

Sends a map pin.

- Unlocked by: Developer (`media`)
- Per-number key: yes

> Sent right away through your number (no queue, no typing simulation) and recorded in `GET /messages` as `sent`, so `message.delivered` / `message.read` [events](https://wahasend.com/docs/webhooks.md) follow. `messageId` is WahaSend's id (use it to edit, delete or forward the message); `wahaMessageId` is WhatsApp's.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phone` | string | yes | International phone number (`+22212345678`) or a WhatsApp id ending in `@lid`. See [Phone numbers](https://wahasend.com/docs/phone-numbers.md). |
| `latitude` | number | yes | −90 to 90. |
| `longitude` | number | yes | −180 to 180. |
| `title` | string | no | Place name, up to 255 characters. |
| `address` | string | no | Address, up to 500 characters. |
| `containerId` | uuid | no | Which of your WhatsApp numbers to use; it always wins. Default: your default number (else any connected one), or a number of the group when [several numbers](https://wahasend.com/docs/phone-numbers.md#several-numbers) is on. Ignored with a per-number key, which always uses its own number. |

**Example**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/alert/send-location \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+22212345678",
  "latitude": 18.0858,
  "longitude": -15.9785,
  "title": "Our shop",
  "address": "Tevragh Zeina, Nouakchott"
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/alert/send-location', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "phone": "+22212345678",
    "latitude": 18.0858,
    "longitude": -15.9785,
    "title": "Our shop",
    "address": "Tevragh Zeina, Nouakchott"
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/alert/send-location",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "phone": "+22212345678",
        "latitude": 18.0858,
        "longitude": -15.9785,
        "title": "Our shop",
        "address": "Tevragh Zeina, Nouakchott",
    },
)
print(r.json())
```

**Response 201**

```json
{
  "success": true,
  "messageId": "3d7f1b2c-5e8a-4c69-b0d3-8f2a6c4e1b95",
  "wahaMessageId": "true_22212345678@c.us_3EB0C767D26A1D2E5A8F",
  "containerId": "6d2b9c1e-8f4a-4e37-a5c2-1b9e7d3f0a64"
}
```

**Errors to expect**

- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NO_SESSION_CONFIGURED`](https://wahasend.com/docs/errors.md#no_session_configured) (400): This account has no connected WhatsApp number.
- [`WAHA_ERROR`](https://wahasend.com/docs/errors.md#waha_error) (502): WhatsApp could not complete the request. Try again.
- [`WAHA_SESSION_ERROR`](https://wahasend.com/docs/errors.md#waha_session_error) (503): WhatsApp is not connected.
- [`PRODUCT_REQUIRED`](https://wahasend.com/docs/errors.md#product_required) (403): This feature is not included in your products.

<a id="alert-send-link"></a>

### Send a link with a custom preview

`POST /api/v1/alert/send-link`

Sends text with a link preview you choose (title, description, image).

- Unlocked by: Developer (`media`)
- Per-number key: yes

> Sent right away through your number (no queue, no typing simulation) and recorded in `GET /messages` as `sent`, so `message.delivered` / `message.read` [events](https://wahasend.com/docs/webhooks.md) follow. `messageId` is WahaSend's id (use it to edit, delete or forward the message); `wahaMessageId` is WhatsApp's.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phone` | string | yes | International phone number (`+22212345678`) or a WhatsApp id ending in `@lid`. See [Phone numbers](https://wahasend.com/docs/phone-numbers.md). |
| `text` | string | yes | Message text, 1–4096 characters. Include the link in it. |
| `previewUrl` | string (URL) | yes | The link the preview is for. Must be a public address: private and local addresses are refused. |
| `previewTitle` | string | yes | Preview title, 1–255 characters. |
| `previewDescription` | string | no | Up to 500 characters. |
| `previewImageUrl` | string (URL) | no | Public link to the preview image. |
| `containerId` | uuid | no | Which of your WhatsApp numbers to use; it always wins. Default: your default number (else any connected one), or a number of the group when [several numbers](https://wahasend.com/docs/phone-numbers.md#several-numbers) is on. Ignored with a per-number key, which always uses its own number. |

**Example**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/alert/send-link \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+22212345678",
  "text": "Track your order: https://example.com/t/1042",
  "previewUrl": "https://example.com/t/1042",
  "previewTitle": "Order #1042"
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/alert/send-link', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "phone": "+22212345678",
    "text": "Track your order: https://example.com/t/1042",
    "previewUrl": "https://example.com/t/1042",
    "previewTitle": "Order #1042"
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/alert/send-link",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "phone": "+22212345678",
        "text": "Track your order: https://example.com/t/1042",
        "previewUrl": "https://example.com/t/1042",
        "previewTitle": "Order #1042",
    },
)
print(r.json())
```

**Response 201**

```json
{
  "success": true,
  "messageId": "3d7f1b2c-5e8a-4c69-b0d3-8f2a6c4e1b95",
  "wahaMessageId": "true_22212345678@c.us_3EB0C767D26A1D2E5A8F",
  "containerId": "6d2b9c1e-8f4a-4e37-a5c2-1b9e7d3f0a64"
}
```

**Errors to expect**

- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NO_SESSION_CONFIGURED`](https://wahasend.com/docs/errors.md#no_session_configured) (400): This account has no connected WhatsApp number.
- [`WAHA_ERROR`](https://wahasend.com/docs/errors.md#waha_error) (502): WhatsApp could not complete the request. Try again.
- [`WAHA_SESSION_ERROR`](https://wahasend.com/docs/errors.md#waha_session_error) (503): WhatsApp is not connected.
- [`PRODUCT_REQUIRED`](https://wahasend.com/docs/errors.md#product_required) (403): This feature is not included in your products.

<a id="alert-send-poll"></a>

### Send a poll

`POST /api/v1/alert/send-poll`

Sends a poll with 2 to 12 options. Votes arrive as `poll.vote` [webhook events](https://wahasend.com/docs/webhooks.md).

- Unlocked by: Developer (`media`)
- Per-number key: yes

> Sent right away through your number (no queue, no typing simulation) and recorded in `GET /messages` as `sent`, so `message.delivered` / `message.read` [events](https://wahasend.com/docs/webhooks.md) follow. `messageId` is WahaSend's id (use it to edit, delete or forward the message); `wahaMessageId` is WhatsApp's.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phone` | string | yes | International phone number (`+22212345678`) or a WhatsApp id ending in `@lid`. See [Phone numbers](https://wahasend.com/docs/phone-numbers.md). |
| `question` | string | yes | 1–255 characters. |
| `options` | string[] | yes | 2–12 options, each 1–100 characters. |
| `multipleAnswers` | boolean | no | Allow several answers. Default `false`. |
| `containerId` | uuid | no | Which of your WhatsApp numbers to use; it always wins. Default: your default number (else any connected one), or a number of the group when [several numbers](https://wahasend.com/docs/phone-numbers.md#several-numbers) is on. Ignored with a per-number key, which always uses its own number. |

**Example**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/alert/send-poll \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+22212345678",
  "question": "Which delivery day suits you?",
  "options": [
    "Monday",
    "Wednesday",
    "Friday"
  ]
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/alert/send-poll', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "phone": "+22212345678",
    "question": "Which delivery day suits you?",
    "options": [
      "Monday",
      "Wednesday",
      "Friday"
    ]
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/alert/send-poll",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "phone": "+22212345678",
        "question": "Which delivery day suits you?",
        "options": [
            "Monday",
            "Wednesday",
            "Friday",
        ],
    },
)
print(r.json())
```

**Response 201**

```json
{
  "success": true,
  "messageId": "3d7f1b2c-5e8a-4c69-b0d3-8f2a6c4e1b95",
  "wahaMessageId": "true_22212345678@c.us_3EB0C767D26A1D2E5A8F",
  "containerId": "6d2b9c1e-8f4a-4e37-a5c2-1b9e7d3f0a64"
}
```

**Errors to expect**

- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NO_SESSION_CONFIGURED`](https://wahasend.com/docs/errors.md#no_session_configured) (400): This account has no connected WhatsApp number.
- [`WAHA_ERROR`](https://wahasend.com/docs/errors.md#waha_error) (502): WhatsApp could not complete the request. Try again.
- [`WAHA_SESSION_ERROR`](https://wahasend.com/docs/errors.md#waha_session_error) (503): WhatsApp is not connected.
- [`PRODUCT_REQUIRED`](https://wahasend.com/docs/errors.md#product_required) (403): This feature is not included in your products.

<a id="alert-forward"></a>

### Forward a message

`POST /api/v1/alert/forward`

Forwards a message your number has to another chat. The recipient sees "Forwarded". Recorded in `GET /messages` like the media sends.

- Unlocked by: Developer (`media`)
- Per-number key: yes

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fromPhone` | string | no | Not needed (WhatsApp finds the message by its id); still accepted. |
| `messageId` | string | yes | The message: WahaSend's `messageId` of a message you sent, or a WhatsApp id (e.g. `wahaMessageId` of a `message.inbound` event). |
| `toPhone` | string | yes | International phone number, 8–20 characters (`+22212345678`). `@lid` ids are not accepted here. |
| `containerId` | uuid | no | Which of your WhatsApp numbers to use; it always wins. Default: your default number (else any connected one), or a number of the group when [several numbers](https://wahasend.com/docs/phone-numbers.md#several-numbers) is on. Ignored with a per-number key, which always uses its own number. |

**Example**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/alert/forward \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messageId": "true_22212345678@c.us_3EB0C767D26A1D2E5A8F",
  "toPhone": "+22287654321"
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/alert/forward', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "messageId": "true_22212345678@c.us_3EB0C767D26A1D2E5A8F",
    "toPhone": "+22287654321"
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/alert/forward",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "messageId": "true_22212345678@c.us_3EB0C767D26A1D2E5A8F",
        "toPhone": "+22287654321",
    },
)
print(r.json())
```

**Response 201**

```json
{
  "success": true,
  "messageId": "3d7f1b2c-5e8a-4c69-b0d3-8f2a6c4e1b95",
  "wahaMessageId": "true_22212345678@c.us_3EB0C767D26A1D2E5A8F",
  "containerId": "6d2b9c1e-8f4a-4e37-a5c2-1b9e7d3f0a64"
}
```

**Errors to expect**

- [`MESSAGE_NOT_FOUND`](https://wahasend.com/docs/errors.md#message_not_found) (404): No message with this id was sent by this account.
- [`MESSAGE_NOT_SENT`](https://wahasend.com/docs/errors.md#message_not_sent) (409): This message has not been sent yet (or it failed). Only sent messages can be edited or deleted.
- [`MESSAGE_WRONG_NUMBER`](https://wahasend.com/docs/errors.md#message_wrong_number) (403): This message was sent from another WhatsApp number than the one this request uses.
- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NO_SESSION_CONFIGURED`](https://wahasend.com/docs/errors.md#no_session_configured) (400): This account has no connected WhatsApp number.
- [`WAHA_ERROR`](https://wahasend.com/docs/errors.md#waha_error) (502): WhatsApp could not complete the request. Try again.
- [`WAHA_SESSION_ERROR`](https://wahasend.com/docs/errors.md#waha_session_error) (503): WhatsApp is not connected.
- [`PRODUCT_REQUIRED`](https://wahasend.com/docs/errors.md#product_required) (403): This feature is not included in your products.

<a id="alert-edit"></a>

### Edit a sent message

`PUT /api/v1/alert/edit`

Changes the text of a message your number sent. WhatsApp only allows this for a short while after sending.

- Unlocked by: Developer (`media`)
- Per-number key: yes

> With WahaSend's id the message is found in your history: it must be sent (`sent`, `delivered` or `read`, else `MESSAGE_NOT_SENT`), yours (else `MESSAGE_NOT_FOUND`) and from the number this request uses (a per-number key or `containerId`; else `MESSAGE_WRONG_NUMBER`). Its text in `GET /messages` is updated too.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `messageId` | string | yes | The message to change. WahaSend's `messageId` (from `/alert/send`, a media send or `GET /messages`; the message must be sent), or WhatsApp's id as before (then `phone` is required). |
| `text` | string | yes | New text, 1–4096 characters. |
| `phone` | string | no | The chat's phone number or `@lid` id. Required with a WhatsApp id; with WahaSend's id it is taken from the message (if given, it must match). |
| `containerId` | uuid | no | Which of your WhatsApp numbers to use; it always wins. Default: your default number (else any connected one), or a number of the group when [several numbers](https://wahasend.com/docs/phone-numbers.md#several-numbers) is on. Ignored with a per-number key, which always uses its own number. |

**Example**

curl:

```bash
curl -X PUT https://app.wahasend.com/api/v1/alert/edit \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messageId": "4f0c6a1e-2b7d-4c1a-9e35-7d8f2a6b1c90",
  "text": "Your order #1042 is ready (counter 2)."
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/alert/edit', {
  method: 'PUT',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "messageId": "4f0c6a1e-2b7d-4c1a-9e35-7d8f2a6b1c90",
    "text": "Your order #1042 is ready (counter 2)."
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.put(
    "https://app.wahasend.com/api/v1/alert/edit",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "messageId": "4f0c6a1e-2b7d-4c1a-9e35-7d8f2a6b1c90",
        "text": "Your order #1042 is ready (counter 2).",
    },
)
print(r.json())
```

**Response 200**

```json
{
  "success": true,
  "messageId": "4f0c6a1e-2b7d-4c1a-9e35-7d8f2a6b1c90",
  "wahaMessageId": "true_22212345678@c.us_3EB0C767D26A1D2E5A8F"
}
```

**Errors to expect**

- [`MESSAGE_NOT_FOUND`](https://wahasend.com/docs/errors.md#message_not_found) (404): No message with this id was sent by this account.
- [`MESSAGE_NOT_SENT`](https://wahasend.com/docs/errors.md#message_not_sent) (409): This message has not been sent yet (or it failed). Only sent messages can be edited or deleted.
- [`MESSAGE_WRONG_NUMBER`](https://wahasend.com/docs/errors.md#message_wrong_number) (403): This message was sent from another WhatsApp number than the one this request uses.
- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NO_SESSION_CONFIGURED`](https://wahasend.com/docs/errors.md#no_session_configured) (400): This account has no connected WhatsApp number.
- [`WAHA_ERROR`](https://wahasend.com/docs/errors.md#waha_error) (502): WhatsApp could not complete the request. Try again.
- [`WAHA_SESSION_ERROR`](https://wahasend.com/docs/errors.md#waha_session_error) (503): WhatsApp is not connected.
- [`PRODUCT_REQUIRED`](https://wahasend.com/docs/errors.md#product_required) (403): This feature is not included in your products.

<a id="alert-delete"></a>

### Delete a sent message

`POST /api/v1/alert/delete`

Deletes a message your number sent, for everyone.

- Unlocked by: Developer (`media`)
- Per-number key: yes

> Same rules as [edit](https://wahasend.com/docs/api/sending.md#alert-edit). With a WhatsApp id, send `phone` too: `{ "phone": "+22212345678", "messageId": "true_…" }`.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `messageId` | string | yes | The message to delete. WahaSend's `messageId` (from `/alert/send`, a media send or `GET /messages`; the message must be sent), or WhatsApp's id as before (then `phone` is required). |
| `phone` | string | no | The chat's phone number or `@lid` id. Required with a WhatsApp id; with WahaSend's id it is taken from the message (if given, it must match). |
| `containerId` | uuid | no | Which of your WhatsApp numbers to use; it always wins. Default: your default number (else any connected one), or a number of the group when [several numbers](https://wahasend.com/docs/phone-numbers.md#several-numbers) is on. Ignored with a per-number key, which always uses its own number. |

**Example**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/alert/delete \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messageId": "4f0c6a1e-2b7d-4c1a-9e35-7d8f2a6b1c90"
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/alert/delete', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "messageId": "4f0c6a1e-2b7d-4c1a-9e35-7d8f2a6b1c90"
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/alert/delete",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "messageId": "4f0c6a1e-2b7d-4c1a-9e35-7d8f2a6b1c90",
    },
)
print(r.json())
```

**Response 200**

```json
{
  "success": true,
  "messageId": "4f0c6a1e-2b7d-4c1a-9e35-7d8f2a6b1c90",
  "wahaMessageId": "true_22212345678@c.us_3EB0C767D26A1D2E5A8F"
}
```

**Errors to expect**

- [`MESSAGE_NOT_FOUND`](https://wahasend.com/docs/errors.md#message_not_found) (404): No message with this id was sent by this account.
- [`MESSAGE_NOT_SENT`](https://wahasend.com/docs/errors.md#message_not_sent) (409): This message has not been sent yet (or it failed). Only sent messages can be edited or deleted.
- [`MESSAGE_WRONG_NUMBER`](https://wahasend.com/docs/errors.md#message_wrong_number) (403): This message was sent from another WhatsApp number than the one this request uses.
- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NO_SESSION_CONFIGURED`](https://wahasend.com/docs/errors.md#no_session_configured) (400): This account has no connected WhatsApp number.
- [`WAHA_ERROR`](https://wahasend.com/docs/errors.md#waha_error) (502): WhatsApp could not complete the request. Try again.
- [`WAHA_SESSION_ERROR`](https://wahasend.com/docs/errors.md#waha_session_error) (503): WhatsApp is not connected.
- [`PRODUCT_REQUIRED`](https://wahasend.com/docs/errors.md#product_required) (403): This feature is not included in your products.