Mark an inbound message as read
Sends a read receipt for an inbound message, the blue ticks the contact sees.
Name the number the message arrived on with either connection_id
or number_id, exactly as you would for a send. Sautikit does not
retain messages, so it cannot infer the number from the wamid
alone; the wamid comes from the whatsapp.event.received webhook
that delivered the message.
Meta's reference: https://developers.facebook.com/docs/whatsapp/cloud-api/guides/mark-message-as-read
API-key scope: whatsapp.messages.
Authorization
bearerAuth Long-lived ES256 JWT minted from the dashboard (https://app.sautikit.com/developers/api-keys). Signed by the
platform keyring. Carries workspace_id and scopes claims;
revoked via the platform deny-list.
In: header
Path Parameters
Meta's message id, from an inbound message.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/whatsapp/messages/string/read" \ -H "Content-Type: application/json" \ -d '{}'{}{ "error": { "code": "validation.bad_request", "message": "string", "request_id": "string", "details": [ "string" ], "resolution": "string", "reason": "invalid_characters", "suggested_e164": "+254720000003" }}{ "error": { "code": "validation.bad_request", "message": "string", "request_id": "string", "details": [ "string" ], "resolution": "string", "reason": "invalid_characters", "suggested_e164": "+254720000003" }}{ "error": { "code": "validation.bad_request", "message": "string", "request_id": "string", "details": [ "string" ], "resolution": "string", "reason": "invalid_characters", "suggested_e164": "+254720000003" }}Send a WhatsApp message POST
Sends a text or template message from one of your connected WhatsApp numbers. Pick the sending number with EITHER `number_id` (a Sautikit number id, the same one the rest of this API uses; we map it to Meta's `phone_number_id` for you) OR `connection_id` (a WhatsApp connection, whose WhatsApp number is used). Exactly one is required. A `number_id` that is not yours, or that no connected WhatsApp account carries, is rejected before anything reaches Meta. Returns **202** with Meta's `wamid`. Delivery is asynchronous, subscribe to the `whatsapp.event.received` workspace webhook, which relays Meta's delivery-status payloads to you verbatim. Sautikit does not store messages. The wamid is your handle for correlating the status events that follow. WhatsApp only permits free-form text inside a 24-hour customer service window opened by the contact messaging you. Outside it, use `type: template` with a Meta-approved template. ## Message types `type` names the message, and an object of the SAME NAME carries its contents. That object is forwarded to WhatsApp untouched, so its shape is WhatsApp's, including any type added after this page was written. ### Text ```json { "number_id": "9d2b1f53-8c0e-4f1d-9a6b-5d3a8c47e9f0", "to": "254720000000", "type": "text", "text": { "body": "Habari Wanjiru, your order from Duka la Vitabu is ready for pickup on Kimathi Street until 6pm.", "preview_url": false } } ``` Set `preview_url: true` to render a preview card for the first link in the body. ### Image, video, audio, document, sticker Media takes EITHER `id` (from `POST /v1/whatsapp/media`) or `link` (a public URL WhatsApp fetches). Prefer `id`: a link is re-fetched on every send and cached for only 10 minutes. Image with a caption (an M-PESA receipt): ```json { "number_id": "9d2b1f53-8c0e-4f1d-9a6b-5d3a8c47e9f0", "to": "254720000000", "type": "image", "image": { "id": "1234567890123456", "caption": "Receipt for KES 2,400, Sarit Centre branch" } } ``` Document (an invoice a customer can download): ```json { "type": "document", "document": { "id": "1234567890123456", "filename": "Invoice-INV-2291.pdf", "caption": "Your invoice for July deliveries" } } ``` Audio has no caption (WhatsApp renders it as a voice note); sticker takes only `id` or `link` and must be WebP. ### Location Send a pickup point: ```json { "type": "location", "location": { "latitude": -1.2833, "longitude": 36.8172, "name": "Mama Ngina Street pickup point", "address": "Mama Ngina St, Nairobi CBD" } } ``` ### Contacts Hand over a rider's details: ```json { "type": "contacts", "contacts": [ { "name": { "formatted_name": "Otieno Odhiambo", "first_name": "Otieno" }, "phones": [{ "phone": "+254720000007", "type": "CELL", "wa_id": "254720000007" }], "org": { "company": "Nairobi Swift Deliveries", "title": "Rider" } } ] } ``` ### Interactive: reply buttons Up to three buttons. Confirming a delivery slot: ```json { "type": "interactive", "interactive": { "type": "button", "body": { "text": "Your parcel arrives in Westlands tomorrow. Which slot suits you?" }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "slot_morning", "title": "8am - 12pm" } }, { "type": "reply", "reply": { "id": "slot_afternoon", "title": "12pm - 5pm" } } ] } } } ``` The tap arrives on your webhook as an inbound `interactive` message carrying the `id` you chose. ### Interactive: list Up to ten rows, grouped in sections, good for a menu or a catalogue the customer scrolls: ```json { "type": "interactive", "interactive": { "type": "list", "header": { "type": "text", "text": "Today's menu" }, "body": { "text": "Choose a dish and we'll deliver within 45 minutes." }, "action": { "button": "View menu", "sections": [ { "title": "Mains", "rows": [ { "id": "nyama_choma", "title": "Nyama choma", "description": "Half kilo, KES 750" }, { "id": "pilau", "title": "Pilau ya nyama", "description": "KES 450" } ] } ] } } } ``` ### Interactive: CTA URL button Puts a long or ugly link behind a button: ```json { "type": "interactive", "interactive": { "type": "cta_url", "body": { "text": "Track your parcel from our Mombasa Road depot." }, "action": { "name": "cta_url", "parameters": { "display_text": "Track parcel", "url": "https://track.example.co.ke/p/9F2K" } } } } ``` ### Interactive: location request Ask a customer where to deliver, instead of parsing a typed address: ```json { "type": "interactive", "interactive": { "type": "location_request_message", "body": { "text": "Where should the boda drop your order?" }, "action": { "name": "send_location" } } } ``` ### Interactive: Flow A multi-step form inside the chat: bookings, KYC, surveys. The answers arrive on your webhook as structured data: ```json { "type": "interactive", "interactive": { "type": "flow", "body": { "text": "Book your service appointment at our Thika Road garage." }, "action": { "name": "flow", "parameters": { "flow_message_version": "3", "flow_id": "1234567890", "flow_cta": "Book a slot", "flow_action": "navigate" } } } } ``` ### Reaction React to a message the customer sent you: ```json { "type": "reaction", "reaction": { "message_id": "wamid.HBgMMjU0NzEyMzQ1Njc4...", "emoji": "👍" } } ``` Send an empty `emoji` to remove a reaction. ### Replying in context Any message can quote one the customer sent, which is worth doing when a conversation has several threads running: ```json { "type": "text", "context": { "message_id": "wamid.HBgMMjU0NzEyMzQ1Njc4..." }, "text": { "body": "Yes, that size is in stock at our Nakuru branch." } } ``` ## Templates Outside the 24-hour window you may only send a template Meta has approved. Sautikit does not create templates, that happens in WhatsApp Manager or through Meta's Message Templates API, here you send one by name. `template.components` is forwarded untouched, so its shape is Meta's. Body parameters fill `{{1}}`, `{{2}}` **in order**, and the count must match the approved template exactly or Meta rejects the send. ### Utility template Transactional, tied to something the customer did, an order, a payment, a delivery: ```json { "number_id": "9d2b1f53-8c0e-4f1d-9a6b-5d3a8c47e9f0", "to": "254720000000", "type": "template", "template": { "name": "order_dispatched", "language_code": "en", "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "Wanjiru" }, { "type": "text", "text": "SK-4821" }, { "type": "text", "text": "Tuesday" } ] } ] } } ``` ### Marketing template Promotional. Subject to per-user marketing limits and the recipient's marketing opt-out, so a send can be accepted here and still not delivered: ```json { "type": "template", "template": { "name": "back_to_school_offer", "language_code": "en", "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "id": "1234567890123456" } } ] }, { "type": "body", "parameters": [{ "type": "text", "text": "20%" }] }, { "type": "button", "sub_type": "url", "index": "0", "parameters": [{ "type": "text", "text": "back-to-school" }] } ] } } ``` ### Authentication template One-time passwords. The body text is fixed by Meta. You supply only the code, and the same code repeats as the button parameter so the customer can copy or autofill it: ```json { "type": "template", "template": { "name": "verification_code", "language_code": "en", "components": [ { "type": "body", "parameters": [{ "type": "text", "text": "418902" }] }, { "type": "button", "sub_type": "url", "index": "0", "parameters": [{ "type": "text", "text": "418902" }] } ] } } ``` Authentication templates have a 10-minute time-to-live (everything else is 30 days), an undelivered code is dropped rather than arriving long after it expired. They are also delivered only to the customer's primary WhatsApp device. ## Phone number format Include the `+` and country code. Without a `+`, WhatsApp prepends YOUR number's country code, for a Kenyan number `0720000000` becomes `+2540720000000`, which is not a real number. Send `+254720000000` or `254720000000`. ## What a 202 means A 202 means WhatsApp ACCEPTED the request, not that the message arrived. Delivery outcomes reach you on the `whatsapp.event.received` webhook; correlate them by the `wamid` returned here. **API-key scope:** `whatsapp.messages`.
Upload media POST
Uploads a file to WhatsApp and returns the media id you then send in an image/video/audio/document message. Send a `multipart/form-data` body with a `file` part. The MIME type comes from a `type` field if you send one, otherwise from the part's own `Content-Type`, Meta requires it and will not sniff. The sending number is named in the QUERY (`number_id` or `connection_id`) so the body stays a pure file upload. ```bash curl -X POST \ "https://api.sautikit.com/v1/whatsapp/media?number_id=$NUMBER_ID" \ -H "Authorization: Bearer $SAUTIKIT_API_KEY" \ -F "type=application/pdf" \ -F "file=@invoice.pdf" ``` The returned `id` goes straight into a send: ```json { "number_id": "9d2b1f53-8c0e-4f1d-9a6b-5d3a8c47e9f0", "to": "254720000000", "type": "document", "document": { "id": "1234567890123456", "filename": "Invoice-INV-2291.pdf" } } ``` Prefer an uploaded `id` over a public `link`. A link is re-fetched by WhatsApp on every send and cached for only 10 minutes, so a receipt sent to 200 customers is 200 fetches of your server; an uploaded id is fetched once. WhatsApp's limits apply and are enforced upstream: 5 MB images, 16 MB audio and video, 100 MB documents, 500 KB stickers. Supported types include JPEG/PNG, MP4, MP3/M4A/OGG(Opus), PDF and the common Office formats, and WebP for stickers. Meta's reference: https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media **API-key scope:** `whatsapp.messages`.