Mensagens

Envie mensagens WhatsApp, consulte histórico e acompanhe status de entrega.

Visão Geral

A API de Mensagens permite o envio de mensagens WhatsApp, consulta de histórico paginado e acompanhamento de status de entrega em tempo real. O provider WhatsApp (Twilio ou Meta Cloud API) é configurado por aplicação e transparente para quem envia.

Há dois caminhos de envio, conforme a autenticação da sua integração:

API Key (X-Api-Key + X-Api-Secret) — base /api/external/messages. Inclui envio, consulta e histórico.
OAuth2 (Bearer JWT, scope mensagens:enviar) — POST /api/external/v2/mensagens. Ideal para n8n, Zapier e automações. Ver OAuth2 / n8n.

Base URL (API Key): /api/external/messages

Autenticação: X-Api-Key + X-Api-Secret

Enviar Mensagem

POST

/api/external/messages/send

Parâmetro	Tipo	Obrigatório	Descrição
`telefone`	`string`	Obrigatório	Número com DDI. Ex: `+5511999999999`
`mensagem`	`string`	Obrigatório	Texto da mensagem
`contexto`	`string`	Opcional	Contexto: `RESERVA`, `PAGAMENTO`, `SUPORTE`, `LEMBRETE`, `CAMPANHA`, `TESTE`, `AGENDAMENTO_SAUDE`
`contextoId`	`number`	Opcional	ID do objeto relacionado
`usuarioId`	`number`	Opcional	ID do usuário destinatário

# Enviar mensagem WhatsApp
curl -X POST https://api.avizuai.com.br/api/external/messages/send \
  -H "X-Api-Key: sua-api-key" \
  -H "X-Api-Secret: seu-api-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "telefone": "+5511999999999",
    "mensagem": "Olá! Esta é uma mensagem de teste.",
    "contexto": "SUPORTE"
  }'

Resposta de sucesso (200):

{
  "status": "ENVIADO",
  "messageSid": "SM1234567890abcdef",
  "mensagemId": 42,
  "mensagem": "Mensagem enviada com sucesso"
}

Erro de Saldo Insuficiente (402)

{
  "error": "Saldo insuficiente",
  "message": "A aplicação não possui saldo suficiente para enviar mensagens.",
  "saldo": "0.00"
}

Consultar Mensagem por ID

GET

/api/external/messages/{id}

Retorna os detalhes completos de uma mensagem enviada.

curl https://api.avizuai.com.br/api/external/messages/42 \
  -H "X-Api-Key: sua-api-key" \
  -H "X-Api-Secret: seu-api-secret"

Resposta (200):

{
  "id": 42,
  "messageSid": "SM1234567890abcdef",
  "toNumber": "+5511999999999",
  "fromNumber": "+14155238886",
  "body": "Olá! Esta é uma mensagem de teste.",
  "status": "DELIVERED",
  "statusDescricao": "Entregue ao destinatário",
  "dataEnvio": "2026-04-11T10:30:00",
  "dataEntrega": "2026-04-11T10:30:05",
  "dataLeitura": null,
  "errorCode": null,
  "errorMessage": null
}

Listar Histórico

GET

/api/external/messages

Parâmetro	Tipo	Obrigatório	Descrição
`page`	`int`	Opcional	Página (default `0`)
`size`	`int`	Opcional	Itens por página (default `20`, máx `100`)
`status`	`string`	Opcional	Filtro: `QUEUED`, `SENT`, `DELIVERED`, `READ`, `FAILED`, `UNDELIVERED`
`contexto`	`string`	Opcional	Filtro por contexto

# Listar mensagens entregues
curl https://api.avizuai.com.br/api/external/messages?page=0&size=10&status=DELIVERED \
  -H "X-Api-Key: sua-api-key" \
  -H "X-Api-Secret: seu-api-secret"

A resposta segue o formato paginado Spring Data com campos: content, totalElements, totalPages, number, size.

Status de Mensagem

Status	Descrição	Final?
`QUEUED`	Na fila de envio	Não
`SENT`	Enviado ao provider (Twilio/Meta)	Não
`DELIVERED`	Entregue ao destinatário	Sim
`READ`	Lido pelo destinatário	Sim
`FAILED`	Falha no envio	Sim
`UNDELIVERED`	Não entregue	Sim

Enviar via OAuth2 (automações)

Para automações autenticadas por OAuth2 client_credentials (n8n, Zapier, scripts próprios), use o endpoint v2. A aplicação é inferida do token (claim aplicacao_id) — não se envia aplicacaoId no corpo.

POST

/api/external/v2/mensagens

Autenticação: Authorization: Bearer <token> · Scope: mensagens:enviar

Parâmetro	Tipo	Obrigatório	Descrição
`telefone`	`string`	Obrigatório	Número com DDI ou apenas dígitos. Ex: `+5511999999999`
`mensagem`	`string`	Obrigatório	Texto da mensagem
`contexto`	`string`	Opcional	Contexto da mensagem. Ex: `SUPORTE`, `TESTE`, `OUTRO` (default `OUTRO`)

# Enviar mensagem via OAuth2 (token obtido em /oauth2/token)
curl -X POST https://api.avizuai.com.br/api/external/v2/mensagens \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "telefone": "+5511999999999",
    "mensagem": "Olá! Mensagem enviada via automação.",
    "contexto": "SUPORTE"
  }'

Resposta de sucesso (200):

{
  "sucesso": true,
  "mensagemId": "42"
}

Falha de envio (200 com sucesso=false):

{
  "sucesso": false,
  "erro": "descrição do erro"
}

Erros de autenticação retornam 401 (JWT inválido ou sem o scope mensagens:enviar); sem saldo retorna 402; telefone/mensagem ausentes retornam 400. O envio passa por histórico, tarifação e webhooks de status normalmente.

Próximos Passos

🔐 OAuth2 / n8n 💰 Financeiro 🔌 Webhooks ⚠ Códigos de Erro