API pública de transmissão

Visão geral

A API pública de transmissão permite que sistemas externos acessem os números do WhatsApp Business da sua organização. Cada solicitação é vinculada a uma organização pela chave de API, e todos os números WABA utilizados devem pertencer a essa organização. Existem duas famílias de endpoints em /broadcast/public:

Endpoints v2: usam a chave de autenticação da organização e são os endpoints documentados nesta página.
Endpoints legados: continuam usando a chave WABA anterior por número e permanecem inalterados. Consulte Endpoints legados.

Configuração base

Configuração	Valor
URL	`https://cerberus.eazybe.com/prod/api/v2`
Caminho base	`/broadcast/public`
Autenticação	Cabeçalho `x-api-key`
Content-Type	`application/json`

Antes de começar

Mantenha a chave no servidor. Ela permite enviar mensagens de todos os números do WhatsApp da sua organização. Armazene-a em variáveis de ambiente ou em um gerenciador de segredos; nunca a inclua em código web ou móvel.

Comece aqui. Consulte Obter números de telefone para identificar os números WABA disponíveis e Obter modelos para confirmar que o modelo foi aprovado antes do envio.

Fluxo de autenticação

Usar a chave de autenticação nos cabeçalhos da solicitação

Todos os endpoints de transmissão exigem a chave de autenticação gerada no cabeçalho x-api-key, disponível em Workspace → Staff.

x-api-key: YOUR_API_KEY

Armazene sua chave de API com segurança. Evite regenerá-la desnecessariamente.

Encontre a chave de autenticação da sua organização na seção Staff

O que a chave resolve

A chave identifica sua organização. Em endpoints que usam fromPhoneNumber ou phone_number, a API verifica adicionalmente se o número está registrado nessa organização e se seu registro WABA está completo – waba_id, phone_number_id, phone_number e access_token devem estar todos presentes. Uma incompatibilidade retorna 401, não 403.

Índice de endpoints

Método	Ponto final	Finalidade	Autenticação
`GET`	`/broadcast/public/phone-numbers`	Liste os números WABA em sua organização	Obrigatório
`GET`	`/broadcast/public/templates`	Listar modelos aprovados para um número	Obrigatório
`POST`	`/broadcast/public/send-template-broadcast`	Envie um modelo para vários destinatários	Obrigatório
`POST`	`/broadcast/public/send-freeform`	Envie uma mensagem de formato livre	Obrigatório
`GET`	`/broadcast/public/status/:jobId`	Consultar um trabalho de transmissão de grande porte	Obrigatório
`GET`	`/broadcast/public/health`	Status do serviço e lista de endpoints	Nenhum

Obter números de telefone

Lista todos os números do WhatsApp Business registrados na sua organização. Use o phone_number retornado como fromPhoneNumber nos endpoints de envio.

Endpoint

GET /broadcast/public/phone-numbers

Solicitação

curl "https://cerberus.eazybe.com/prod/api/v2/broadcast/public/phone-numbers" \
  -H "x-api-key: $API_KEY"

Resposta

200 — Números de telefone obtidos com sucesso

{
  "status": true,
  "status_code": 200,
  "message": "Phone numbers fetched successfully",
  "data": [
    {
      "phone_number": "14844634680",
      "waba_id": "1099052972334241",
      "phone_number_id": "894234333763517"
    }
  ]
}

Uma matriz data vazia significa que a chave é válida, mas nenhum número WABA está conectado à organização ainda. Esse é um estado de configuração, não um erro.

Obter modelos

Retorna os modelos aprovados do WhatsApp disponíveis para um de seus números. Consulte este endpoint antes de uma transmissão – enviar um nome de modelo não aprovado ou com erro ortográfico falha em toda a solicitação.

Endpoint

GET /broadcast/public/templates

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`phone_number`	corda	Obrigatório	Um número WABA pertencente à sua organização, apenas dígitos

Solicitação

curl "https://cerberus.eazybe.com/prod/api/v2/broadcast/public/templates?phone_number=14844634680" \
  -H "x-api-key: $API_KEY"

Resposta

200 — Modelos obtidos com sucesso

{
  "status": true,
  "status_code": 200,
  "message": "Templates fetched successfully",
  "data": [
    {
      "name": "eazybe_temp",
      "status": "APPROVED",
      "category": "MARKETING",
      "language": "en",
      "components": [
        { "type": "BODY", "text": "Hello {{1}}, your code is {{2}}." }
      ]
    }
  ]
}

