API des messages WhatsApp - Envoyer des messages de session

Présentation

L'API des messages WhatsApp envoie des messages WhatsApp libres (texte, images, vidéos, audio et documents) à un client qui vous a écrit au cours des dernières 24 heures. C'est la version API d'une réponse depuis l'Inbox, et le message est enregistré dans la conversation comme n'importe quelle réponse d'agent.

En dehors de la fenêtre de 24 heures, WhatsApp n'accepte que des modèles approuvés. Utilisez pour cela l'API des modèles WhatsApp.

Remarque : l'API d'envoi de messages remplit la même fonction pour tous les canaux, WhatsApp compris, avec une structure de requête unique et des relances sécurisées intégrées. Utilisez l'endpoint de cette page si vous travaillez uniquement avec WhatsApp et des numéros de téléphone.

Prérequis

• Une clé API sur un forfait avec accès à l'API (Pro ou supérieur). Consultez API ChatMaxima.
• Un compte WhatsApp connecté via la Cloud API. Consultez Configuration du canal WhatsApp.
• Une conversation ouverte. Le dernier message que le client vous a envoyé doit dater de moins de 24 heures.

Envoyer un message de session

Texte

curl -X POST https://chatmaxima.com/api/v2/whatsapp/messages/send/ \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "a1b2c3d4e5f6",
    "mobile_no": "+15550001111",
    "reference_id": "ticket-2042",
    "message": "Thanks Jane, your refund has been approved."
  }'

Image, vidéo, audio ou document

Envoyez message sous forme d'objet plutôt que de chaîne :

{
  "account_id": "a1b2c3d4e5f6",
  "mobile_no": "+15550001111",
  "reference_id": "invoice-1001",
  "message": {
    "type": "document",
    "media_url": "https://cdn.example.com/invoice-1001.pdf",
    "file_name": "invoice-1001.pdf",
    "caption": "Your invoice"
  }
}

Champs de la requête

Champ	Type	Obligatoire	Description
mobile_no	string	Oui	Numéro du client avec l'indicatif du pays.
account_id	string	Si vous avez plusieurs numéros	Le compte WhatsApp depuis lequel envoyer, issu de Comptes de canaux.
reference_id	string	Non	Votre propre identifiant. Obligatoire si vous souhaitez recevoir des webhooks pour ce message.
message	string ou objet	Oui	Une chaîne envoie du texte. Un objet envoie le type indiqué.
message.type	string	Sous forme d'objet	text, image, video, audio ou document.
message.text ou message.caption	string	Pour text	Le texte, ou la légende pour un média.
message.media_url	string	Pour les médias	URL https publique du fichier.
message.file_name	string	Non	Nom de fichier affiché pour les documents.

Réponse

{
  "status": "success",
  "code": 201,
  "message": "Message sent",
  "data": {
    "message_id": "wamid.XXXXXXXX",
    "mobile_no": "15550001111",
    "account_id": "a1b2c3d4e5f6",
    "reference_id": "ticket-2042",
    "status": "sent",
    "created_datetime": "2026-11-03 10:05:00"
  }
}

Remarque : les webhooks de livraison, de lecture et d'échec ne sont envoyés que pour les messages de session qui incluent un reference_id. Les envois de modèles les déclenchent toujours.

La fenêtre de 24 heures

ChatMaxima vérifie la fenêtre avant l'envoi. Si le client ne vous a jamais écrit, ou si son dernier message date de plus de 24 heures, la requête échoue avec 422 WINDOW_CLOSED :

{
  "error": {
    "code": "WINDOW_CLOSED",
    "message": "The 24-hour customer service window is closed (last inbound message was 31.4 hours ago). Send an approved template to reopen the conversation.",
    "details": { "window_open": false, "hours_since_last_inbound": 31.4 }
  }
}

Envoyez plutôt un modèle approuvé avec l'API des modèles WhatsApp. Lorsque le client répond, la fenêtre se rouvre pour 24 heures.

Vérifier le statut d'un message

Recherchez n'importe quel message WhatsApp de votre espace de travail grâce à son wamid, qu'il ait été envoyé par l'API, un bot ou un agent. Encodez l'identifiant pour l'URL.

curl https://chatmaxima.com/api/v2/whatsapp/messages/wamid.XXXXXXXX/status/ \
  -H "Authorization: YOUR_API_KEY"

{
  "status": "success",
  "code": 200,
  "data": {
    "message_id": "wamid.XXXXXXXX",
    "status": "delivered",
    "error": null,
    "created_datetime": "2026-11-03 10:05:00",
    "updated_datetime": "2026-11-03 10:05:04"
  }
}

Statut	Signification
sent	WhatsApp a accepté le message.
delivered	Il est arrivé sur le téléphone du client.
read	Le client l'a ouvert. Les notes vocales écoutées comptent aussi comme lues.
failed	WhatsApp n'a pas pu le livrer. error contient le rapport de Meta.

Le statut ne fait qu'avancer. Une mise à jour delivered tardive n'écrase jamais read. Les heures sont exprimées en UTC.

Erreurs

HTTP	Code	Quand elle se produit
422	MISSING_MOBILE_NO	mobile_no est manquant.
422	INVALID_MOBILE_NO	Le numéro ne comporte pas de 7 à 15 chiffres après nettoyage.
422	UNSUPPORTED_MESSAGE_TYPE	message.type ne fait pas partie des types pris en charge.
422	MISSING_MESSAGE	Le texte est vide.
422	MISSING_MEDIA_URL	Un type de média a été envoyé sans media_url.
422	INVALID_MEDIA_URL	media_url n'est pas une URL https.
403	PLAN_EXPIRED	Votre forfait a expiré.
403	MESSAGE_LIMIT_REACHED	Votre quota mensuel de messages est épuisé.
422	ACCOUNT_RESOLUTION_FAILED	account_id n'est pas l'un de vos comptes WhatsApp, aucun compte n'est connecté, ou vous en avez plusieurs et n'en avez transmis aucun.
422	WINDOW_CLOSED	La fenêtre de 24 heures est fermée ou n'a jamais été ouverte.
422	WHATSAPP_SEND_REJECTED	Meta a rejeté le message. details contient l'erreur de Meta.
502	SEND_UNCONFIRMED	ChatMaxima n'a pas pu confirmer l'envoi. Vérifiez le statut avant de réessayer.
404	NOT_FOUND	Recherche de statut : aucun message avec ce wamid dans votre espace de travail.

Les erreurs d'authentification, de forfait et de limite de débit sont listées dans la présentation de l'API.

Bonnes pratiques

• Envoyez toujours reference_id si vous comptez sur les webhooks pour suivre la livraison.
• Vérifiez d'abord la fenêtre dans votre propre logique si vous savez quand le client vous a écrit pour la dernière fois, afin d'éviter des appels en échec.
• Préférez les webhooks à l'interrogation de l'endpoint de statut pour les volumes élevés.

Étapes suivantes

• API des modèles WhatsApp →
• Webhooks WhatsApp →
• API d'envoi de messages →