ARararahq
Mensagens

Enviar mensagem

Changed on

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/v1/messages

Request

Headers

Idempotency-Keystring

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.

Request body

receiverstring 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.

templateNamestring nullable

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

templateVariablesstring[] nullable

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.

bodystring nullable

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

senderstring nullable

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.

replyTostring nullable

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

scheduled_atstring date-time nullable

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.

smartLinkParamstring nullable

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

smartLinkUrlstring nullable

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

type'template' | 'text' | 'interactive' | 'location' | 'reaction' nullable

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

mode'LIVE' nullable

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

media_urlstring nullable

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

Example request

{
  "receiver": "+5511999999999",
  "templateName": "pedido_confirmado",
  "templateVariables": [
    "João",
    "12345"
  ],
  "scheduled_at": "2027-01-15T14:00:00-03:00"
}

Response

Mensagem aceita

idstring nullable

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

status'PENDING' | 'SCHEDULED' | 'PROCESSING' | 'SENT' | 'DELIVERED' | 'READ' | 'FAILED' | 'CANCELED' 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.

mode'LIVE' required

Todo envio por chave de API é LIVE.

senderstring required

Número que enviou.

receiverstring required

Número do destinatário.

bodystring nullable

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

costnumber nullable

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

reasonstring nullable

Motivo da falha quando status é FAILED.

Example response

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

Changes

  • d576cd28afc0Revision changes
    • breaking

      added to the request property allOf list

    • breaking

      added to the request property allOf list

    • breaking

      added to the request property allOf list

    • breaking

      the request property type changed from object to no type

    • breaking

      the request property type changed from object to no type

    • breaking

      the request property type changed from object to no type

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • info

      api tag Mensagens added

    • info

      api tag messages removed

    • info

      added the new optional request property

    • info

      the request property became nullable

    • info

      the request property became nullable

    • info

      the request property became nullable

    • info

      added the non-success response with the status

  • 372d8c2e735dRevision changes
    • breaking

      the response's body type changed from object to no type for status

    • breaking

      the response property / became nullable for the status

    • breaking

      the response property / became nullable for the status

    • breaking

      the response property / became nullable for the status

    • breaking

      the response property became optional for the status

    • breaking

      the response's property format changed from float to no format for status

    • breaking

      the response's property type changed from object to string for status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • info

      added the new optional header request parameter Idempotency-Key

    • info

      added to the response body anyOf list for the response status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status