Skip to main content

Send a WhatsApp message

POST/messaging/v1/whatsapp

Sends one WhatsApp message to one number: an approved template, or inside the 24-hour window a reply. Ponitor returns the message, already charged and queued. Its status changes as WhatsApp reports back.

Request body​

  • #senderstringRequired
    Your WhatsApp number (+231770000000, with or without the +).
    Example: +231770000000
  • #recipientstringRequired
    The phone number, in international format, with or without the +. It can also be the ID WhatsApp gives someone who hides their number (LR.1349…), from a received message's sender. Authentication templates can only go to a phone number.
    Example: +231770000000
  • #workspacestringOptional
    The handle of the workspace to send from and charge, such as gbarnga-branch. Leave it out for Main. See Workspaces.
    Example: gbarnga-branch
  • #externalIdstringRequired
    Your own reference, up to 64 characters, unique within your team. If you reuse one on a WhatsApp message, you get the original back with 200. Nothing is sent or charged again. See Retries and externalId.
    Example: order-42
  • #textstringOptional
    The message's text, 2 to 4,096 characters, inside the 24-hour window. See WhatsApp replies.
    Example: Your Acme order 42 is on its way.
  • #image, video, audio, documentobjectOptional
    Inside the 24-hour window. A file at a link. See WhatsApp replies for the types and sizes each one takes.
    Example: { "url": "https://example.com/r.jpg", "caption": "Receipt" }
    3 child parameters
    • #urlstringRequired
      A public link to the file, up to 2,048 characters. See The file's link below.
    • #captionstringOptional
      Up to 1,024 characters. Not for audio.
    • #filenamestringOptional
      document only. Up to 240 characters, for your records. The customer's WhatsApp doesn't show it.
  • #buttonsobject[]Optional
    With text of up to 1,024 characters, inside the 24-hour window. Up to 3 reply buttons. See Buttons, lists and links.
    Example: [{ "id": "yes", "title": "Yes" }]
    2 child parameters
    • #idstringRequired
      Up to 128 characters, different for each button. It comes back in the reply.
    • #titlestringRequired
      The words on the button, up to 20 characters.
  • #listobjectOptional
    With text of up to 1,024 characters, inside the 24-hour window. A list of up to 10 rows.
    2 child parameters
    • #buttonstringRequired
      The words on the button that opens the list, up to 20 characters.
    • #itemsobject[]Required
      1 to 10 rows.
      3 child parameters
      • #idstringRequired
        Up to 128 characters, different for each row.
      • #titlestringRequired
        Up to 24 characters.
      • #descriptionstringRequired
        Up to 72 characters.
  • #stickerobjectOptional
    Inside the 24-hour window. A WebP of exactly 512 by 512 pixels, under 100 KB.
    1 child parameter
    • #urlstringRequired
      A public link to the sticker.
  • #locationobjectOptional
    Inside the 24-hour window. A pin the customer can open in their maps.
    Example: { "latitude": 6.3005, "longitude": -10.7969, "name": "Office" }
    4 child parameters
    • #latitudenumberRequired
      From -90 to 90.
    • #longitudenumberRequired
      From -180 to 180.
    • #namestringOptional
      Up to 100 characters. The pin shows it.
    • #addressstringOptional
      Up to 200 characters. The pin shows it when there's no name.
  • #contactsobject[]Optional
    Inside the 24-hour window. Up to 10 contact cards. The customer can call or save each one.
    3 child parameters
    • #namestringRequired
      Up to 100 characters.
    • #phonesstring[]Optional
      Up to 5 numbers.
    • #emailsstring[]Optional
      Up to 5 email addresses.
  • #templateobjectOptional
    An approved template by its ID, with its values. See Send a template.
    Example: { "id": "6f1c2a3e-8b4d-4e5f-9a1b-2c3d4e5f6a7b", "body": ["Blama"] }
    3 child parameters
    • #idstringRequired
      The Template ID from WhatsApp › Templates in the app. It must be approved for the number you send from.
    • #bodystring[]Optional
      The values for {{1}}, {{2}} and so on, in order. Up to 20 values of up to 1,024 characters each.
    • #buttonsstring[]Optional
      The values for the buttons' placeholders, in order.
  • #smsFallbackobjectOptional
    An SMS to send instead if the number isn't on WhatsApp. See If they're not on WhatsApp.
    Example: { "sender": "ACME", "text": "Your order 42 is ready." }
    2 child parameters
    • #senderstringRequired
      Your approved SMS Sender ID or Short Code.
    • #textstringRequired
      Up to 640 characters. {{firstname}}, {{lastname}} and {{fullname}} are filled in from your saved contact.

