Endpoint
POST /api/v1/messages/send
x-api-key: <api_key>
Le message est accepté en queued, puis envoyé de façon asynchrone.
Depuis la console MsgFlash, les médias peuvent être préparés via un upload temporaire avant l’envoi final. Voir Uploads média temporaires. Paramètres
Body
| Champ | Type | Requis | Description |
|---|
instanceId | UUID | oui | Instance WhatsApp source |
to | string | oui | Numéro E.164 |
type | enum | oui si pas de templateId | Type du message libre |
templateId | UUID | oui si pas de type | Template MsgFlash à utiliser |
text | string | selon type | Corps du message libre |
mediaUrl | string | selon type | URL publique du media |
latitude | number | si type=location | Latitude |
longitude | number | si type=location | Longitude |
locationName | string | non | Nom du lieu |
locationAddress | string | non | Adresse du lieu |
contactId | UUID | non | Contact partagé ou contexte template |
variables | object | non | Valeurs injectées dans custom.* |
Mode 1 — Message libre
Texte
curl -X POST https://srv.msgflash.com/api/v1/messages/send \
-H "x-api-key: msgf_live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"instanceId": "YOUR_INSTANCE_ID",
"to": "+33612345678",
"type": "text",
"text": "Bonjour, votre commande est prête."
}'
Image
Vidéo
Audio
Note vocale
Document
Localisation
Contact
{
"instanceId": "YOUR_INSTANCE_ID",
"to": "+33612345678",
"type": "image",
"mediaUrl": "https://cdn.example.com/banner.jpg",
"text": "Nouvelle collection"
}
{
"instanceId": "YOUR_INSTANCE_ID",
"to": "+33612345678",
"type": "video",
"mediaUrl": "https://cdn.example.com/promo.mp4"
}
{
"instanceId": "YOUR_INSTANCE_ID",
"to": "+33612345678",
"type": "audio",
"mediaUrl": "https://cdn.example.com/message.mp3"
}
{
"instanceId": "YOUR_INSTANCE_ID",
"to": "+33612345678",
"type": "voice_note",
"mediaUrl": "https://cdn.example.com/note.ogg"
}
{
"instanceId": "YOUR_INSTANCE_ID",
"to": "+33612345678",
"type": "document",
"mediaUrl": "https://cdn.example.com/facture.pdf",
"text": "Votre facture"
}
{
"instanceId": "YOUR_INSTANCE_ID",
"to": "+33612345678",
"type": "location",
"latitude": 6.3654,
"longitude": 2.4183,
"locationName": "Boutique Cotonou Centre",
"locationAddress": "Avenue de la Marina, Cotonou"
}
{
"instanceId": "YOUR_INSTANCE_ID",
"to": "+33612345678",
"type": "contact",
"contactId": "CONTACT_UUID"
}
Mode 2 — Envoi via template
Vous pouvez envoyer un message en fournissant templateId à la place de type.
curl -X POST https://srv.msgflash.com/api/v1/messages/send \
-H "x-api-key: msgf_live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"instanceId": "YOUR_INSTANCE_ID",
"to": "+33612345678",
"contactId": "CONTACT_UUID",
"templateId": "TEMPLATE_UUID",
"variables": {
"app": "MsgFlash",
"coupon": "PROMO10"
}
}'
- charge le template
- résout
contact.*, user.*, instance.*
- injecte vos valeurs libres dans
custom.*
- enregistre le texte rendu final dans
Message.body
Exemple de template :
Bonjour {{contact.firstName}}, bienvenue sur {{custom.app}} depuis {{instance.name}}.
contact.*user.*instance.*custom.*
Pour les variables contact.*, fournissez contactId si vous voulez un contexte contact enrichi.
Réponse succès
{
"data": {
"id": "msg_uuid",
"instanceId": "inst_uuid",
"contactId": "cnt_uuid",
"campaignId": null,
"type": "text",
"to": "+33612345678",
"body": "Bonjour Awa, bienvenue sur MsgFlash depuis Boutique Porto-Novo.",
"mediaUrl": null,
"status": "queued",
"providerMessageId": null,
"createdAt": "2026-04-01T10:00:00.000Z",
"updatedAt": "2026-04-01T10:00:00.000Z"
}
}
Erreurs courantes
| Code | HTTP | Quand |
|---|
VALIDATION_ERROR | 400 | Body invalide |
TEMPLATE_INVALID | 400 | Placeholder ou template invalide |
TEMPLATE_VARIABLES_MISSING | 400 | Variables template manquantes |
TEMPLATE_CONTEXT_UNAVAILABLE | 400 | contactId ou instanceId de contexte invalide |
NOT_FOUND | 404 | Instance, contact ou template introuvable |
SUBSCRIPTION_INACTIVE | 403 | Souscription non exploitable |
MONTHLY_OUTBOUND_QUOTA_EXCEEDED | 429 | Quota mensuel épuisé |
Statuts possibles
queued → sent → delivered → read
└──────→ failed
| Statut | Description |
|---|
queued | Message accepté et mis en file |
sent | Transmis à WhatsApp |
delivered | Livré sur l’appareil |
read | Lu par le destinataire |
failed | Échec d’envoi |
Suivre le statut
GET /api/v1/messages/{id}- Webhooks
message.sent, message.delivered, message.read, message.failed
Voir Webhooks.