Send a message

Send a WhatsApp text from one of your connected numbers to someone who messaged that number in the last 30 days. To send a photo or document, see Send photos & documents.

curl https://api.waconnect.ai/v1/messages \
  -H "Authorization: Bearer wc_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: booking-381-reminder" \
  -d '{"from":"+12125550147","to":"+14155550123","text":"Reminder: your appointment is tomorrow at 3 pm."}'

Who you can message#

API numbers only reply. You can send to a phone that messaged the same number in the last 30 days; each new message from them restarts the 30 days. Sending to anyone else answers 403 OUTSIDE_REPLY_WINDOW, and nothing is queued or charged.

Sending pace#

Each number sends like a person types: one message every 1 to 3 seconds, with "typing…" shown just before it, and at most 20 messages in any 60 seconds. Messages above that wait their turn and go out in the order you sent them; none are dropped. scheduledFor in the response tells you when the message goes out.

What happens next#

The API answers 202 Accepted straight away, with the message in PENDING status. WaConnect then:

1. queues it for its turn and sends the message.queued webhook;
2. shows "typing…" to the recipient, then sends it through your number;
3. sends the message.sent webhook and charges $0.005.

{
  "id": "01a0f4c2-8b1e-7a0c-9d3f-2e6b5a4c1d00",
  "numberId": "01a0f44d-c969-75b1-955d-3841d817f711",
  "direction": "OUTBOUND",
  "contact": { "phone": "+14155550123", "name": null },
  "kind": "TEXT",
  "text": "Reminder: your appointment is tomorrow at 3 pm.",
  "media": null,
  "status": "PENDING",
  "error": null,
  "sentVia": "api",
  "sentAt": "2026-10-01T10:00:00.000Z",
  "scheduledFor": "2026-10-01T10:00:01.500Z"
}

Follow the delivery#

A message moves through PENDING → SENT → DELIVERED → READ, or ends in FAILED with a reason in error.

• Best: listen for the message.queued, message.sent and message.status webhooks.
• Messages aren't stored in WaConnect, so the webhooks are the only way to follow a message's status. Save them on your side.

Which number sends it#

Name the sending number with from or numberId. You can leave both out only when your API key can use exactly one number; that number sends it, connected or not. If it's disconnected, you get 409 NUMBER_NOT_CONNECTED, and WaConnect never switches to another number. With two or more numbers, leaving both out answers 400 NUMBER_REQUIRED.

Sending from many numbers with one app works the same way: give the key all of them, and name the number on every request.

Common errors#

Check code, not the status. See all error codes.