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 via Twilio, consulta de histórico paginado e acompanhamento de status de entrega em tempo real.
Base URL: /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 http://localhost:8082/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 http://localhost:8082/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 http://localhost:8082/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 Twilio | Não |
DELIVERED | Entregue ao destinatário | Sim |
READ | Lido pelo destinatário | Sim |
FAILED | Falha no envio | Sim |
UNDELIVERED | Não entregue | Sim |