Conte os espaços reservados {{n}} no corpo - é exatamente quantos valores a matriz templateParams de cada destinatário deve fornecer.

Enviar modelo de transmissão

Envia um modelo aprovado para uma lista de destinatários. O comportamento muda com o tamanho da lista: até 1.000 destinatários a transmissão é enfileirada de forma síncrona; acima disso, a lista é dividida em partes e processado como um trabalho em segundo plano cujo status pode ser consultado.

Endpoint

POST /broadcast/public/send-template-broadcast

Cabeçalhos

Cabeçalho	Obrigatório	Descrição
`x-api-key`	Obrigatório	Chave de autorização da organização
`Content-Type`	Obrigatório	`application/json`
`Idempotency-Key`	Opcional	String exclusiva, segura para tentar novamente

Corpo

Campo	Tipo	Obrigatório	Descrição
`broadcastName`	corda	Obrigatório	Rótulo da campanha mostrado nos relatórios
`fromPhoneNumber`	corda	Obrigatório	Seu número WABA, em Obter números de telefone
`templateName`	corda	Obrigatório	Nome do modelo aprovado
`templateLanguage`	corda	Obrigatório	Código de idioma, por ex. `en`
`templateType`	corda	Obrigatório	`MARKETING`, `UTILITY` e assim por diante
`templateId`	corda	Opcional	ID do modelo do WhatsApp
`globalTemplateParams`	string[]	Opcional	Padrões aplicados a destinatários sem parâmetros próprios
`data`	objeto[]	Obrigatório	Destinatários, 1 a 10.000

Objeto destinatário

Campo	Tipo	Obrigatório	Descrição
`countryCode`	corda	Obrigatório	Apenas dígitos, sem `+`. por exemplo `91`
`toPhoneNumber`	corda	Obrigatório	Apenas dígitos, sem código do país
`templateParams`	string[]	Opcional	Valores para `{{1}}`, `{{2}}`… Substitui globais.

Solicitação

curl -X POST "https://cerberus.eazybe.com/prod/api/v2/broadcast/public/send-template-broadcast" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: festive-run-1" \
  -d '{
    "broadcastName": "Festive Offer Campaign",
    "fromPhoneNumber": "14844634680",
    "templateName": "eazybe_temp",
    "templateLanguage": "en",
    "templateType": "MARKETING",
    "templateId": "1530766784804741",
    "globalTemplateParams": ["Valued customer", "FESTIVE10"],
    "data": [
      {
        "countryCode": "91",
        "toPhoneNumber": "9675360316",
        "templateParams": ["Vineet", "VIP20"]
      },
      {
        "countryCode": "91",
        "toPhoneNumber": "8077378155"
      }
    ]
  }'

Neste exemplo, o primeiro destinatário obtém seus próprios valores e o segundo volta para globalTemplateParams.

Respostas

200 — Na fila (1.000 destinatários ou menos)

{
  "status": true,
  "status_code": 200,
  "message": "Bulk broadcast queued successfully",
  "data": { }
}

202 — Aceito para processamento em segundo plano (mais de 1.000 destinatários)

{
  "status": true,
  "status_code": 202,
  "message": "Broadcast accepted for background processing",
  "data": {
    "jobId": "pub_4f8c2a1e9b7d43c6a5e0f2b18d3c9a67",
    "status": "PROCESSING",
    "totalRecipients": 1001,
    "chunkSize": 1000,
    "totalChunks": 2
  }
}

Guarde o jobId — é a única forma de verificar como terminou a transmissão. Consulte Obter status da transmissão usando esse identificador. 400 — Limite de destinatários excedido

{
  "status": false,
  "status_code": 400,
  "message": "Recipient limit exceeded",
  "data": {
    "error": {
      "message": "Template broadcast cannot exceed 10000 recipients per request."
    }
  }
}

400 — Modelo não aprovado

{
  "status": false,
  "status_code": 400,
  "message": "Template is not approved or not found",
  "data": {
    "error": {
      "message": "Template is not approved or not found for this WABA phone number."
    }
  }
}

Destinatários duplicados são rejeitados, não mesclados. Se o mesmo par countryCode + toPhoneNumber aparecer duas vezes, toda a solicitação falhará com um 400 nomeando o índice da duplicata. Desduplicar sua lista antes de enviar.

Enviar mensagem de formato livre

