Mensagens

Envie texto, mídia (imagem, vídeo, áudio, documento) ou modelo aprovado. O envio vai para a fila e responde 202 na hora; o status (pendente, enviada, entregue, lida, falhou) chega pelo webhook mensagem.status ou por GET /mensagens/{id}. Para consultar mensagens de toda a organização use GET /mensagens; também é possível listar mensagens de uma conversa.

• Para quem: conversa_id (responder numa conversa que já existe) ou telefone (com DDI e DDD). Só um dos dois.
• Pelo telefone, a conversa e o contato são criados se ainda não existirem; nome dá nome ao contato novo.
• Pelo telefone, com mais de um WhatsApp conectado, mande caixa_id (veja GET /me), senão vem 422 caixa_obrigatoria. Com conversa_id a mensagem sai pela caixa da conversa (caixa_id e nome só valem com telefone).
• responde_a_id cita uma mensagem da mesma conversa.
• Na API oficial do WhatsApp, fora da janela de 24 horas desde a última mensagem do contato, só sai modelo aprovado (422 janela_fechada). Veja os modelos em GET /modelos.
• Mídia vai por link https público (midia.url): o WhatsApp baixa dele na hora do envio. O texto vira a legenda.
• Mande Idempotency-Key para poder repetir sem mandar duas vezes (veja Idempotência).
• Limite próprio: 60 envios por minuto por chave e 120 por organização.
• canal (opcional, só WhatsApp): auto (padrão, igual a omitir) segue a regra da caixa; oficial sai só pela API oficial da Meta; qr sai só pelo WhatsApp por QR. A escolha manual nunca troca de canal: se o canal escolhido não puder enviar, vem erro (422 canal_oficial_indisponivel, canal_oficial_sem_grupo, canal_qr_indisponivel, canal_qr_sem_modelo, canal_so_whatsapp; a janela de 24 h vale em oficial) ou, se cair depois de aceito, a mensagem fica falhou com o código em erro. Modelo só sai pela oficial. Repetir o mesmo id_cliente com outro canal dá 409 idempotencia_conflito.

Baixar mídia recebida#

Cada item de midia[] nas mensagens e nos webhooks mensagem.recebida / mensagem.enviada traz id estável, além de mime, nome_arquivo, tamanho e duracao_s quando disponíveis. Baixe os bytes por GET /mensagens/{id}/midia, autenticado com escopo mensagens:ler. Use ?item=<id-do-anexo> para escolher um anexo por esse id ou ?item=0 para escolher pelo índice começando em zero; sem item, baixa o primeiro.

• A resposta 200 é o arquivo binário, com Content-Type e Content-Disposition. O endpoint aceita Range: bytes=... e responde 206 com Content-Range.
• Se o download sob demanda estiver em andamento, recebe 202 com erro.codigo: midia_baixando e Retry-After (aguarde esse número de segundos antes de tentar de novo). Se não for possível obter o arquivo, recebe 409 midia_indisponivel.
• Mensagem inexistente, de outra organização ou sem mídia responde 404.

{
  "conversa_id": "495a7cae-128c-4b66-adbc-807b3959c129",
  "tipo": "texto",
  "texto": "Perfeito, remarquei para quinta às 10h."
}

{
  "telefone": "+55 31 98888-7777",
  "tipo": "imagem",
  "midia": {"url":"https://seu-sistema.com.br/arquivos/orcamento.jpg"},
  "texto": "Segue o orçamento."
}

{
  "conversa_id": "495a7cae-128c-4b66-adbc-807b3959c129",
  "tipo": "documento",
  "midia": {
    "url": "https://seu-sistema.com.br/arquivos/orcamento.pdf",
    "nome_arquivo": "Orçamento.pdf"
  }
}

{
  "telefone": "+55 31 98888-7777",
  "caixa_id": "7a9d53e9-9d1b-4122-923b-fac67958f445",
  "tipo": "modelo",
  "modelo": {"nome":"lembrete_consulta","idioma":"pt_BR","corpo":["Maria","9h"]}
}

{
  "conversa_id": "495a7cae-128c-4b66-adbc-807b3959c129",
  "tipo": "texto",
  "texto": "Seu pedido saiu para entrega.",
  "canal": "oficial"
}