Send a Message

POST /api/send-message

Send any WhatsApp message type from a single endpoint — text, media, location, contact, poll, or buttons. The type is chosen by the message_type field.

Auth: Bearer Device Key
Cost: 1 credit for text / location / contact / poll; 2 credits for image / video / audio / document / buttons / interactive. Refunded automatically on failure.
Rate limit: 20/min burst per device — use Send Bulk Messages for volume.

Fields

Field	Type	Required for	Notes
`number`	string	all	Recipient, any format
`message_type`	string	all	One of the types below
`message`	string	`text`, `buttons`, `interactive`	Also used as the caption for media
`media_url`	string (URL)	`image`, `video`, `audio`, `document`	Public https URL; fetched with SSRF protection & a size cap
`file_name`	string	`document`	e.g. `invoice.pdf`
`mimetype`	string	media types	e.g. `image/jpeg`, `video/mp4`, `audio/mp4`, `application/pdf`
`latitude`, `longitude`	number	`location`
`contact_name`, `contact_number`	string	`contact`	Builds a vCard
`poll_name`	string	`poll`	Question text
`poll_options`	string[]	`poll`	≥ 2 options
`allow_multiple_answers`	boolean	`poll`	Optional, default `false`
`buttons`	object[]	`buttons`, `interactive`	Each `{ "buttonId": "...", "displayText": "..." }`
`quoted_message_id`	string	quoted replies	`message_id` being replied to
`quoted_message`	string	quoted replies	Fallback text if the original isn't in the store

message_type ∈ text · image · video · audio · document · location · contact · poll · buttons · interactive.

Response

{ "success": true, "message_type": "text", "message_id": "3EB0A1B2C3…", "to": "8801234567890" }

Save message_id — you need it to delete or quote the message.

Examples by type

Text

{ "number": "8801234567890", "message_type": "text", "message": "Hello!" }

Image

{
  "number": "8801234567890",
  "message_type": "image",
  "message": "Optional caption",
  "media_url": "https://example.com/photo.jpg",
  "mimetype": "image/jpeg"
}

Video

{
  "number": "8801234567890",
  "message_type": "video",
  "media_url": "https://example.com/clip.mp4",
  "mimetype": "video/mp4"
}

Audio

{
  "number": "8801234567890",
  "message_type": "audio",
  "media_url": "https://example.com/voice.mp3",
  "mimetype": "audio/mp4"
}

Document

{
  "number": "8801234567890",
  "message_type": "document",
  "media_url": "https://example.com/invoice.pdf",
  "file_name": "invoice.pdf",
  "mimetype": "application/pdf"
}

Location

{
  "number": "8801234567890",
  "message_type": "location",
  "latitude": 37.7749,
  "longitude": -122.4194
}

Contact

{
  "number": "8801234567890",
  "message_type": "contact",
  "contact_name": "Golam Rabbi",
  "contact_number": "8801234567890"
}

Poll

{
  "number": "8801234567890",
  "message_type": "poll",
  "poll_name": "Best color?",
  "poll_options": ["Red", "Blue", "Green"],
  "allow_multiple_answers": false
}

Buttons

{
  "number": "8801234567890",
  "message_type": "buttons",
  "message": "Pick one",
  "buttons": [
    { "buttonId": "yes", "displayText": "Yes" },
    { "buttonId": "no", "displayText": "No" }
  ]
}

Buttons & interactive

Interactive/button messages are fragile and increasingly deprecated by WhatsApp — delivery is best-effort and may render as plain text on some clients. Prefer text or poll where possible.

Quoted replies

Reply to a specific message by passing its message_id as quoted_message_id. Include quoted_message as a fallback in case the original isn't in the engine's store:

{
  "number": "8801234567890",
  "message_type": "text",
  "message": "Sure, sending it now 👍",
  "quoted_message_id": "3EB0A1B2C3…",
  "quoted_message": "Can you send the invoice?"
}

Media rules

media_url must be a public https URL. Rapiwa fetches it server-side with SSRF protection (private/loopback/link-local hosts are refused, redirects are not followed) and a size cap. Point it at real, publicly reachable object storage or a CDN.
Set an accurate mimetype; sensible defaults are used if omitted (image/jpeg, video/mp4, audio/mp4, application/pdf).

cURL

curl -X POST https://app.rapiwa.com/api/send-message \
  -H "Authorization: Bearer YOUR_DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"8801234567890","message_type":"text","message":"Hello from Rapiwa!"}'