Envia uma única mensagem para um destinatário. Todos os oito tipos de conteúdo compartilham este endpoint — o campo type decide quais outros campos são obrigatórios.

Endpoint

POST /broadcast/public/send-freeform

Campos comuns

Campo	Tipo	Obrigatório	Descrição
`fromPhoneNumber`	corda	Obrigatório	Seu número WABA
`toPhoneNumber`	corda	Obrigatório	Destinatário com código do país, apenas dígitos
`type`	corda	Obrigatório	Um dos oito tipos abaixo

Campos específicos do tipo

`type`	Obrigatório	Opcional	Extensões de arquivo aceitas
`text`	`text`	—	—
`image`	`url`	`caption`	jpg, jpeg, png
`document`	`url`	`name`, `caption`	pdf, txt, doc, docx, ppt, pptx, xls, xlsx
`audio`	`url`	—	aac, amr, mp3, m4a, mp4, ogg, opus
`video`	`url`	`caption`	mp4, 3gp
`sticker`	`url`	—	webp
`location`	`latitude`, `longitude`	`name`, `address`	—
`interactive`	`interactive`	—	—

A extensão é lida a partir do caminho do URL, não do arquivo. Um PNG real servido a partir de um URL que termina em .webp é rejeitado para image, e um URL sem extensão é rejeitado para cada tipo de mídia. As strings de consulta são ignoradas, então …/photo.png?v=2 está bem.

Texto

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "text",
  "text": "Your order #4821 has shipped."
}

Imagem

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "image",
  "url": "https://cdn.example.com/offer.jpg",
  "caption": "This week only"
}

Documento

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "document",
  "url": "https://cdn.example.com/invoice-4821.pdf",
  "name": "Invoice_4821.pdf",
  "caption": "Your invoice is ready"
}

Áudio

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "audio",
  "url": "https://cdn.example.com/voice-note.mp3"
}

Vídeo

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "video",
  "url": "https://cdn.example.com/demo.mp4",
  "caption": "60-second walkthrough"
}

Adesivo

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "sticker",
  "url": "https://cdn.example.com/thumbs-up.webp"
}

Localização

latitude e longitude devem ser números JSON, não strings. A latitude aceita −90 a 90, longitude −180 a 180.

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "location",
  "latitude": 28.4595,
  "longitude": 77.0266,
  "name": "Eazybe HQ",
  "address": "Sector 44, Gurugram, Haryana 122003"
}

Interativo — botões

Até 3 botões de resposta. Mais de três são rejeitados.

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": { "type": "text", "text": "Renew your plan" },
    "body": { "text": "Your subscription ends in 3 days. Renew now?" },
    "footer": { "text": "Reply STOP to opt out" },
    "action": {
      "buttons": [
        { "type": "reply", "reply": { "id": "renew_yes", "title": "Renew now" } },
        { "type": "reply", "reply": { "id": "renew_later", "title": "Remind me later" } }
      ]
    }
  }
}

Interativo — lista

Até 10 linhas contadas em todas as seções combinadas, não por seção.

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": { "type": "text", "text": "Pick a plan" },
    "body": { "text": "Choose the plan that fits your team." },
    "action": {
      "button": "View plans",
      "sections": [
        {
          "title": "Monthly",
          "rows": [
            { "id": "starter_m", "title": "Starter", "description": "3 seats included" },
            { "id": "growth_m", "title": "Growth", "description": "10 seats included" }
          ]
        }
      ]
    }
  }
}

Resposta

200 — mesmo formato para todos os oito tipos

{
  "status": true,
  "status_code": 200,
  "message": "Free-form message queued successfully",
  "data": { }
}

Obter status da transmissão

Retorna o progresso de um trabalho de transmissão de grande porte — aqueles que retornaram 202 e um jobId. Transmissões de 1.000 destinatários ou menos não criam um trabalho e não têm status para consultar.

Endpoint

GET /broadcast/public/status/:jobId

Solicitação

curl "https://cerberus.eazybe.com/prod/api/v2/broadcast/public/status/pub_4f8c2a1e9b7d43c6a5e0f2b18d3c9a67" \
  -H "x-api-key: $API_KEY"

Respostas

200 — registro de trabalho mais um resumo do progresso do bloco

{
  "status": true,
  "status_code": 200,
  "message": "Broadcast status fetched successfully",
  "data": {
    "jobId": "pub_4f8c2a1e9b7d43c6a5e0f2b18d3c9a67",
    "status": "QUEUED_FOR_PROCESSING",
    "totalRecipients": 1001,
    "totalChunks": 2,
    "summary": { }
  }
}

