Mensagens

Endpoints da app consumidora pra enviar mensagens via chip vinculado e consultar status.

`POST /v1/messages`

Enfileira envio. Retorna 202 Accepted com message_id. Mensagem efetiva acontece async (rate limit + jitter por chip).

POST /v1/messages
Authorization: Bearer APP_KEY
Content-Type: application/json

Body comum

Campo	Obrigatorio	Notas
`chip_id`	sim*	qual chip envia. *Vai virar opcional na Fase 10 (ADR 013)
`to`	sim	telefone destino — `5511999998888` (so digitos) ou JID completo
`type`	sim	`text` \| `image` \| `audio` \| `document` \| `location` \| `reaction`
`content`	sim	varia por type — ver abaixo
`idempotency_key`	recomendado	string ate 120 chars; unique `(app_id, idempotency_key)` previne duplicacao
`quoted_message_id`	opcional	ULID de mensagem anterior pra reply

Texto

{
  "chip_id": "01HZTQ...",
  "to": "5511999998888",
  "type": "text",
  "content": { "text": "ola, sua compra foi confirmada" },
  "idempotency_key": "order-1234-confirmed"
}

Imagem

{
  "chip_id": "...",
  "to": "...",
  "type": "image",
  "content": {
    "url": "https://cdn.com/produto.jpg",
    "caption": "produto X — R$99"
  }
}

Hub baixa do url, valida tamanho (MEDIA_MAX_BYTES, default 16MB), reupload pro WhatsApp.

Aceita tambem data:image/jpeg;base64,... em url (inline).

Audio

{
  "type": "audio",
  "content": {
    "url": "https://cdn.com/audio.ogg",
    "ptt": true                         // true = bolha de voz; false = anexo
  }
}

⚠️ Pra tocar como bolha de voz no WhatsApp, mimetype precisa ser audio/ogg; codecs=opus. Conversao do seu lado.

Documento

{
  "type": "document",
  "content": {
    "url": "https://cdn.com/contrato.pdf",
    "filename": "contrato-2026.pdf",
    "title": "Contrato"
  }
}

Localizacao

{
  "type": "location",
  "content": {
    "lat": -23.5505,
    "lng": -46.6333,
    "name": "Loja SP",
    "address": "Av Paulista 1000"
  }
}

Reaction

{
  "type": "reaction",
  "content": {
    "emoji": "❤️",
    "to_wa_message_id": "BAE5..."        // wa_message_id da mensagem alvo
  }
}

emoji="" remove reaction existente.

Response (todos os types)

202 Accepted:

{
  "id": "01HZTQMSG...",
  "status": "queued"
}

A mensagem entra na fila do chip. Voce acompanha via webhook message.status (queued → sent → delivered → read). Ou consulta diretamente:

`GET /v1/messages/:id`

{
  "id": "01HZTQMSG...",
  "chip_id": "...",
  "app_id": "...",
  "wa_message_id": "BAE5...",
  "to_jid": "5511...@s.whatsapp.net",
  "from_jid": "5511...:30@s.whatsapp.net",
  "direction": "out",
  "type": "text",
  "content": { "text": "..." },
  "status": "delivered",
  "error": null,
  "created_at": "...",
  "sent_at": "...",
  "delivered_at": "...",
  "read_at": "..."
}

Status possiveis

Status	Significado
`queued`	enfileirada, aguardando rate limiter
`sent`	hub mandou pro WhatsApp (server ack 1)
`delivered`	aparelho do destinatario recebeu (server ack 2)
`read`	destinatario leu (so se leitura ativa nas configs WhatsApp)
`failed`	erro irreversivel — campo `error` tem detalhe

Erros comuns

409 chip-not-connected — chip vinculado nao esta connected
403 chip-access-forbidden — app sem can_send=true no vinculo
409 idempotency-conflict — mesma idempotency_key ja foi usada com payload diferente
422 unsupported-message-type — type nao reconhecido
422 transcription-disabled — tentou rota de transcricao manual com provider desligado

Ver Erros pra lista completa.