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

Mensagens

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.

POST

messages

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

Authorization

string

header

required

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

Idempotency-Key

string

Chave de idempotência, de 1 a 255 caracteres, sem caracteres de controle (fora disso: 400 INVALID_IDEMPOTENCY_KEY). Derive de um evento do seu sistema (id do pedido, id da tentativa) e reuse a mesma chave nas retentativas.

Maximum string length: 255

Body

application/json

Envie exatamente um entre templateName, body, interactive, location e reaction.

receiver

string

required

Telefone do destinatário. Formato recomendado: E.164 com + (+5511999999999). Também passam 5511999999999 e whatsapp:+5511999999999. A Arara fica só com os dígitos e exige de 7 a 15; fora disso, 422 INVALID_RECIPIENT.

Example:

"+5511999999999"

templateName

string | null

Nome do template aprovado. Pode ser enviado a qualquer hora.

Example:

"pedido_confirmado"

templateVariables

string[] | null

Variáveis posicionais do template, na ordem de {{1}}, {{2}}... (alias aceito: variables). Em template com mídia no cabeçalho, a URL da mídia vai na primeira posição. Não aceita quebra de linha nem tab.

Example:

["João", "12345"]

body

string | null

Texto da mensagem. Só com a janela de 24h aberta; fora dela, 422 CONVERSATION_WINDOW_CLOSED.

interactive

object | null

Botões, lista, formulário ou cobrança. Só com a janela de 24h aberta.

Show child attributes

location

object | null

Localização. Só com a janela de 24h aberta.

Show child attributes

reaction

object | null

Reação com emoji a uma mensagem.

Show child attributes

charge

object | null

Cobrança que acompanha um template com botão CHARGE. Use junto com templateName.

Show child attributes

sender

string | null

Número da organização que envia. Omitido, usa o número padrão. Número que não é seu responde 422 SENDER_NOT_ALLOWED.

replyTo

string | null

ID (ara_msg_...) da mensagem citada na resposta.

scheduled_at

string<date-time> | null

Agenda o envio (ISO 8601). Data no futuro deixa a mensagem em SCHEDULED até o horário. Data no passado envia na hora. Aceita também o nome scheduledAt.

Example:

"2027-01-15T14:00:00-03:00"

smartLinkParam

string | null

Parâmetro do botão de smart link do template.

smartLinkUrl

string | null

URL de destino do botão de smart link do template.

type

enum<string> | null

Opcional. Quando omitido, é inferido do conteúdo enviado.

Available options:

template,

text,

interactive,

location,

reaction

mode

enum<string> | null

Opcional. Todo envio por chave de API é real (LIVE). Não existe modo de teste.

Available options:

LIVE

media_url

string | null

deprecated

Legado (aceita também mediaUrl). Use a primeira posição de templateVariables.

Response

Mensagem aceita

status

enum<string>

required

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. Veja reason.
CANCELED: cancelada antes do envio.

O webhook message.status_updated usa os mesmos estados em minúsculas, com PENDING virando queued.

Available options:

PENDING,

SCHEDULED,

PROCESSING,

SENT,

DELIVERED,

READ,

FAILED,

CANCELED

mode

enum<string>

required

Todo envio por chave de API é LIVE.

Available options:

LIVE

sender

string

required

Número que enviou.

receiver

string

required

Número do destinatário.

string | null

ID público da mensagem. Use para consultar e para casar com o webhook.

Example:

"ara_msg_k9Bf2Xq"

body

string | null

Conteúdo final enviado, com as variáveis aplicadas. Pode vir null.

cost

number | null

Custo em reais. Pode vir null. Os valores dos exemplos são ilustrativos.

reason

string | null

Motivo da falha quando status é FAILED.

Visão geral

Mensagens

Conversas

Templates

Campanhas

Contatos

Opt-out

Formulários

Automações

Smart Links

Números

Carteira

Consulta de telefone

Recuperação

Conta

Webhooks

Enviar mensagem

Authorizations

Headers

Body

Response