Messages

Send a WhatsApp message from a connected instance. Receive-direction messages arrive as message.received webhooks; there's no "list inbox" endpoint — webhooks are the read path.

Send a message

The instance must be connected. Sending while pending / qr / disconnected returns 409 not_connected.

The body is a discriminated union on type. Valid shapes:

// text
{
  "to": "5511999999999",
  "body": { "type": "text", "text": "hello" }
}
 
// image
{
  "to": "5511999999999",
  "body": { "type": "image", "media_url": "https://...", "caption": "look" }
}
 
// audio
{
  "to": "5511999999999",
  "body": { "type": "audio", "media_url": "https://..." }
}
 
// document
{
  "to": "5511999999999",
  "body": { "type": "document", "media_url": "https://...", "filename": "invoice.pdf" }
}

to is an MSISDN — international format with no leading +. We accept group JIDs (...@g.us) for completeness, but most workflows are 1:1.

curl -sX POST "$WHATISUP_API/v1/instances/inst_01J.../messages" \
  -H "Authorization: Bearer $WHATISUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"5511999999999","body":{"type":"text","text":"hi"}}'

The response acknowledges that the message has been handed to the WhatsApp socket. Final delivery state arrives as a separate message.delivered webhook (or message.failed on terminal failure). Use the message_id to correlate.

What you don't see in this API

• No GET endpoint for messages. Inbound messages come in as webhooks and are the canonical record. We do not buffer them server-side beyond what's needed for retry of the webhook.
• No bulk send. Loop the API; the per-customer rate limiter (API keys → Rate limiting) is your throttle. Stripe-style batching is on the roadmap.
• No "schedule send". Schedule it on your side and call us at fire time.