404 — Trabalho de transmissão não encontrado 401 — O trabalho pertence a uma organização diferente Um trabalho criado por outra organização retorna 401 em vez de 404 — os IDs de trabalho não são enumeráveis entre organizações.

Verificação de integridade

Confirma que o serviço está ativo e lista as rotas que ele expõe atualmente. Nenhuma chave de API necessária.

Endpoint

GET /broadcast/public/health

{
  "status": "ok",
  "timestamp": "2026-07-22T11:04:33.812Z",
  "service": "Public Broadcast API",
  "version": "2.0.0",
  "endpoints": {
    "generate-key": "POST /broadcast/public/generate-key",
    "template-broadcast": "POST /broadcast/public/send-template-broadcast",
    "freeform": "POST /broadcast/public/send-freeform",
    "templates": "GET /broadcast/public/templates",
    "phone-numbers": "GET /broadcast/public/phone-numbers",
    "status": "GET /broadcast/public/status/:jobId",
    "single": "POST /broadcast/public/send-single",
    "bulk-standard": "POST /broadcast/public/send-bulk",
    "health": "GET /broadcast/public/health"
  }
}

Regras de validação

Eles são executados antes que qualquer coisa chegue ao WhatsApp, portanto, uma rejeição aqui não custa cota de mensagens. Cada falha retorna 400 com message: "Validation error" e um motivo específico.

Regra	Aplica-se a	Em caso de falha
Os números de telefone devem conter apenas dígitos — sem `+`, espaços ou travessões	Ambos enviam endpoints	`toPhoneNumber` / `countryCode` inválido
Pelo menos um destinatário	Transmissão de modelo	A lista de destinatários é obrigatória
Nenhuma duplicata `countryCode` • `toPhoneNumber`	Transmissão de modelo	Destinatário duplicado encontrado no índice n
Máximo de 10.000 destinatários	Transmissão de modelo	Limite de destinatários excedido
O modelo deve existir e ser aprovado para esse número	Transmissão de modelo	O modelo não foi aprovado ou não foi encontrado
`text` deve ser uma string não vazia	Formato livre, digite `text`	texto é necessário para mensagens de texto
`url` deve ser http ou https	Tipos de mídia de formato livre	url deve ser um URL http ou https válido
A extensão de URL deve estar na lista de permitidos	Tipos de mídia de formato livre	Lista as extensões aceitas
Latitude −90 a 90, longitude −180 a 180, ambos os números	Formato livre, digite `location`	Nomeia a coordenada incorreta
O tipo interativo deve ser `button` ou `list`	Formato livre, digite `interactive`	o tipo interativo deve ser botão ou lista
1 a 3 botões	Botões interativos	Não pode exceder 3 botões
1 a 10 linhas em todas as seções	Lista interativa	Não pode exceder 10 linhas

Limites de taxa

Os limites são contados em uma janela fixa de 60 segundos. A maioria tem como escopo sua chave de API e o número de telefone na solicitação, portanto, dois números de envio diferentes não competem pelo mesmo orçamento.

Ponto final	Limite	Contado por
`send-template-broadcast`	10/min	chave + fromPhoneNumber
`send-freeform`	20/min	chave + fromPhoneNumber
`templates`	20/min	chave + phone_number
`phone-numbers`	30/min	chave
`status`	30/min	chave

Excedendo um limite

{
  "status": false,
  "status_code": 429,
  "message": "Rate limit exceeded",
  "data": {
    "error": {
      "message": "Rate limit exceeded. Try again in 43 seconds."
    }
  }
}

A mensagem informa exatamente quantos segundos restam na janela. Espere tanto tempo em vez de tentar novamente imediatamente – uma nova tentativa imediata não consome nada, mas retorna o mesmo erro.

Tratamento de erros

Cada erro usa o mesmo envelope:

{
  "status": false,
  "status_code": 400,
  "message": "Short summary",
  "data": {
    "error": {
      "message": "Specific detail about what to fix"
    }
  }
}

Códigos de status

