POST Envoyer un message

Endpoint

POST /api/v1/messages/send

Important — comment obtenir `instanceId`

instanceId est obligatoire pour envoyer un message. Ne pas utiliser à la place :

name
waNumber

Pour obtenir le bon instanceId :

appeler GET /api/v1/instances
sélectionner l’instance voulue
récupérer data[n].id
envoyer cette valeur dans le champ instanceId

Exemple :

id = identifiant technique requis par l’API
name = libellé lisible
waNumber = numéro connecté affiché à l’utilisateur

Body

Champ	Type	Requis	Description
`instanceId`	UUID	oui	Identifiant technique de l’instance MsgFlash, obtenu via `GET /api/v1/instances`
`to`	string	oui	Numéro E.164
`type`	enum	oui si pas de `templateId`	`text`, `image`, `video`, `audio`, `document`, `voice_note`, `location`, `contact`, `buttons`
`templateId`	UUID	oui si pas de `type`	Template à rendre
`text`	string	selon type	Corps du message
`mediaUrl`	string	selon type	URL publique du media
`latitude`	number	si `location`	Latitude
`longitude`	number	si `location`	Longitude
`locationName`	string	non	Nom du lieu
`locationAddress`	string	non	Adresse
`contactId`	UUID	non	Contact partagé ou contexte template
`variables`	object	non	Valeurs `custom.*`
`title`	string	si `buttons`	Titre du message boutons
`description`	string	si `buttons`	Description du message boutons
`footer`	string	non	Pied de page du message boutons
`buttons`	array	si `buttons`	Liste des boutons (max 2)

Boutons

Chaque bouton doit être structuré ainsi :

{
  "title": "reply", // reply | url | call | copy | pix
  "displayText": "Texte du bouton",
  "id": "button_id",
  "url": "https://example.com", // pour type url
  "phoneNumber": "+5511999999999", // pour type call
  "copyCode": "dGV4dA==", // pour type copy
  "currency": "BRL", // pour type pix
  "name": "John Doe", // pour type pix
  "keyType": "random", // pour type pix
  "key": "0ea59ac5-f001-4f0e-9785-c7..." // pour type pix
}

Exemple de requête

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": "INSTANCE_UUID",
    "to": "+33612345678",
    "type": "text",
    "text": "Bonjour"
  }'

Messages avec boutons

Les messages avec boutons nécessitent un compte WhatsApp Business. Ils permettent d’ajouter jusqu’à 2 boutons interactifs.

Types de boutons supportés

Type	Description	Champs requis
`reply`	Bouton de réponse rapide	`displayText`, `id`
`copy`	Bouton pour copier du texte	`displayText`, `copyCode`
`url`	Bouton ouvrant une URL	`displayText`, `url`
`call`	Bouton pour appeler	`displayText`, `phoneNumber`
`pix`	Bouton de paiement Pix (Brésil)	`displayText`, `currency`, `name`, `keyType`, `key`

Exemple de message avec boutons

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": "INSTANCE_UUID",
    "to": "+33612345678",
    "type": "buttons",
    "title": "Choisissez une option",
    "description": "Que souhaitez-vous faire ?",
    "footer": "Répondez rapidement",
    "buttons": [
      {
        "title": "reply",
        "displayText": "Voir le menu",
        "id": "menu_option"
      },
      {
        "title": "url",
        "displayText": "Visiter le site",
        "url": "https://example.com"
      }
    ]
  }'

Réponse succès `201`

{
  "data": {
    "id": "msg_uuid",
    "instanceId": "inst_uuid",
    "contactId": null,
    "campaignId": null,
    "type": "text",
    "to": "+33612345678",
    "body": "Bonjour",
    "mediaUrl": null,
    "status": "queued",
    "warnings": [
      "This instance is still in the warmup phase."
    ],
    "safety": {
      "decision": "warn",
      "riskLevel": "medium",
      "state": "warming",
      "score": 56,
      "reasons": [
        "This instance is still in the warmup phase."
      ],
      "recommendations": [
        "Start with previously engaged contacts before scaling volume."
      ]
    },
    "error": null,
    "providerMessageId": null,
    "createdAt": "2026-04-01T10:00:00.000Z",
    "updatedAt": "2026-04-01T10:00:00.000Z"
  }
}

En V1, les warnings safety n’empêchent pas l’envoi. Ils servent uniquement de guidance.

Erreurs courantes

HTTP	Code	Quand
`400`	`VALIDATION_ERROR`	Body invalide
`400`	`TEMPLATE_INVALID`	Template invalide
`400`	`TEMPLATE_VARIABLES_MISSING`	Variables requises manquantes
`400`	`TEMPLATE_CONTEXT_UNAVAILABLE`	Contact ou instance de contexte invalide
`403`	`SUBSCRIPTION_INACTIVE`	Souscription non exploitable
`403`	`UNSUPPORTED_FEATURE`	Fonctionnalité non supportée (boutons sans WhatsApp Business)
`404`	`NOT_FOUND`	Instance, contact ou template introuvable
`429`	`MONTHLY_OUTBOUND_QUOTA_EXCEEDED`	Quota d’envoi épuisé

GET Santé d'une instance POST Planifier un message

Pour commencer

Guides

Référence API · Équipes

Référence API · Instances

Référence API · Messages

Référence API · Campagnes

Référence API · Modèles

Référence API · Contacts

Référence API · Groupes

Référence API · Number lookups

Référence API · Webhooks

Référence API · Facturation

Ressources

POST Envoyer un message

Endpoint

Important — comment obtenir `instanceId`

Body

Boutons

Exemple de requête

Messages avec boutons

Types de boutons supportés

Exemple de message avec boutons

Réponse succès `201`

Erreurs courantes

​Endpoint

​Important — comment obtenir instanceId

​Body

​Boutons

​Exemple de requête

​Messages avec boutons

​Types de boutons supportés

​Exemple de message avec boutons

​Réponse succès 201

​Erreurs courantes

Endpoint

Important — comment obtenir `instanceId`

Body

Boutons

Exemple de requête

Messages avec boutons

Types de boutons supportés

Exemple de message avec boutons

Réponse succès `201`

Erreurs courantes