Inviare un messaggio WhatsApp via 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 e FormData integrati)
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 imposta il boundary 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",
}
# Inviate ogni campo come parte multipart (files=) e non url-encoded (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 array (non una stringa) fa inviare a cURL multipart/form-data.
    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"
}

Quali campi della richiesta contano di più?

I campi obbligatori dipendono da messageType. Questi sono i più comuni.

La programmazione dell'invio usa scheduled, scheduleTime e gmt, mentre delay rallenta la consegna. L'elenco completo è nel riferimento dell'API WhatsApp.

Come si invia un template con un pulsante o un OTP?

Aggiungete il valore del pulsante in buttonsTemplateVariable. Per un template di autenticazione con pulsante «copia codice», passate il codice sia nel corpo sia nei campi del pulsante.

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

Qui login_code è un segnaposto per il vostro template di autenticazione approvato. Con più pulsanti, buttonsTemplateVariable accetta un array JSON. Generate il codice sul server, memorizzatelo come hash con una scadenza e non registratelo mai nei log. La nostra guida agli OTP tratta la consegna one-tap, zero-tap e copy-code.

Come si risponde all'interno della finestra di assistenza clienti?

Usate un tipo di messaggio di sessione. Una risposta in testo semplice richiede messageType=TEXT e 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."

Per i pulsanti di risposta, inviate messageType=INTERACTIVE e un interactivePayload che segua il formato dei messaggi interattivi di 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"}}]}}'

Per segnare come letto un messaggio in arrivo, e facoltativamente mostrare l'indicatore di scrittura, chiamate POST /whatsapp/message/read con 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 }'

Consultate la nostra guida ai messaggi interattivi per indicazioni di progettazione.

Come si traccia la consegna?

Gli stati vengono inviati al webhook configurato sul vostro account e si possono leggere anche per batch. Ogni destinatario passa da SUBMITTED, SENT, DELIVERED e READ, oppure termina come FAILED o REJECTED con un motivo.

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 è obbligatorio; status, destination, search, page e size sono facoltativi e page parte da zero. Usate il polling come rete di sicurezza per gli eventi persi e costruite il vostro ricevitore come descritto nella nostra guida ai webhook. I batch si possono anche mettere in pausa, riprendere e interrompere con gli endpoint dei batch descritti nel riferimento.

Quali errori devo gestire?

Leggete prima lo stato HTTP, poi il corpo dell'errore. L'API segnala gli errori in un corpo JSON a cinque campi e i fallimenti specifici di WhatsApp possono provenire da Meta.

La nostra guida ai codici di errore spiega i codici Meta più comuni. Poiché non esiste una chiave di idempotenza, seguite i passaggi di protezione dai duplicati in Errori e limiti: scrivete prima un record in sospeso, memorizzate il batchId restituito e dopo un timeout controllate lo stato prima di inviare di nuovo.

Esempio pratico: un servizio di notifica degli ordini

«Souq Rafiq» (nome di fantasia), un rivenditore degli Emirati, invia un template order_update quando un ordine viene spedito.

1. Il servizio ordini scrive una riga con chiave order-8842-shipped e stato pending.
2. Chiama sendbulk con il template e il numero d'ordine come bodyTemplateVariables.
3. Con 200 memorizza il batchId e segna la riga come accepted.
4. Il gestore del webhook aggiorna la riga a DELIVERED o READ, oppure FAILED con un motivo.
5. Se il cliente risponde, lo strumento di assistenza usa un messaggio di sessione TEXT all'interno della finestra.
6. Un job notturno legge bulk-insights per i batch del giorno prima e riconcilia gli eventuali stati mancanti.

Quali sono gli errori comuni?

• Inviare JSON. L'endpoint di invio WhatsApp è multipart; Content-Type: application/json non funziona.
• data= in Python invece di files=, che esegue l'url-encoding del form.
• Testo libero fuori dalla finestra, che fallisce. Usate un template.
• Codice lingua sbagliato, come en invece di en_US del template.
• Considerare 200 come consegnato. Significa in coda.
• Nuovi tentativi alla cieca dopo un timeout, che possono scrivere due volte a un cliente.
• Token nel codice client. Chiamate l'API solo dal backend.
• Limiti: i dettagli del payload variano per template. Confermate con il nostro team la struttura delle variabili per la prima campagna personalizzata.

Come vi aiuta OmniChannels.ai

BroadNet è un Meta Business Solution Provider ufficiale e l'attivazione sulla WhatsApp Business API usa l'Embedded Signup di Meta; il nostro team prepara la registrazione con voi, mentre le approvazioni restano a Meta. L'API REST è documentata con una specifica OpenAPI 3.1 e un SDK TypeScript, @broadnet/cpaas-sdk, e gli stati di consegna sono normalizzati tra i canali. Partite dalla documentazione dell'API WhatsApp o dal quickstart.