Skip to content
Dashboard

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).

Method Path Scope
POST /messages messages:send
Terminal window
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?"}'
{
"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 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.

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: 250
X-Quota-Remaining: 209
X-Quota-Reset: 2026-09-20T00:00:00.000Z

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.

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.

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_closed with window_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 in agent_paused_until. POST /leads/{id}/resume ends the pause.
  • Text: 1,000 characters on Instagram, 2,000 on Messenger. No WhatsApp quota and no humanized choreography apply: humanize is ignored, quota is null.
{
"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).

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.
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.