Whatixo.Docs Français Open Whatixo
Docs / Whatixo API

Send messages

A single endpoint for every message type: text, image, video, audio, voice note and document.

POSThttps://api.whatixo.com/api/whatsapp/messages/send

Parameters

FieldTypeDescription
deviceIdrequiredstringID of the sending number (Settings → Integrations & API). It must belong to you and be connected.
torequiredstringRecipient: international number (243812345678) or a group JID (1203…@g.us).
textoptionalstringMessage text, or the media caption. 4,096 characters max. WhatsApp formatting: *bold*, _italic_, ~strikethrough~, ```code```.
mediaUrloptionalstringPublic https:// link to a file (64 MB max), or the link of a media file from your Library.
fileNameoptionalstringDisplay name for a document (e.g. invoice-1042.pdf). Default: the file name in the URL.
typeoptionalstringtext (default), image, video, audio, ptt or document. Use ptt to send audio as a voice note.
How the media type is chosen

Whatixo detects the file type from the mediaUrl extension:

  • .mp4 .mov .avi .mkv → video
  • .mp3 .ogg .wav .m4a → audio (voice note if type is ptt)
  • .pdf .doc .docx .xls .xlsx .csv .txt .zip → document
  • any other extension → image

So make sure the URL ends with the right extension.

Examples

Text

curl -X POST https://api.whatixo.com/api/whatsapp/messages/send \
  -H "x-api-key: $WHATIXO_API_KEY" -H "Content-Type: application/json" \
  -d '{"deviceId":"8f2c1a7e-4b9d-4e21-9a6f-3c5d7e1b2a90","to":"243812345678","text":"*Order #1042* confirmed ✅\nDelivery scheduled for tomorrow."}'

Image with caption

Request bodyJSON
{
  "deviceId": "8f2c1a7e-4b9d-4e21-9a6f-3c5d7e1b2a90",
  "to": "243812345678",
  "type": "image",
  "mediaUrl": "https://my-store.com/images/november-promo.jpg",
  "text": "30% off this weekend only 🔥"
}

PDF document

Request bodyJSON
{
  "deviceId": "8f2c1a7e-4b9d-4e21-9a6f-3c5d7e1b2a90",
  "to": "243812345678",
  "type": "document",
  "mediaUrl": "https://my-store.com/invoices/1042.pdf",
  "fileName": "Invoice-1042.pdf",
  "text": "Here is your invoice, thanks for your purchase!"
}

Voice note

Request bodyJSON
{
  "deviceId": "8f2c1a7e-4b9d-4e21-9a6f-3c5d7e1b2a90",
  "to": "243812345678",
  "type": "ptt",
  "mediaUrl": "https://my-store.com/audio/welcome.ogg"
}

Message in a group

Request bodyJSON
{
  "deviceId": "8f2c1a7e-4b9d-4e21-9a6f-3c5d7e1b2a90",
  "to": "120363041234567890@g.us",
  "text": "📦 New order to prepare: #1042"
}

Responses

CodeMeaning
200Message handed to WhatsApp: {"success":true,"message":"Transmis avec succès"}
400Missing field (deviceId, to), invalid number, text too long or media unreachable.
401Missing or invalid API key.
402Monthly message quota reached (PLAN_LIMIT) or subscription suspended (ACCOUNT_SUSPENDED).
403The number isn’t connected (“L’appareil n’est pas connecté”): reconnect it in the app.
404Unknown deviceId or one that doesn’t belong to your account.
429More than 200 requests per minute: wait a moment.
502WhatsApp refused the send (number without WhatsApp, blocked number…).

Error messages returned by the API are in French; rely on the HTTP code and the code field when present.

Before sending in volume

First check that the numbers have WhatsApp with /contacts/check, and space out your sends (a few seconds between messages, more for strangers). For a marketing campaign, prefer the app’s campaigns, which handle a safe pace automatically.

Legacy route

POST /whatsapp/send remains available with exactly the same parameters, for existing integrations. Use /whatsapp/messages/send for new projects.