# Send a message to a lead (WhatsApp, Instagram, Messenger)

`POST https://app.whatsetter.com/api/v1/messages`

Sends a text message to a lead on the lead's own channel.

**Instagram and Messenger.** Only within 24 hours of the person's last
message (Meta's rule): past that you get `409 messaging_window_closed`
with `window_closes_at`, and nothing is sent. The message goes out
through the dashboard inbox's own path (it shows in the thread as a
manual reply) and, like a reply typed there, pauses the agent on this
lead for the account's `human_pause_hours` (`agent_paused_until` in
the answer; `POST /leads/{id}/resume` ends it). Instagram takes 1,000
characters, Messenger 2,000. No WhatsApp quota and no choreography
apply (`humanize` is ignored, `quota` is null).

**WhatsApp**, through WhatSetter's anti-ban engine. Two rules are
enforced server-side and cannot be bypassed:

1. **No cold outreach**: the lead must already have a conversation.
   First contact goes through `POST /lists/{id}/leads` + a campaign
   (paced, verified sending). Otherwise you get `409 lead_not_contacted`.
2. **Daily quota**: the send consumes the same daily budget as the
   campaign engine for that WhatsApp number. When the number's safe
   daily volume is reached you get `429 quota_exceeded` (reset at
   midnight UTC). Check the `X-Quota-Remaining` response header.

The message is sent from the lead's own campaign number and appears in
the dashboard conversation thread. Requires scope `messages:send`.

Note: `201` means the message was **accepted by the WhatsApp engine**.
Like all WhatsApp APIs, final delivery is asynchronous (device online,
contact state…). Delivery/read receipts will surface via webhooks in a
future version.

**Idempotency.** Send an `Idempotency-Key` header (≤ 200 characters).
A key that already produced a response replays it for **15 minutes**
(`X-Idempotent-Replay: true`) instead of sending again; a retry fired
while the first request is still running answers `409
request_in_flight`. The `X-Quota-*` headers are set on the `201` and
on the `429` alike.

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `lead_id` | string | yes | The lead's `id` from `/leads` or `/conversations`. |
| `text` | string | yes | WhatsApp 4,096 characters, Instagram 1,000, Messenger 2,000. |
| `humanize` | boolean | no | When true (default, recommended), the send replays a human choreography (read receipt, "typing…" indicator, a typing delay paced to the message length) before the message goes out. Expect the request to take ~3–15 s. Set to false for an instant send (still quota-gated).  |

```json
{
  "lead_id": "",
  "text": "",
  "humanize": true
}
```

## Example request

```bash
curl --request POST \
  --url 'https://app.whatsetter.com/api/v1/messages' \
  --header 'Authorization: Bearer ws_live_…'
  --header 'Content-Type: application/json' \
  --data '{"lead_id":"","text":"","humanize":true}'
```

## Responses

### 201: Message sent

```json
{
  "data": {
    "id": "68f2bb33cc44dd55ee66ff77",
    "message_id": "true_33612345678@c.us_3EB0C8A1B2C3D4E5F6",
    "lead_id": "68e0a1b2c3d4e5f6a7b8c9d0",
    "channel": "whatsapp",
    "text": "Bonjour Marie, je vous confirme notre appel de demain à 10h.",
    "sent_at": "2026-09-19T08:12:45.000Z",
    "humanized": true,
    "typing_ms": 4200,
    "quota": {
      "limit": 250,
      "used": 41,
      "remaining": 209,
      "resets_at": "2026-09-20T00:00:00.000Z"
    }
  }
}
```

### 401: Missing, unknown or revoked API key

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 403: The key lacks the required scope (`insufficient_scope`), the plan does not have this part of the API (`not_in_plan`), or Instagram is not enabled on the workspace (`instagram_not_enabled`, Instagram routes)

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 404: Resource not found in this workspace

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 409: The lead was never contacted (`lead_not_contacted`: cold outreach
must go through lists + campaigns), a request with the same
Idempotency-Key is still in flight (`request_in_flight`), or, on
Instagram and Messenger: the 24-hour window is closed
(`messaging_window_closed`, with `window_closes_at`), the person
does not receive messages from the account right now
(`recipient_unreachable`), the account must be reconnected (`instagram_reconnect_required`), the Page is
missing or must be reconnected (`facebook_page_required`,
`facebook_reconnect_required`), or the account of the thread is no
longer connected (`instagram_account_not_found`).


```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 422: Invalid parameter or body (also an invalid or expired `cursor`)

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 429: Daily anti-ban quota reached for this number (`quota_exceeded`, resets at midnight UTC)

```json
{
  "error": {
    "code": "quota_exceeded",
    "message": "Daily WhatsApp quota reached for this number (250 messages — anti-ban protection). It resets at midnight UTC."
  }
}
```

### 500: Messaging backend not configured on this deployment (`internal_error`)

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 502: `send_failed`: the WhatsApp engine refused the message, or did not
confirm it in time. With an `Idempotency-Key`, retrying is safe
(an ambiguous send keeps the key so the retry can never
double-deliver); without one, do not blindly retry.


```json
{
  "error": {
    "code": "send_failed",
    "message": "The message could not be sent. Retry shortly."
  }
}
```

### 503: `agent_disconnected`: the campaign has no WhatsApp number, or the
number is currently disconnected. Reconnect it in the dashboard.


```json
{
  "error": {
    "code": "agent_disconnected",
    "message": "The WhatsApp number for this campaign is currently disconnected. Reconnect it in the dashboard."
  }
}
```


Source: https://docs.whatsetter.com/api-reference/operations/sendmessage/