Código	Significado	O que fazer
`200`	Na fila ou buscado	—
`202`	Transmissão de grande porte aceita	Consulte o status com o `jobId`
`400`	Validação ou falha de limite	Leia `data.error.message` e corrija a payload
`401`	Problema de chave, número ou propriedade do trabalho	Veja a tabela abaixo
`404`	Trabalho de transmissão não encontrado	Verifique o `jobId`
`409`	O mesmo `Idempotency-Key` ainda em processamento	Espere e pesquise; não reenvie
`429`	Limite de taxa excedido	Aguarde os segundos indicados na mensagem
`500`	Enviar falhou downstream	Tente novamente com o mesmo `Idempotency-Key`
`503`	O tempo limite do banco de dados de autenticação expirou	Tente novamente com espera

Os quatro erros 401

Todos os quatro retornam 401, mas significam coisas diferentes:

Mensagem	Causa	Correção
A chave de API é obrigatória	Nenhum cabeçalho `x-api-key`	Adicione o cabeçalho
Chave de API inválida. Organização não encontrada.	Nenhuma organização possui esse `auth_key`	Verifique a chave e se você está no ambiente certo
Nenhuma conta WABA encontrada para esta organização.	O número não está registrado na sua organização	Use um número em Obter números de telefone
A conta WABA está incompleta. Campos ausentes: …	O registro WABA está faltando `waba_id`, `phone_number_id`, `phone_number` ou `access_token`	Conclua a integração do WABA para esse número

Política de nova tentativa. Tente novamente 500 e 503 com espera exponencial. Nunca tente novamente 400 ou 401 — a mesma solicitação falhará de forma idêntica. Em 429, aguarde o intervalo dos nomes das respostas. Sempre envie um Idempotency-Key nas solicitações que você pretende tentar novamente.

Endpoints legados

Autenticação diferente. Esses três são anteriores à v2 e ainda usam a chave WABA por número mais antiga, não a sua organização auth_key. Eles permanecem inalterados e com suporte, mas novas integrações devem usar os endpoints v2 acima.

POST /broadcast/public/generate-key      no auth · 5/min

Gera uma chave de API herdada para um número de telefone. Leva phoneNumber, não um ID de organização.

{ "phoneNumber": "919876543210" }

POST /broadcast/public/send-single       legacy key · 30/min

Envia uma mensagem modelo. Os campos do destinatário ficam no nível superior, e não em uma matriz data.

POST /broadcast/public/send-bulk         legacy key · 10/min

Envio de modelos em massa, limitado a 1.000 destinatários — não há agrupamento nem ID de trabalho. Exceder o limite retorna 400 no corpo da resposta com uma linha de status HTTP 200, ao contrário do endpoint v2 que é lançado.

​Visão geral

​Configuração base

​Antes de começar

​Fluxo de autenticação

​Usar a chave de autenticação nos cabeçalhos da solicitação

​O que a chave resolve

​Índice de endpoints

​Obter números de telefone

​Endpoint

​Solicitação

​Resposta

​Obter modelos

​Endpoint

​Parâmetros de consulta

​Solicitação

​Resposta

​Enviar modelo de transmissão

​Endpoint

​Cabeçalhos

​Corpo

​Objeto destinatário

​Solicitação

​Respostas

​Enviar mensagem de formato livre

​Endpoint

​Campos comuns

​Campos específicos do tipo

​Texto

​Imagem

​Documento

​Áudio

​Vídeo

​Adesivo

​Localização

​Interativo — botões

​Interativo — lista

​Resposta

​Obter status da transmissão

​Endpoint

​Solicitação

​Respostas

​Verificação de integridade

​Endpoint

​Regras de validação

​Limites de taxa

​Excedendo um limite

​Tratamento de erros

​Códigos de status

​Os quatro erros 401

​Endpoints legados

Visão geral

Configuração base

Antes de começar

Fluxo de autenticação

Usar a chave de autenticação nos cabeçalhos da solicitação

O que a chave resolve

Índice de endpoints

Obter números de telefone

Endpoint

Solicitação

Resposta

Obter modelos

Endpoint

Parâmetros de consulta

Solicitação

Resposta

Enviar modelo de transmissão

Endpoint

Cabeçalhos

Corpo

Objeto destinatário

Solicitação

Respostas

Enviar mensagem de formato livre

Endpoint

Campos comuns

Campos específicos do tipo

Texto

Imagem

Documento

Áudio

Vídeo

Adesivo

Localização

Interativo — botões

Interativo — lista

Resposta

Obter status da transmissão

Endpoint

Solicitação

Respostas

Verificação de integridade

Endpoint

Regras de validação

Limites de taxa

Excedendo um limite

Tratamento de erros

Códigos de status

Os quatro erros 401

Endpoints legados