Send the content in one field only: text, image, video, audio, document, sticker, location, contacts or template. buttons, list or link go with text, one of them at a time. Fields not listed here are refused, and so is channel: this path only sends WhatsApp messages. See Sending WhatsApp messages for how WhatsApp works.

Example request​

curl -X POST "https://sandbox-api.ponitor.com/messaging/v1/whatsapp" \
-H "apiKey: $PONITOR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sender": "+231770000000",
"recipient": "+231770123456",
"externalId": "remind-0412",
"template": {
"id": "6f1c2a3e-8b4d-4e5f-9a1b-2c3d4e5f6a7b",
"body": [
"Blama",
"LRD 4,500",
"18 June"
]
}
}'

Responses​

Created. The message was accepted, charged and queued. The body is the message.

{
"message": {
"id": "8d0f3c2a-5b7e-4a91-b6c4-1e2f3a4b5c6d",
"channel": "WHATSAPP",
"direction": "OUTBOUND",
"sender": "+231770000000",
"recipient": "+231770123456",
"messageType": "TEMPLATE",
"inServiceWindow": null,
"template": {
"id": "6f1c2a3e-8b4d-4e5f-9a1b-2c3d4e5f6a7b",
"name": "repayment_reminder",
"language": "en"
},
"text": "Hi Blama, your repayment of LRD 4,500 is due 18 June.",
"status": "QUEUED",
"cost": 0.03,
"failureReason": null,
"failureCode": null,
"externalId": "remind-0412",
"conversationId": null,
"createdAt": "2026-10-05T09:30:00.112Z",
"updatedAt": "2026-10-05T09:30:00.112Z"
}
}

Send a template​

Set template to an approved template's ID and its values. The ID is the Template ID on the template's page in WhatsApp › Templates.

{
"sender": "+231770000000",
"recipient": "+231770123456",
"externalId": "remind-0412",
"template": {
"id": "6f1c2a3e-8b4d-4e5f-9a1b-2c3d4e5f6a7b",
"body": ["Blama", "LRD 4,500", "18 June"],
"buttons": ["loans/0412"]
}
}
FieldTypeMeaning
idstringThe template's ID, from the app. It must be approved for the number you send from.
bodystring[]The values for {{1}}, {{2}} and so on, in order. Up to 20 values of up to 1024 characters each. Leave it out if the template has no placeholders.
buttonsstring[]The values for the buttons' placeholders, in order, such as the end of a link button's address. Leave it out if the buttons have none.

A template belongs to a WhatsApp account. Send it from a number in that account. Each WhatsApp account has its own copy of a template, with its own ID.

The header (text, a photo, a video or a document) is sent as approved. A template with too few or too many values is refused with 400. The message says how many values it takes.

If they're not on WhatsApp​

Add smsFallback to send an SMS if the number isn't on WhatsApp. The WhatsApp message goes first. If WhatsApp reports that the number isn't on WhatsApp, Ponitor sends the SMS once from your Sender ID. It's charged as an SMS.

{
"sender": "+231770000000",
"recipient": "+231880000000",
"externalId": "ready-0412",
"template": { "id": "6f1c2a3e-8b4d-4e5f-9a1b-2c3d4e5f6a7b", "body": ["Blama"] },
"smsFallback": { "sender": "ACME", "text": "Hi {{firstname|there}}, your order 42 is ready." }
}
FieldWhat it is
senderYour approved SMS Sender ID or Short Code.
textUp to 640 characters. {{firstname}}, {{lastname}} and {{fullname}} are filled in from your saved contact.

To cover contacts with no saved name, add a default after a bar. {{firstname|there}} becomes "there".

The SMS is a separate message with its own ID, status and webhook events. The WhatsApp message's smsFallback shows the SMS's messageId once it's sent. Get the WhatsApp message to read it, then get the SMS with that ID. The SMS can't go to a WhatsApp user ID, because there's no number to text.

WhatsApp replies​

Inside the 24-hour window, you can reply with text, one file, a sticker, a location or contact cards. Put it in the field named after its type.

FieldHoldsWhat it takes
textThe text2 to 4,096 characters. WhatsApp formatting (*bold*, _italic_, ~strikethrough~) works.
imageurl, caption (optional)JPEG or PNG, up to 5 MB.
videourl, caption (optional)MP4 with H.264 video and AAC audio, up to 16 MB. The caption is sent as a separate text message after the video is delivered, and charged as a reply.
audiourlOGG with the Opus codec arrives as a voice note. MP3, AAC and AMR arrive as an audio file. Up to 16 MB. No caption.
documenturl, filename (optional), caption (optional)PDF, Word (DOC, DOCX), Excel (XLSX) or PowerPoint (PPTX), up to 20 MB. The caption is sent as a separate text message after the document is delivered, and charged as a reply.
stickerurlA WebP of exactly 512 by 512 pixels, under 100 KB, with a clear background. Not animated.
locationlatitude, longitude, name and address (optional)A pin the customer can open in their maps. The pin shows name, or address if there's no name.
contactsA list of cards: name, phones and emails (optional)Up to 10 cards, each with up to 5 phones and 5 emails. The customer can call or save each one.

