curl --request POST \
--url https://api.ararahq.com/v1/messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"receiver": "+5511999999999"
}
'{
"id": "ara_msg_k9Bf2Xq",
"status": "PENDING",
"mode": "LIVE",
"sender": "whatsapp:+5511888888888",
"receiver": "whatsapp:+5511999999999",
"body": "Oi João, seu pedido 12345 foi confirmado!",
"cost": 0.068,
"reason": null
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "O número do recebedor é obrigatório",
"details": {}
}
}{
"timestamp": "2026-09-15T14:30:00.000+00:00",
"status": 401,
"error": "Unauthorized",
"path": "/v1/messages"
}{
"error": {
"code": "INSUFFICIENT_FUNDS",
"message": "Saldo insuficiente.",
"details": {}
}
}{
"error": {
"code": "ACCOUNT_NOT_ACTIVATED",
"message": "Ative a conta para enviar mensagens.",
"details": {
"reason": "FIRST_SUBSCRIPTION_REQUIRED"
}
}
}{
"error": {
"code": "CONFLICT",
"message": "Template 'pedido_confirmado' não encontrado.",
"details": {}
}
}{
"error": {
"code": "CONVERSATION_WINDOW_CLOSED",
"message": "A janela de 24h está fechada. Envie um template.",
"details": {}
}
}{
"error": {
"code": "SEND_RATE_LIMITED",
"message": "Limite de envio atingido. Tente de novo em instantes.",
"details": {}
}
}{
"error": {
"code": "SEND_TEMPORARILY_UNAVAILABLE",
"message": "Envio temporariamente indisponível. Tente de novo em instantes.",
"details": {}
}
}Enviar mensagem
Envia uma mensagem de WhatsApp. Mande exatamente um conteúdo:
templateName, body, interactive, location ou reaction. Zero ou
mais de um responde 400 VALIDATION_ERROR.
- Template aprovado (
templateName) pode ser enviado a qualquer hora. - Os demais conteúdos só passam com a janela de 24h aberta. Fora dela:
422 CONVERSATION_WINDOW_CLOSED.
A resposta 202 traz o id da mensagem. O status final chega pelo webhook
message.status_updated.
Idempotency-Key (opcional): a mesma chave, para o mesmo usuário, devolve a
mensagem já criada, sem novo envio nem nova cobrança. A chave não expira e o
corpo não é comparado: reusar a chave com outro destinatário devolve a
mensagem antiga, sem erro. Use uma chave por intenção de envio, derivada de
um evento do seu sistema (ex. pedido-12345-confirmacao).
Permissão: MESSAGES_SEND.
curl --request POST \
--url https://api.ararahq.com/v1/messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"receiver": "+5511999999999"
}
'{
"id": "ara_msg_k9Bf2Xq",
"status": "PENDING",
"mode": "LIVE",
"sender": "whatsapp:+5511888888888",
"receiver": "whatsapp:+5511999999999",
"body": "Oi João, seu pedido 12345 foi confirmado!",
"cost": 0.068,
"reason": null
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "O número do recebedor é obrigatório",
"details": {}
}
}{
"timestamp": "2026-09-15T14:30:00.000+00:00",
"status": 401,
"error": "Unauthorized",
"path": "/v1/messages"
}{
"error": {
"code": "INSUFFICIENT_FUNDS",
"message": "Saldo insuficiente.",
"details": {}
}
}{
"error": {
"code": "ACCOUNT_NOT_ACTIVATED",
"message": "Ative a conta para enviar mensagens.",
"details": {
"reason": "FIRST_SUBSCRIPTION_REQUIRED"
}
}
}{
"error": {
"code": "CONFLICT",
"message": "Template 'pedido_confirmado' não encontrado.",
"details": {}
}
}{
"error": {
"code": "CONVERSATION_WINDOW_CLOSED",
"message": "A janela de 24h está fechada. Envie um template.",
"details": {}
}
}{
"error": {
"code": "SEND_RATE_LIMITED",
"message": "Limite de envio atingido. Tente de novo em instantes.",
"details": {}
}
}{
"error": {
"code": "SEND_TEMPORARILY_UNAVAILABLE",
"message": "Envio temporariamente indisponível. Tente de novo em instantes.",
"details": {}
}
}Authorizations
Chave de API da Arara (ara_live_...), enviada no header Authorization: Bearer ara_live_.... Crie e gerencie as chaves no painel: https://app.ararahq.com/dashboard/apikeys. O valor completo aparece uma única vez, na criação.
Headers
Body
Envie exatamente um entre templateName, body, interactive, location e reaction.
Response
Mensagem aceita
Estado atual, sempre em maiúsculas:
PENDING: criada, na fila.SCHEDULED: agendada.PROCESSING: em processamento.SENT: aceita pelo provedor.DELIVERED: entregue no aparelho.READ: lida.FAILED: falhou. Vejareason.CANCELED: cancelada antes do envio.
O webhook message.status_updated usa os mesmos estados em
minúsculas, com PENDING virando queued.
PENDING, SCHEDULED, PROCESSING, SENT, DELIVERED, READ, FAILED, CANCELED