Messages go through API numbers and are not stored in WaConnect: you get each message in the send response and in webhooks, and your software keeps its own copy. There's no endpoint to list or fetch messages later.
The message object#
The same object is returned when you send and in every message webhook.
{
"id": "01a0f4c2-8b1e-7a0c-9d3f-2e6b5a4c1d00",
"numberId": "01a0f44d-c969-75b1-955d-3841d817f711",
"direction": "OUTBOUND",
"contact": { "phone": "+14155550123", "name": "Emily Carter" },
"kind": "TEXT",
"text": "Your order #1042 is ready for pickup.",
"media": null,
"status": "DELIVERED",
"error": null,
"sentVia": "api",
"sentAt": "2026-10-01T10:00:00.000Z"
}idstringrequired- The message id. Ids sort in creation order.
numberIdstringrequired- Your number that sent or received it.
directionINBOUND | OUTBOUNDrequired- Received from the customer, or sent by you.
contactobjectrequired- The customer: phone (international format) and name (their WhatsApp profile name, when known).
kindstringrequired- TEXT, IMAGE, VIDEO, AUDIO, DOCUMENT, STICKER, LOCATION, CONTACT or OTHER.
textstring | nullrequired- The text, or the caption of a photo or document.
mediaobject | nullrequired- Photos and documents only: status (PENDING, READY or FAILED), mimeType, fileName, size in bytes, and width and height for photos. Download the file from GET /v1/messages/:id/media. null for other messages.
statusstringrequired- PENDING, SENT, DELIVERED, READ or FAILED.
errorstring | nullrequired- Why a message FAILED.
sentViaapi | phone | nullrequired- How an outgoing message was sent: through the API, or typed on the phone itself. null for received messages.
sentAtISO 8601 daterequired- When it was sent or received.
scheduledForISO 8601 dateoptional- Messages sent through the API: when it's due to go out. Numbers send at a human pace, so it can be a few seconds or minutes after sentAt.
Send a message#
https://api.waconnect.ai/v1/messagesSends a text, photo or document from one of your connected API numbers. Answers 202 with the message in PENDING status. Supports the Idempotency-Key header. Guides: Send messages, Send photos & documents.
Body
fromstringoptional- Your connected WhatsApp number that sends it, in international format.
numberIdstring (uuid)optional- Or the sending number's id. Send from or numberId, not both. With neither, the number is picked only when your key can use exactly one number; otherwise the request answers 400 NUMBER_REQUIRED.
tostringrequired- The recipient in international format.
textstringoptional- Up to 4,096 characters; with media, the caption (up to 1,024). Required when there's no media.
mediaobjectoptional- A file uploaded with POST /v1/media/uploads: uploadId, kind (IMAGE or DOCUMENT) and, for documents, fileName.
Upload a photo or document#
https://api.waconnect.ai/v1/media/uploadsReturns uploadId, a one-time uploadUrl (valid 10 minutes) and expiresAt. PUT the file to uploadUrl, then send it with POST /v1/messages. Photos: JPG or PNG, up to 16 MB. Documents: any type, up to 100 MB. Full guide: Send photos & documents.
Body
kindIMAGE | DOCUMENTrequired- How it shows in the chat.
mimeTypestringrequired- The file's type, e.g. image/jpeg or application/pdf.
sizenumberrequired- The file's size in bytes.
Download a photo or document#
https://api.waconnect.ai/v1/messages/:id/mediaRedirects (302) to a download link that works for 5 minutes. Add ?download=1 to download under the file's original name.
Files are kept for about 24 hours, then deleted. Download a received photo or document as soon as its webhook arrives and store it yourself. Answers 404 with MESSAGE_HAS_NO_FILE when the message has no file, media.status isn't READY, or the file has expired.