Sign inRequest access

Send Messages

POST /v1/messages sends one message from a session. Authenticate with the session's API key, or with a personal access token plus session_id in the body.

Recipients

to takes a phone number with its country code, or a WhatsApp ID (JID):

to Sends to
+6281234567890 (spaces, dashes and the + are optional) A person
6281234567890@s.whatsapp.net or …@lid A person, by JID
120363012345678901@g.us A group the number is in; find its JID with GET /v1/groups
120363098765432109@newsletter A channel the number administers

To check that numbers use WhatsApp before sending, call POST /v1/contacts/check.

Message types

Send text, or exactly one of the other fields. With media, put the text in caption.

Type Body
Text {"to": "…", "text": "Hello"} (up to 65,536 bytes)
Image {"to": "…", "image": {"url": "https://…/photo.jpg", "caption": "…"}}
Video {"to": "…", "video": {"url": "https://…/clip.mp4", "caption": "…"}}
Audio {"to": "…", "audio": {"url": "https://…/note.ogg", "ptt": true}} (ptt sends a voice note)
Document {"to": "…", "document": {"url": "https://…/invoice.pdf", "filename": "Invoice.pdf", "caption": "…"}}
Location {"to": "…", "location": {"latitude": -6.2, "longitude": 106.8, "name": "Office", "address": "Jl. Sudirman 21"}}
Contact card {"to": "…", "contact": {"name": "Support", "phone": "+6281234567890"}}

Media is downloaded from its URL when the message is sent, so the URL must be public and stay valid for a few minutes. Images can be up to 16 MB, video, audio and documents up to 64 MB. The type is detected from the file; set mimetype to override it.

Mentions

To mention someone in a group, write @ and their number in the text and list them in mentions:

{
  "to": "120363012345678901@g.us",
  "text": "Welcome @6281234567890!",
  "mentions": ["+6281234567890"]
}

Status

Every message is queued first, so the request answers fast even while WhatsApp is slow. The status then moves forward:

status Meaning
queued Accepted, waiting for its turn.
sending Being sent now.
sent WhatsApp accepted it; wa_message_id is set.
delivered It reached the recipient's phone.
read The recipient opened it (if they share read receipts).
failed It could not be sent; error says why.

Temporary problems are retried up to 3 times. A message that could not be sent within 24 hours, for example because the session stayed disconnected, fails. Permanent problems fail at once, such as a number that is not on WhatsApp or media that cannot be downloaded.

Follow a message with GET /v1/messages/{id}, or list them with GET /v1/messages (newest first; limit up to 100, status to filter, and before with the last id you got to page back). The webhook events message.sent and message-receipt.update report the same progress as it happens.

Mark as read

Send read receipts for messages you received:

curl https://api.warsita.com/v1/messages/read \
  -H "Authorization: Bearer $WARSITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chat": "6281234567890@s.whatsapp.net", "ids": ["3EB0C431C26A1916E2A3"]}'

ids are WhatsApp message ids, the id of a messages.received event. In a group, also send sender, the JID of who wrote the message. Or turn on read_incoming in the session settings to mark everything as read.

Message logging

By default Warsita keeps a message's content only until it is sent; afterwards payload is null and only the status remains. Turn on message_logging in the session settings to keep it. Logs are deleted after 30 days either way, and DELETE /v1/sessions/{id}/messages clears a session's finished messages at once.

NextWebhooks