Ir para o conteúdo
Promovaweb

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
  1. Texto e arquivo usam contratos próprios
  2. O identificador acompanha a mensagem
  3. A entrega acontece depois do aceite
  4. O timeout deixa uma pergunta sobre o envio
  5. A URL da mídia tem prazo
  6. O recibo de um grupo não representa todos os participantes

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.

  1. Fila

    Queued

    O envio aguarda processamento.

  2. Envio

    Sent

    A sessão envia a mensagem.

  3. Entrega

    Delivered

    O transporte confirma a entrega.

  4. Leitura

    Read

    O recibo aparece quando disponível.

Estados possíveis de um envio assíncrono, com leitura condicionada à disponibilidade do recibo.

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.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.