Mensagens e mídias pela UAZAPI
Uma resposta HTTP de sucesso não quer dizer que o destinatário leu a mensagem. A UAZAPI envia e recebe textos e arquivos pela sessão do WhatsApp e devolve identificadores para cada envio. Com eles e com os eventos posteriores, você separa a mensagem aceita da enviada, da entregue e da lida, quando o recibo está disponível.
Ficha e sumário da página
- Referência técnica
- UAZAPI 2.6.9
- Revisão
- 13 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
Texto e arquivo usam contratos próprios
A API recebe chamadas diferentes para texto e mídia. O endpoint
/send/text trata mensagens textuais, enquanto /send/media recebe
arquivos, imagens, vídeos e áudios conforme o contrato de cada tipo.
Você escolhe o endpoint pelo conteúdo que o seu app precisa transmitir.
O fato de uma imagem abrir no seu navegador não garante que o servidor
da UAZAPI consiga baixá-la: a URL pode exigir uma sessão autenticada
ou apontar para um endereço acessível somente na sua rede.
O campo file e os tipos aceitos ficam descritos no contrato da operação.
Essa conferência evita tratar qualquer arquivo como se tivesse as mesmas
condições de transporte. O servidor precisa obter o conteúdo e processar
o formato antes do envio. O WhatsApp e as permissões do destinatário
também participam do resultado. Uma requisição com autenticação válida
pode receber uma recusa específica do formato ou da ação solicitada.
O identificador acompanha a mensagem
Os retornos de envio incluem identificadores usados para consultar e
correlacionar mensagens. A documentação distingue o id consolidado da
API e o messageid original. Você preserva esses valores como strings,
sem convertê-los em números ou reconstruí-los a partir do telefone.
Essa preservação permite relacionar o evento posterior ao registro que
o seu sistema criou quando solicitou o envio da resposta.
Os campos track_source e track_id acrescentam uma referência do seu
sistema. Eles ajudam a associar uma mensagem a uma execução de automação,
mas não funcionam como proteção automática contra repetição. A documentação
informa que track_id aceita valores duplicados. Quando o seu app envia a mesma
chamada duas vezes com esse campo igual, o contrato não promete que apenas
uma mensagem chega ao destinatário.
A entrega acontece depois do aceite
Um retorno HTTP bem-sucedido descreve o processamento da requisição
conforme o endpoint chamado. O estado Queued informa que o envio entrou
na fila assíncrona. Em Sent, a sessão enviou a mensagem. A confirmação
de entrega aparece como Delivered, enquanto Read indica recibo de
leitura disponível. Esses estados respondem a perguntas diferentes sobre
o caminho percorrido e precisam permanecer distintos no seu histórico.
Fila
QueuedO envio aguarda processamento.
Envio
SentA sessão envia a mensagem.
Entrega
DeliveredO transporte confirma a entrega.
Leitura
ReadO recibo aparece quando disponível.
Você recebe mudanças pelo evento messages_update e pode reconciliar
o registro com consultas à API. Os eventos podem chegar repetidos ou
fora de ordem. Um evento atrasado de envio não deve rebaixar uma mensagem
que já tem confirmação de leitura. A atualização do seu app considera
o estado conhecido e o significado da ocorrência recebida, em vez de
substituir o texto de status pela última requisição que chegou.
O timeout deixa uma pergunta sobre o envio
Quando o seu app não recebe resposta dentro do tempo esperado, o envio pode já ter sido processado pelo servidor. Repetir a requisição sem consultar o histórico pode produzir duas respostas iguais na conversa. O tratamento é diferente de repetir uma leitura que falhou temporariamente. Uma consulta busca um registro existente, enquanto uma chamada de envio cria uma nova mensagem com efeito visível para o destinatário.
A documentação orienta consultar o estado ou reconciliar pelos
identificadores antes de repetir uma alteração. Você também observa
Retry-After quando o servidor informa um limite temporário. Um fluxo
que continua enviando chamadas antes do prazo indicado pode receber
novas respostas 429, pois as rotas dividem a cota da instância. O histórico de
tentativas precisa mostrar o motivo da espera e o envio associado,
sem registrar tokens ou o conteúdo privado da conversa.
A URL da mídia tem prazo
O endpoint /message/download recebe o identificador da mensagem e pode
devolver fileURL, o endereço do arquivo para download. Na documentação
2.6.9, esse arquivo fica disponível no CDN por dois dias. Guardar apenas
o endereço no seu sistema não estende esse prazo. Para manter
o anexo por mais tempo, a aplicação baixa o arquivo e o grava num
armazenamento próprio, com acesso adequado à conversa correspondente.
Você também pode solicitar o download novamente para obter outra URL, desde que a mensagem e a mídia original continuem disponíveis. Essa possibilidade depende da retenção na origem e não substitui o armazenamento do anexo que o seu atendimento precisa conservar.
A URL pública também exige atenção ao compartilhamento. Uma imagem enviada numa conversa privada não deve aparecer em logs públicos só porque o download retornou um endereço acessível. O retorno em base64 transporta o arquivo dentro do JSON e aumenta o tamanho da resposta. A documentação prefere a URL para esse transporte, deixando base64 para integrações que realmente exigem o conteúdo embutido.
O recibo de um grupo não representa todos os participantes
As confirmações em grupos têm tratamento próprio. A API reúne recibos
por mensagem e envia o evento GroupReceipts dentro de messages_update.
O status geral acompanha o participante mais adiantado. Portanto, uma
mensagem marcada como lida pode ter sido lida por apenas um participante.
Você usa os recibos individuais para interpretar a entrega
por pessoa, sem converter o estado geral em confirmação coletiva.
A uazapi mantém o serviço proprietário usado nessa comunicação. O acesso à API não substitui as condições do WhatsApp nem garante entrega contínua. A forma como o receptor relaciona as mudanças à mensagem original está em webhooks e eventos. No seu app, a confirmação permanece limitada ao que o transporte informou: uma entrega não comprova que a conversa foi atendida ou que o contato respondeu.