Each field goes next to sender, recipient and externalId, as in the example request.

For example, an image with a caption:

"image": {
"url": "https://example.com/receipts/order-42.jpg",
"caption": "Your receipt for order 42"
}

Send text with one of these fields. The customer answers with a tap.

FieldHoldsWhat it takes
buttonsA list of { "id", "title" }Up to 3 reply buttons. Each title up to 20 characters, each id up to 128 and different. text up to 1,024 characters.
listbutton, and items: a list of { "id", "title", "description" }button is the label that opens the list, up to 20 characters. Up to 10 rows. Each row needs a title of up to 24 characters and a description of up to 72. text up to 1,024 characters.
linktitle and urlOne button that opens an https link. title up to 20 characters. text up to 640 characters.
{
"sender": "+231770000000",
"recipient": "+231770123456",
"externalId": "slot-0412",
"text": "Pick a delivery slot",
"list": {
"button": "Slots",
"items": [
{ "id": "am", "title": "Morning", "description": "8am to 12pm" },
{ "id": "pm", "title": "Afternoon", "description": "12pm to 5pm" }
]
}
}

When the customer taps a button or picks a row, the message.received webhook includes reply. It has the id you sent, the title, and a row's description. Match on id. It stays the same when you change the words. Outside the 24-hour window, send an approved template with quick-reply buttons.

  • The link must open without signing in. The file is fetched when the message goes out. Keep the link working until the message is DELIVERED.
  • The link must return the file's real Content-Type, such as image/jpeg or application/pdf. A file whose type doesn't match isn't sent.
  • Send one file per message.
  • filename is for your records. The customer's WhatsApp doesn't show it.

A file costs the same as a text reply. If the file can't be fetched, is too large or has an unsupported type, the message ends as FAILED or UNDELIVERED. The reason is in failureReason. See Delivery statuses.

The message object​

Get a WhatsApp message returns the same object.

FieldTypeMeaning
iduuidPonitor's ID for the message.
channelstringAlways WHATSAPP.
directionstringOUTBOUND for messages you send, INBOUND for messages a customer sends you.
senderstringYour WhatsApp number, or the customer's for a message they sent.
recipientstringThe customer's number, in international format, or yours for a message they sent.
messageTypestring or nullTEMPLATE or FREE_FORM for a message you sent. null for one a customer sent.
inServiceWindowboolean or nullFor a message you sent, whether it went out inside the 24-hour window. null for one a customer sent.
text, image, video, audio, document, sticker, location, contacts, order, templateThe message, in the field named after its type, as you send it. order is a customer's order from your WhatsApp catalog: its catalogId and items (productId, quantity, price, currency). A file has its url (for a received file, a link that works for an hour), and its caption, mimeType, filename and size when known. A template has its id, name and language, and text holds what the customer read.
buttons, list, linkSent with text, as you sent them.
replyobjectSet when the customer tapped a button or quick reply, or picked a list row. Has the id you sent, the title they saw, and a row's description.
referralobjectSet when the customer wrote from your click-to-WhatsApp ad. Has the ad's headline, body, sourceUrl, sourceType, sourceId and clickId.
forwardedstringSet on a forwarded message. FORWARDED, or FREQUENTLY_FORWARDED if it has been forwarded many times.
statusstringQUEUED, SENT, DELIVERED, EXPIRED, UNDELIVERED, UNKNOWN or FAILED. A message a customer sent is DELIVERED. See Delivery statuses.
costnumberWhat the message cost, in US dollars. Refunded if it ends as FAILED.
failureReasonstring or nullWhy the message wasn't delivered, in plain words. Set for EXPIRED, UNDELIVERED and FAILED.
failureCodestring or nullThe same reason as a code that never changes, such as E11001. Branch on it. See Why a message wasn't delivered.
externalIdstring or nullYour reference. null for a message a customer sent.
conversationIduuid or nullGroups the messages with one customer.
smsFallbackobjectOnly if you sent one. Has sender, text and messageId. messageId is the SMS's ID once it's sent, and null until then. See If they're not on WhatsApp.
createdAtdate-timeWhen Ponitor accepted it.
updatedAtdate-timeWhen it last changed, usually its latest status.

Fields from before /whatsapp aren't here: the message is in text or the field named after its type, never content, and the reason is failureReason, not failedReason. /messages and the webhooks still have both.