Mensagens

​

O objeto mensagem

​

Enviar uma mensagem

curl -X POST https://api.ararahq.com/v1/messages \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-12345-confirmacao" \
  -d '{
    "receiver": "+5511999999999",
    "templateName": "pedido_confirmado",
    "templateVariables": ["João", "12345"]
  }'

{
  "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
}

​

Regras que valem saber

• Um conteúdo por mensagem. Mande exatamente um entre templateName, body, interactive, location e reaction. Zero ou mais de um responde 400 VALIDATION_ERROR.
• Janela de 24h. Só templateName passa a qualquer hora. Os outros conteúdos exigem a janela aberta; fora dela a resposta é 422 CONVERSATION_WINDOW_CLOSED. Para checar antes, use POST /v1/conversations/window-status.
• Telefone. Use E.164 com + (+5511999999999). Também passam 5511999999999 e whatsapp:+5511999999999. Inválido: 422 INVALID_RECIPIENT.
• Mídia no cabeçalho. A URL da imagem ou do PDF vai na primeira posição de templateVariables. Se o arquivo não está hospedado, suba em POST /v1/media/upload (imagem até 5 MB, PDF até 100 MB).
• Idempotência. Com Idempotency-Key, a mesma chave devolve a mensagem já criada, sem reenviar nem cobrar. O corpo não é comparado: derive a chave de um evento do seu sistema (id do pedido, id da tentativa) e use uma chave por intenção de envio.
• Status em maiúsculas. A API responde PENDING, SENT, DELIVERED. O webhook usa os mesmos estados em minúsculas, com PENDING virando queued.
• Consulta por dono. GET /v1/messages/{id} só devolve mensagens do mesmo usuário dono da chave. Mensagem de outro membro responde 403 sem corpo, e ID inexistente responde 404 sem corpo.
• Lote é tudo ou nada. Em POST /v1/messages/batch (até 1.000 destinatários, mesmo template), um telefone inválido ou saldo insuficiente recusa o lote inteiro com 422. Acima de 1.000, use Campanhas.

​

Agendar

# Amanhã, neste horário. No macOS: date -u -v+1d +%Y-%m-%dT%H:%M:%SZ
SCHEDULED_AT=$(date -u -d '+1 day' +%Y-%m-%dT%H:%M:%SZ)

curl -X POST https://api.ararahq.com/v1/messages \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: consulta-8842-lembrete" \
  -d '{
    "receiver": "+5511999999999",
    "templateName": "lembrete_consulta",
    "templateVariables": ["amanhã às 14h"],
    "scheduled_at": "'"$SCHEDULED_AT"'"
  }'

​

Endpoints

​

Erros mais comuns

​

Próximos passos