Envoyer un message WhatsApp par API : cURL, Node, Python, PHP

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F campaignName=order-updates \
  -F destinationNo=971500000000 \
  -F messageType=TEMPLATE \
  -F templateName=order_update \
  -F templateLanguage=en_US \
  -F bodyTemplateVariables=INV-400

// Node.js 18+ (fetch et FormData intégrés)
const form = new FormData();
form.append("batchId", "0");
form.append("campaignName", "order-updates");
form.append("destinationNo", "971500000000");
form.append("messageType", "TEMPLATE");
form.append("templateName", "order_update");
form.append("templateLanguage", "en_US");
form.append("bodyTemplateVariables", "INV-400");

const res = await fetch("https://api.broadnet.me/whatsapp/message/sendbulk", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BROADNET_TOKEN}` }, // fetch définit la frontière multipart
  body: form,
});
console.log(await res.json());

import os
import requests

fields = {
    "batchId": "0",
    "campaignName": "order-updates",
    "destinationNo": "971500000000",
    "messageType": "TEMPLATE",
    "templateName": "order_update",
    "templateLanguage": "en_US",
    "bodyTemplateVariables": "INV-400",
}
# Envoyez chaque champ comme une partie multipart (files=) plutôt qu'encodé en URL (data=).
r = requests.post(
    "https://api.broadnet.me/whatsapp/message/sendbulk",
    headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
    files={k: (None, v) for k, v in fields.items()},
    timeout=30,
)
print(r.json())

<?php
$ch = curl_init("https://api.broadnet.me/whatsapp/message/sendbulk");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("BROADNET_TOKEN")],
    // Un tableau (et non une chaîne) fait envoyer du multipart/form-data par cURL.
    CURLOPT_POSTFIELDS => [
        "batchId" => "0",
        "campaignName" => "order-updates",
        "destinationNo" => "971500000000",
        "messageType" => "TEMPLATE",
        "templateName" => "order_update",
        "templateLanguage" => "en_US",
        "bodyTemplateVariables" => "INV-400",
    ],
]);
echo curl_exec($ch);
curl_close($ch);

{
  "totalFiles": 1,
  "totalSuccess": 1,
  "totalFailed": 0,
  "totalDuplicates": 0,
  "batchId": "2609091405000000001",
  "fileResults": [
    {
      "fileName": "direct",
      "totalRecords": 1,
      "successCount": 1,
      "failedRecipients": [],
      "duplicateRecipients": []
    }
  ],
  "message": "Messages queued for delivery"
}

Quels champs de la requête comptent le plus ?

Les champs obligatoires dépendent de messageType. Voici les plus courants.

La planification utilise scheduled, scheduleTime et gmt, et delay limite le rythme de livraison. La liste complète figure dans la référence de l'API WhatsApp.

Comment envoyer un modèle avec un bouton ou un OTP ?

Ajoutez la valeur du bouton dans buttonsTemplateVariable. Pour un modèle d'authentification avec bouton de copie du code, transmettez le code à la fois dans le corps et dans le champ du bouton.

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=971500000000 \
  -F messageType=TEMPLATE \
  -F templateName=login_code \
  -F templateLanguage=en_US \
  -F bodyTemplateVariables=482913 \
  -F buttonsTemplateVariable=482913

Ici, login_code est un espace réservé pour votre propre modèle d'authentification approuvé. Pour plusieurs boutons, buttonsTemplateVariable accepte un tableau JSON. Générez le code côté serveur, stockez-le haché avec une expiration et ne le journalisez jamais. Notre guide des OTP couvre la livraison en un appui, sans appui et par copie de code.

Comment répondre dans la fenêtre de service client ?

Utilisez un type de message de session. Une réponse en texte simple nécessite messageType=TEXT et content.

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=971500000000 \
  -F messageType=TEXT \
  -F campaignName=support \
  -F "content=Your order has shipped. Reply here if you need anything."

Pour des boutons de réponse, envoyez messageType=INTERACTIVE et un interactivePayload conforme au format des messages interactifs de Meta.

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=971500000000 \
  -F messageType=INTERACTIVE \
  -F campaignName=support \
  -F 'interactivePayload={"type":"button","body":{"text":"Confirm your delivery slot?"},"action":{"buttons":[{"type":"reply","reply":{"id":"slot_ok","title":"Confirm"}},{"type":"reply","reply":{"id":"slot_change","title":"Change"}}]}}'

Pour marquer un message entrant comme lu et, facultativement, afficher un indicateur de saisie, appelez POST /whatsapp/message/read avec du JSON :

curl -X POST https://api.broadnet.me/whatsapp/message/read \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "messageId": "wamid.HBgMOTcxNTAwMDAwMDAwFQIAEhgg", "typing": true }'

Consultez notre guide des messages interactifs pour des conseils de conception.

Comment suivre la livraison ?

Les statuts sont poussés vers le webhook configuré sur votre compte et peuvent aussi être lus par lot. Chaque destinataire passe par SUBMITTED, SENT, DELIVERED et READ, ou se termine en FAILED ou REJECTED avec un motif.

curl "https://api.broadnet.me/whatsapp/message/bulk-insights?batch_Id=2609091405000000001&status=FAILED&page=0&size=50" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

batch_Id est obligatoire ; status, destination, search, page et size sont facultatifs, et page commence à zéro. Utilisez l'interrogation en complément pour rattraper les événements manqués, et construisez votre récepteur comme décrit dans notre guide des webhooks. Les lots peuvent aussi être mis en pause, repris et abandonnés via les points de terminaison de lots de la référence.

Quelles erreurs faut-il gérer ?

Lisez d'abord le statut HTTP, puis le corps de l'erreur. L'API renvoie les erreurs dans un corps JSON à cinq champs, et les échecs propres à WhatsApp peuvent venir de Meta.

Notre guide des codes d'erreur explique les codes Meta courants. Faute de clé d'idempotence, suivez les étapes de protection contre les doublons décrites dans Erreurs et limites : écrivez d'abord un enregistrement « en attente », stockez le batchId renvoyé et, après un délai d'attente dépassé, vérifiez le statut avant de renvoyer.

Exemple concret : un service de notification de commandes

« Souq Rafiq » (société fictive), enseigne de distribution aux Émirats arabes unis, envoie un modèle order_update à l'expédition d'une commande.

1. Le service de commandes écrit une ligne de clé order-8842-shipped avec le statut pending.
2. Il appelle sendbulk avec le modèle et le numéro de commande comme bodyTemplateVariables.
3. Sur un 200, il stocke le batchId et marque la ligne accepted.
4. Le gestionnaire de webhook met à jour la ligne en DELIVERED ou READ, ou en FAILED avec un motif.
5. Si le client répond, l'outil de support utilise un message de session TEXT dans la fenêtre.
6. Une tâche de nuit lit bulk-insights pour les lots de la veille et rapproche les statuts manquants.

Quelles sont les erreurs courantes ?

• Envoyer du JSON. Le point de terminaison d'envoi WhatsApp est en multipart ; Content-Type: application/json ne fonctionnera pas.
• data= en Python au lieu de files=, ce qui encode le formulaire en URL.
• Texte libre hors de la fenêtre, qui échoue. Utilisez un modèle.
• Mauvais code de langue, par exemple en au lieu du en_US du modèle.
• Considérer 200 comme « délivré ». Cela signifie « en file d'attente ».
• Nouveaux essais à l'aveugle après un délai dépassé, qui peuvent écrire deux fois au client.
• Jeton dans le code client. Appelez l'API uniquement depuis votre backend.
• Limites : les détails de la charge utile varient selon le modèle. Confirmez la structure des variables avec notre équipe pour votre première campagne personnalisée.

Comment OmniChannels.ai vous aide

BroadNet est un Meta Business Solution Provider officiel, et l'onboarding vers l'API WhatsApp Business passe par l'Embedded Signup de Meta ; notre équipe prépare l'enregistrement avec vous, les approbations restant du ressort de Meta. L'API REST est documentée par une spécification OpenAPI 3.1 et un SDK TypeScript, @broadnet/cpaas-sdk, et les statuts de livraison sont normalisés entre les canaux. Commencez par la documentation de l'API WhatsApp ou le démarrage rapide.