Enviar mensajes de WhatsApp por API: cURL, Node, Python y 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 y FormData integrados)
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 establece el límite (boundary) del 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",
}
# Envíe cada campo como una parte multipart (files=) y no codificado 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 array (no una cadena) hace que cURL envíe 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"
}

¿Qué campos de la petición son los más importantes?

Los campos obligatorios dependen de messageType. Estos son los habituales.

La programación usa scheduled, scheduleTime y gmt, y delay regula la entrega. La lista completa está en la referencia de la API de WhatsApp.

¿Cómo envío una plantilla con un botón o un OTP?

Añada el valor del botón en buttonsTemplateVariable. Para una plantilla de autenticación con un botón de copiar código, pase el código tanto en el campo del cuerpo como en el del botón.

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

Aquí login_code es un marcador de posición para su propia plantilla de autenticación aprobada. Para varios botones, buttonsTemplateVariable admite un array JSON. Genere el código en su servidor, guárdelo con hash y con caducidad, y no lo registre nunca en logs. Nuestra guía de OTP trata la entrega con un toque, sin toque y con copia de código.

¿Cómo respondo dentro de la ventana de atención al cliente?

Use un tipo de mensaje de sesión. Una respuesta de texto sencillo necesita messageType=TEXT y 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."

Para los botones de respuesta, envíe messageType=INTERACTIVE y un interactivePayload que siga el formato de mensajes interactivos 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"}}]}}'

Para marcar un mensaje entrante como leído y, opcionalmente, mostrar un indicador de escritura, llame a 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 }'

Consulte nuestra guía de mensajes interactivos para orientarse en el diseño.

¿Cómo hago el seguimiento de la entrega?

Los estados se envían al webhook configurado en su cuenta y también pueden consultarse por lote. Cada destinatario pasa por SUBMITTED, SENT, DELIVERED y READ, o termina como 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 es obligatorio; status, destination, search, page y size son opcionales, y page empieza en cero. Use la consulta periódica (polling) como respaldo ante eventos perdidos y construya su receptor como se describe en nuestra guía de webhooks. Los lotes también pueden pausarse, reanudarse y abortarse con los endpoints de lotes de la referencia.

¿Qué errores debo gestionar?

Lea primero el estado HTTP y después el cuerpo del error. La API genera los errores en un cuerpo JSON de cinco campos, y los fallos específicos de WhatsApp pueden proceder de Meta.

Nuestra guía de códigos de error explica los códigos habituales de Meta. Como no hay clave de idempotencia, siga los pasos de protección frente a duplicados de Errores y límites: escriba primero un registro pendiente, guarde el batchId devuelto y, tras un tiempo de espera agotado, compruebe el estado antes de volver a enviar.

Ejemplo práctico: un servicio de notificación de pedidos

"Souq Rafiq" (ficticia), un comercio de los Emiratos Árabes Unidos, envía una plantilla order_update cuando se despacha un pedido.

1. El servicio de pedidos escribe una fila con la clave order-8842-shipped y el estado pending.
2. Llama a sendbulk con la plantilla y el número de pedido como bodyTemplateVariables.
3. Con un 200, guarda el batchId y marca la fila como accepted.
4. El gestor del webhook actualiza la fila a DELIVERED o READ, o a FAILED con un motivo.
5. Si el cliente responde, la herramienta de soporte usa un mensaje de sesión TEXT dentro de la ventana.
6. Un proceso nocturno lee bulk-insights de los lotes del día anterior y concilia los estados que falten.

¿Cuáles son los errores habituales?

• Enviar JSON. El endpoint de envío de WhatsApp es multipart; Content-Type: application/json no funcionará.
• Usar data= en Python en lugar de files=, lo que codifica el formulario en URL.
• Texto libre fuera de la ventana, que falla. Use una plantilla.
• Código de idioma incorrecto, como en en lugar del en_US de la plantilla.
• Tratar un 200 como entregado. Significa en cola.
• Reintentos a ciegas tras un tiempo de espera agotado, que pueden enviar dos veces un mensaje a un cliente.
• El token en código de cliente. Llame a la API solo desde su backend.
• Límites: los detalles de la carga varían según la plantilla. Confirme con nuestro equipo la disposición de las variables para su primera campaña personalizada.

Cómo le ayuda OmniChannels.ai

BroadNet es un Meta Business Solution Provider oficial, y el alta en la API de WhatsApp Business usa el Embedded Signup de Meta; nuestro equipo prepara el registro con usted, mientras que las aprobaciones siguen en manos de Meta. La API REST está documentada con una especificación OpenAPI 3.1 y un SDK de TypeScript, @broadnet/cpaas-sdk, y los estados de entrega se normalizan entre canales. Empiece con la documentación de la API de WhatsApp o el inicio rápido.