Guides by resource
Messages
Send a message to a lead on WhatsApp through the anti-ban engine, or on Instagram and Messenger inside the 24-hour window, with safe retries.
POST /messages writes to a lead on the lead’s own channel, as if a teammate had answered in the dashboard. On WhatsApp it goes from the campaign’s own number and the anti-ban rules are enforced server-side. On Instagram and Messenger it goes from the account or the Page, inside Meta’s 24-hour window (below).
Endpoints
Section titled “Endpoints”| Method | Path | Scope |
|---|---|---|
| POST | /messages |
messages:send |
Send a message
Section titled “Send a message”curl -X POST "https://app.whatsetter.com/api/v1/messages" \ -H "Authorization: Bearer ws_live_…" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 8c3d2f9e-7b1a-4e6f-9c0d-2a1b3c4d5e6f" \ -d '{"lead_id":"66f1a2b3c4d5e6f7a8b9c0d1","text":"Are we still on for tomorrow at 2pm?"}'const res = await fetch('https://app.whatsetter.com/api/v1/messages', { method: 'POST', headers: { Authorization: 'Bearer ws_live_…', 'Content-Type': 'application/json', 'Idempotency-Key': '8c3d2f9e-7b1a-4e6f-9c0d-2a1b3c4d5e6f', }, body: JSON.stringify({ lead_id: '66f1a2b3c4d5e6f7a8b9c0d1', text: 'Are we still on for tomorrow at 2pm?', }),});const { data: message } = await res.json();import requests
r = requests.post( "https://app.whatsetter.com/api/v1/messages", headers={ "Authorization": "Bearer ws_live_…", "Idempotency-Key": "8c3d2f9e-7b1a-4e6f-9c0d-2a1b3c4d5e6f", }, json={ "lead_id": "66f1a2b3c4d5e6f7a8b9c0d1", "text": "Are we still on for tomorrow at 2pm?", },)message = r.json()["data"]{ "data": { "id": "66f1a2b3c4d5e6f7a8b9c0e5", "message_id": "true_33612345678@c.us_3EB0C8F2A1D4B5E6F7A8", "lead_id": "66f1a2b3c4d5e6f7a8b9c0d1", "text": "Are we still on for tomorrow at 2pm?", "sent_at": "2026-09-19T08:12:04.000Z", "humanized": true, "typing_ms": 3210, "quota": { "limit": 250, "used": 41, "remaining": 209, "resets_at": "2026-09-20T00:00:00.000Z" } }}| Field | Meaning |
|---|---|
id |
The conversation row id in WhatSetter, or null if the row could not be written after the send. |
message_id |
The WhatsApp message id. |
lead_id |
The lead you wrote to. |
text |
The text sent. |
sent_at |
When the engine accepted it. |
humanized |
Whether the human choreography was played. |
typing_ms |
The typing delay that was simulated, 0 when humanize is false. |
quota |
The number’s daily budget after this send. |
201 means the message was accepted by the WhatsApp engine. Final delivery is asynchronous, like any WhatsApp API. The message appears in the dashboard conversation as a manual reply.
The rules
Section titled “The rules”No cold outreach
Section titled “No cold outreach”The lead must already have a conversation: at least one message exchanged. Otherwise you get 409 lead_not_contacted. First contact goes through a list and campaign or an opt-in push.
Daily quota per number
Section titled “Daily quota per number”Each send consumes the same daily budget as the campaign engine for that WhatsApp number (250 messages a day when no specific quota is set). When it is reached: 429 quota_exceeded, reset at midnight UTC.
Every 201 and 429 carries the budget in headers:
X-Quota-Limit: 250X-Quota-Remaining: 209X-Quota-Reset: 2026-09-20T00:00:00.000ZThe number must be connected
Section titled “The number must be connected”If the campaign has no WhatsApp number, or the number is disconnected, you get 503 agent_disconnected. Check whatsapp_connected on GET /campaigns and reconnect it from the dashboard.
Humanized sending
Section titled “Humanized sending”By default (humanize: true) the send replays a human choreography: read receipt, typing indicator, a typing delay paced to the message length, then the send. Expect the request to take 3 to 15 seconds. This is the recommended mode.
"humanize": false sends instantly, still quota-gated. Use it only for time-critical confirmations.
text is required, 1 to 4096 characters, text only.
Instagram and Messenger
Section titled “Instagram and Messenger”The same call, the same body, on a lead whose channel is instagram or facebook (Messenger). The message goes out through the dashboard inbox’s own path and shows in the thread as a manual reply.
- Within 24 hours of the person’s last message only. That is Meta’s rule for a business. Past it you get
409 messaging_window_closedwithwindow_closes_at(when it closed), and nothing is sent: wait for the person to write again. WhatSetter never uses the tag that stretches the window to 7 days through the API; it is kept for a reply a person types in the inbox. - Like a reply typed in the inbox, it pauses the agent on this lead for the account’s
human_pause_hours(Instagram guide), so it does not answer over you. The answer says until when inagent_paused_until.POST /leads/{id}/resumeends the pause. - Text: 1,000 characters on Instagram, 2,000 on Messenger. No WhatsApp quota and no humanized choreography apply:
humanizeis ignored,quotaisnull.
{ "error": { "code": "messaging_window_closed", "message": "Instagram lets a business answer only within 24 hours of the person's last message. Wait for them to write again.", "window_closes_at": "2026-10-29T18:42:10.000Z" }}GET /conversations?channel=instagram&needs_reply=true lists the threads waiting for an answer (Conversations).
Retry safely with Idempotency-Key
Section titled “Retry safely with Idempotency-Key”A message API must be safe to retry: a timeout must never turn into a second real WhatsApp message. Pass an Idempotency-Key header on every send, unique per intent (a UUID, an order id…), up to 200 characters. WhatSetter remembers it for 15 minutes.
| Situation | What a retry with the same key gets |
|---|---|
The first call answered 201 |
The same 201 body, with the header X-Idempotent-Replay: true. No second message. |
| The first call is still running | 409 request_in_flight. Wait and retry. |
The first call failed cleanly (422, 409, 429, 503) |
The key is released: your retry is a real new attempt. |
The first call timed out (502 send_failed) |
409 request_in_flight for the rest of the window: the message may have gone out. Check the conversation transcript before sending again. |
Errors you will meet
Section titled “Errors you will meet”| HTTP | code |
When |
|---|---|---|
| 401 | missing_api_key, invalid_api_key |
Key absent, unknown or revoked. |
| 403 | insufficient_scope |
The key lacks messages:send. |
| 404 | not_found |
Unknown lead, or a lead of another workspace. |
| 409 | lead_not_contacted |
The lead has never been contacted. Go through a list or an opt-in push. |
| 409 | request_in_flight |
Same Idempotency-Key still processing, or an earlier attempt with it timed out. |
| 409 | messaging_window_closed |
Instagram or Messenger: more than 24 hours since the person’s last message. See window_closes_at. |
| 409 | recipient_unreachable |
Instagram or Messenger: the person does not receive messages from the account right now (blocked it, or turned messages off). |
| 409 | instagram_reconnect_required, facebook_reconnect_required, facebook_page_required, instagram_account_not_found |
Instagram or Messenger: the account or the Page must be connected again from the dashboard. |
| 403 | instagram_not_enabled |
An Instagram lead, and Instagram is not enabled on the workspace. |
| 422 | validation_error |
Missing lead_id, empty or too long text, humanize not a boolean, key over 200 characters. |
| 429 | quota_exceeded |
Daily budget of the number reached. See X-Quota-Reset. |
| 429 | rate_limited |
Too many requests this minute. Honor Retry-After. |
| 500 | internal_error |
Messaging backend not configured on our side. |
| 502 | send_failed |
The engine refused or did not confirm the send. Retry with the same key. |
| 503 | agent_disconnected |
No number on the campaign, or the number is offline. |