Enviar mensagem de WhatsApp por 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 nativos)
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}` }, // o fetch define o boundary do 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",
}
# Envie cada campo como uma parte multipart (files=) em vez de codificado em 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")],
    // Um array (não uma string) faz o cURL enviar 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"
}

Quais campos da requisição mais importam?

Os campos obrigatórios dependem do messageType. Estes são os mais comuns.

O agendamento usa scheduled, scheduleTime e gmt, e delay regula o ritmo da entrega. A lista completa está na referência da API de WhatsApp.

Como envio um template com botão ou um OTP?

Adicione o valor do botão em buttonsTemplateVariable. Para um template de autenticação com um botão de copiar código, passe o código tanto no corpo quanto nos campos do botão.

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

Aqui login_code é um espaço reservado para o seu próprio template de autenticação aprovado. Para vários botões, buttonsTemplateVariable recebe um array JSON. Gere o código no seu servidor, guarde-o com hash e uma expiração e nunca o registre em logs. Nosso guia de OTP cobre a entrega com um toque, sem toque e com copiar código.

Como respondo dentro da janela de atendimento ao cliente?

Use um tipo de mensagem de sessão. Uma resposta em texto simples precisa de 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."

Para botões de resposta, envie messageType=INTERACTIVE e um interactivePayload que siga o formato de mensagem interativa da 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 uma mensagem recebida como lida e, opcionalmente, mostrar um indicador de digitação, chame POST /whatsapp/message/read com 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 }'

Veja nosso guia de mensagens interativas para orientações de design.

Como rastreio a entrega?

Os status são enviados por push para o webhook configurado na sua conta e também podem ser lidos por lote. Cada destinatário passa por SUBMITTED, SENT, DELIVERED e READ ou termina como FAILED ou REJECTED com um 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 é obrigatório; status, destination, search, page e size são opcionais, e page começa em zero. Use consultas periódicas como reforço para eventos perdidos e monte o seu receptor como descrito no nosso guia de webhooks. Os lotes também podem ser pausados, retomados e abortados com os endpoints de lote da referência.

Que erros devo tratar?

Leia primeiro o status HTTP e depois o corpo do erro. A API gera erros em um corpo JSON de cinco campos, e falhas específicas do WhatsApp podem vir da Meta.

Nosso guia de códigos de erro explica os códigos comuns da Meta. Como não há chave de idempotência, siga os passos de proteção contra duplicatas em Erros e limites: grave primeiro um registro pendente, guarde o batchId devolvido e, após um timeout, verifique o status antes de enviar de novo.

Exemplo prático: um serviço de notificação de pedidos

A "Souq Rafiq" (sintética), uma varejista dos Emirados Árabes Unidos, envia um template order_update quando um pedido é despachado.

1. O serviço de pedidos grava uma linha com a chave order-8842-shipped e status pending.
2. Ele chama sendbulk com o template e o número do pedido como bodyTemplateVariables.
3. Em um 200, guarda o batchId e marca a linha como accepted.
4. O handler do webhook atualiza a linha para DELIVERED ou READ, ou FAILED com um motivo.
5. Se o cliente responder, a ferramenta de suporte usa uma mensagem de sessão TEXT dentro da janela.
6. Um job noturno lê o bulk-insights dos lotes de ontem e concilia os status que faltarem.

Quais são os erros comuns?

• Enviar JSON. O endpoint de envio do WhatsApp é multipart; Content-Type: application/json não funciona.
• data= no Python em vez de files=, o que codifica o formulário em URL.
• Texto livre fora da janela, que falha. Use um template.
• Código de idioma errado, como en em vez do en_US do template.
• Tratar o 200 como entregue. Ele significa enfileirada.
• Novas tentativas às cegas após um timeout, que podem enviar a mensagem duas vezes ao cliente.
• Token em código de cliente. Chame a API apenas a partir do seu backend.
• Limites: os detalhes do payload variam por template. Confirme com a nossa equipe o layout das variáveis para a sua primeira campanha personalizada.

Como a OmniChannels.ai ajuda

A BroadNet é uma Meta Business Solution Provider oficial, e o onboarding da API do WhatsApp Business usa o Embedded Signup da Meta; nossa equipe prepara o registro com você, enquanto as aprovações continuam com a Meta. A API REST é documentada com uma especificação OpenAPI 3.1 e um SDK TypeScript, @broadnet/cpaas-sdk, e os status de entrega são normalizados entre os canais. Comece pela documentação da API de WhatsApp ou pelo quickstart.