WABA API

Documentação da integração com WhatsApp Business API via rotas públicas da Sendeasy.

Autenticação

Header obrigatório:

Authorization: Bearer <api_token>

Prefixo de rotas

/api/v1/waba/:whatsappId

Templates

Método	Endpoint	Finalidade
`GET`	`/templates`	Listar templates
`POST`	`/templates`	Criar template
`PUT`	`/templates/:templateId`	Atualizar template
`DELETE`	`/templates/:templateName`	Remover template

Mensagens

Método	Endpoint	Finalidade
`POST`	`/send`	Enviar template (ou texto simples via body específico)
`POST`	`/send-text`	Enviar texto
`POST`	`/send-image`	Enviar imagem
`POST`	`/send-video`	Enviar vídeo
`POST`	`/send-audio`	Enviar áudio
`POST`	`/send-document`	Enviar documento
`POST`	`/marketing-lite/send`	Enviar mensagem marketing (Marketing Messages Lite API)
`GET`	`/messages/:messageId/status`	Consultar histórico de status de uma mensagem

Nova API: mensagem marketing

Endpoint público:

POST /api/v1/waba/:whatsappId/marketing-lite/send

Endpoint Meta utilizado pelo backend:

POST /{phone-number-id}/marketing_messages

Pré-requisitos:

Conta WABA com onboarding de Marketing Messages Lite concluído.
Termos de Marketing Messages Lite aceitos na conta Meta.
Template de categoria MARKETING com status APPROVED.

Payload

Campo	Tipo	Obrigatório	Observações
`to`	`string`	Sim	número no formato internacional (somente dígitos)
`templateName`	`string`	Sim	nome do template aprovado no Meta
`language`	`string`	Não	padrão: `pt_BR`
`components`	`array`	Não	componentes/parametrizações do template
`productPolicy`	`string`	Não	`CLOUD_API_FALLBACK` (default) ou `STRICT`
`messageActivitySharing`	`boolean`	Não	padrão: `true`
`bizOpaqueCallbackData`	`string`	Não	volta no webhook para correlação de campanha

Exemplo: envio de mensagem marketing

curl --location 'https://server.sendeasy.pro/api/v1/waba/SEU_WHATSAPP_ID/marketing-lite/send' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SEU_API_TOKEN' \
  --data '{
    "to": "5511999999999",
    "templateName": "promo_blackfriday",
    "language": "pt_BR",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "João" }
        ]
      }
    ],
    "productPolicy": "CLOUD_API_FALLBACK",
    "messageActivitySharing": true,
    "bizOpaqueCallbackData": "campaign_blackfriday_2026"
  }'

Resposta de sucesso (exemplo):

{
  "messages": [
    { "id": "wamid.HBg..." }
  ]
}

Erro de limite/opt-out (exemplo):

{
  "error": "MARKETING_LIMIT_REACHED",
  "message": "User has opted out of marketing messages or reached the limit",
  "details": "..."
}

Exemplo: envio de texto

curl --location 'https://server.sendeasy.pro/api/v1/waba/SEU_WHATSAPP_ID/send-text' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SEU_API_TOKEN' \
  --data '{
    "to": "5511999999999",
    "text": "Olá! Mensagem enviada pela WABA API."
  }'

Exemplo: envio de template

{
  "to": "5511999999999",
  "templateName": "boas_vindas",
  "language": "pt_BR",
  "components": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "João" }
      ]
    }
  ]
}

Template com header de mídia (IMAGE / VIDEO / DOCUMENT)

Quando o template aprovado tiver um header de mídia, é obrigatório enviar o componente header com parameters. O type em minúsculo (header/body), e a imagem precisa estar em uma URL pública sua (S3, CDN, etc.) — não use o header_handle retornado na definição do template, ele expira.

{
  "to": "5511999999999",
  "templateName": "promo_lancamento",
  "language": "es_CO",
  "components": [
    {
      "type": "header",
      "parameters": [
        {
          "type": "image",
          "image": { "link": "https://sua-cdn.com/banner.jpg" }
        }
      ]
    }
  ]
}

Alternativamente, em vez de link use id com o media_id retornado pelo upload em /api/v1/waba/:whatsappId/media.

Consulta de status de mensagem

A Cloud API da Meta não expõe um endpoint público para consultar status sob demanda — o status é entregue exclusivamente via webhook (sent / delivered / read / failed). A Sendeasy persiste cada evento recebido e disponibiliza o histórico nesta rota, com o mesmo formato do payload do webhook.

GET /api/v1/waba/:whatsappId/messages/:messageId/status

Exemplo

curl --location 'https://server.sendeasy.pro/api/v1/waba/SEU_WHATSAPP_ID/messages/wamid.HBg.../status' \
  --header 'Authorization: Bearer SEU_API_TOKEN'

Resposta

{
  "statuses": [
    {
      "id": "wamid.HBgMNTUzMT...",
      "status": "sent",
      "timestamp": "1710000000",
      "recipient_id": "5511999999999"
    },
    {
      "id": "wamid.HBgMNTUzMT...",
      "status": "failed",
      "timestamp": "1710000003",
      "recipient_id": "5511999999999",
      "errors": [
        { "code": 131026, "title": "Message undeliverable" }
      ]
    }
  ]
}

Quando ainda não houver evento gravado para o messageId, a resposta é 404 com statuses: [] — basta tentar de novo após alguns segundos. Apenas mensagens enviadas via canal WABA têm status persistido nesta rota.

Códigos de erro comuns

Código	Quando acontece
`WHATSAPP_NOT_FOUND`	`whatsappId` não existe
`WHATSAPP_CREDENTIALS_MISSING`	canal sem credenciais WABA completas
`MISSING_PARAMETERS`	payload sem campos obrigatórios
`MARKETING_LIMIT_REACHED`	contato deu opt-out ou atingiu limite de marketing
`WHATSAPP_API_ERROR`	erro retornado pela API da Meta

Webhooks WABA (contrato público)

Quando o webhook do projeto estiver habilitado, a Sendeasy envia:

event: "messaging" para eventos de mensagem.
event: "message_status" para atualização de estado de envio.

Exemplo (messaging):

{
  "event": "messaging",
  "channel": "waba",
  "data": {},
  "channelId": "uuid-do-canal"
}

Exemplo (message_status):

{
  "event": "message_status",
  "channel": "whatsapp",
  "data": {
    "messageId": "wamid.HBg...",
    "status": "read",
    "timestamp": "1713800010"
  },
  "channelId": "uuid-do-canal"
}

Valores comuns de data.status:

sent
delivered
read
failed