Como gerenciar chats pela API do WhatsApp: guia prático

A API do WhatsApp permite listar chats, puxar o histórico de mensagens de uma conversa, marcar como lido, fixar e deletar — o conjunto de ações que organiza a caixa de entrada, disponível por código. Este tutorial mostra cada uma dessas ações e onde encaixar num painel de atendimento.

Por que gerenciar chat é diferente de gerenciar mensagem

Mensagem é o conteúdo individual trocado; chat é a conversa inteira com um contato. Ações de chat operam no nível da conversa — marcar tudo como lido, fixar no topo, remover da lista — e não em uma mensagem específica dentro dela.

Essa distinção importa para quem constrói um painel de atendimento próprio: listar chats alimenta a visão geral (quem está conversando agora), enquanto o histórico de mensagens de um chat alimenta a tela de conversa individual quando um atendente abre um item específico.

O conjunto de cinco ações — listar, ler histórico, marcar como lido, fixar e deletar — é o suficiente para montar uma interface de atendimento funcional sem depender de nenhuma ferramenta de terceiros, desde que o volume de conversas simultâneas ainda seja administrável por um time pequeno.

Pré-requisitos

• Instância conectada e key de acesso em mãos.
• Um caso de uso definido para a listagem — normalmente um painel interno ou uma fila de atendimento.

Passo a passo

1. Liste todos os chats ativos

curl https://us.api-wa.me/{KEY}/chat

Essa chamada é a base de qualquer painel: retorna as conversas ativas da instância, uma por contato.

2. Busque as mensagens de um chat específico

curl "https://us.api-wa.me/{KEY}/chat/[email protected]"

Note o formato do chatId — o número seguido de @s.whatsapp.net, o identificador interno usado pela camada não oficial. Esse é o valor que aparece na listagem do passo 1 e que se reaproveita nas próximas chamadas.

3. Marque como lido

curl -X PATCH "https://us.api-wa.me/{KEY}/[email protected]&action=markRead&value=true"

Uso típico: quando um atendente abre a conversa no seu painel interno, seu sistema chama esse endpoint para sincronizar o status de lido também do lado da instância.

4. Fixe uma conversa prioritária

curl -X PATCH "https://us.api-wa.me/{KEY}/[email protected]&action=pin&value=true"

Combina bem com uma regra automática: se uma mensagem recebida contém palavra-chave de urgência ("cancelamento", "reclamação formal"), fixar o chat automaticamente garante que ele fique visível no topo até ser tratado.

async function fixarSeUrgente(chatId, texto) {
  const urgente = /cancelamento|reclamação|urgente/i.test(texto);
  if (urgente) {
    await fetch(
      `https://us.api-wa.me/${KEY}/chat?id=${chatId}&action=pin&value=true`,
      { method: 'PATCH' },
    );
  }
}

5. Delete um chat encerrado

curl -X DELETE "https://us.api-wa.me/{KEY}/[email protected]"

Remove a conversa da lista da instância — útil para limpar chats de teste ou conversas já arquivadas em outro sistema, sem acumular indefinidamente na lista ativa.

Montando uma fila de atendimento simples

Combinando os cinco passos, uma fila básica de atendimento fica assim: listar chats (passo 1) alimenta a visão geral; abrir um chat específico chama o histórico (passo 2) e marca como lido (passo 3); uma regra de urgência fixa o que precisa de atenção prioritária (passo 4); e um processo periódico limpa chats encerrados (passo 5).

Esse fluxo é a base do que já existe em vários atendentes no mesmo número de WhatsApp — a diferença é que aqui o foco é a mecânica de cada endpoint, não a distribuição entre atendentes.

Construindo um painel de chats ativos

Um painel simples de "conversas que precisam de atenção" combina os endpoints de listagem com uma regra de priorização, sem precisar de nenhuma ferramenta externa:

async function chatsPendentes() {
  const resp = await fetch(`https://us.api-wa.me/${KEY}/chat`);
  const chats = await resp.json();

  return chats
    .filter((c) => !c.lida)
    .sort((a, b) => (b.fixado ? 1 : 0) - (a.fixado ? 1 : 0));
}

Esse tipo de painel é o ponto de partida de qualquer operação de atendimento própria, antes de considerar uma ferramenta dedicada como o Chatwoot integrado à WAME API — para volume pequeno, a combinação de listar, marcar como lido e fixar já cobre boa parte da necessidade.

Paginação e volume alto de chats

Instâncias com muitas conversas ativas devem tratar a listagem como algo a paginar ou filtrar, não como uma chamada única que traz tudo de uma vez a cada atualização de tela. Um padrão simples: cachear a lista por um intervalo curto (10 a 30 segundos) no seu backend, e servir o painel a partir desse cache, atualizando em segundo plano.

let cacheChats = { dados: [], atualizadoEm: 0 };

async function listarChatsComCache() {
  const agora = Date.now();
  if (agora - cacheChats.atualizadoEm < 15000) {
    return cacheChats.dados;
  }
  const resp = await fetch(`https://us.api-wa.me/${KEY}/chat`);
  cacheChats = { dados: await resp.json(), atualizadoEm: agora };
  return cacheChats.dados;
}

Isso evita que um painel com múltiplos atendentes atualizando a tela ao mesmo tempo gere uma chamada repetida à API a cada poucos segundos por pessoa conectada.

Erros comuns

Confundir o chatId com o número puro. O formato esperado inclui o sufixo @s.whatsapp.net; passar só o número sem esse sufixo faz a chamada falhar silenciosamente em vez de retornar o resultado esperado.

Marcar como lido antes de realmente processar a mensagem. Se o "marcar como lido" acontece automaticamente ao receber, e não quando um atendente de fato vê a mensagem, seu painel perde a informação real de quais conversas ainda precisam de atenção.

Deletar chat como forma de "resolver" um problema. Deletar remove da lista, mas não desfaz o que já foi conversado nem soluciona a causa do contato. Vale reservar a exclusão para limpeza operacional, não como atalho para encerrar uma reclamação sem resposta.

Não paginar ou filtrar em instâncias com muitos chats. Buscar a lista inteira a cada atualização de tela, sem cache nem filtro, funciona bem com poucas dezenas de conversas e começa a pesar conforme o volume cresce — o padrão de cache do passo anterior evita esse problema antes dele aparecer.

Fixar automaticamente por regra, não manualmente

Fixar chat manualmente funciona para poucos casos, mas não escala para uma operação com dezenas de conversas simultâneas. Uma regra automática, aplicada no mesmo webhook que recebe a mensagem, resolve isso sem depender de um atendente lembrar de fixar:

const PALAVRAS_URGENTES = ['cancelamento', 'reclamação', 'urgente', 'não funciona'];

app.post('/webhook', async (req, res) => {
  const { chatId, text } = req.body;
  const ehUrgente = PALAVRAS_URGENTES.some((p) => text?.toLowerCase().includes(p));

  if (ehUrgente) {
    await fetch(
      `https://us.api-wa.me/${KEY}/chat?id=${chatId}&action=pin&value=true`,
      { method: 'PATCH' },
    );
  }
  res.sendStatus(200);
});

Vale também desafixar automaticamente depois que a conversa é marcada como resolvida no seu sistema, para o topo do painel não acumular chats antigos que já foram tratados.

Combinando com Labels para priorização mais rica

Fixar um chat resolve visibilidade imediata, mas é um estado binário — fixado ou não. Para uma priorização mais granular (urgente, aguardando cliente, em negociação), combinar essa gestão de chat com Labels na API do WhatsApp permite múltiplos níveis de organização ao mesmo tempo: um chat pode estar fixado e, além disso, etiquetado com o motivo específico da prioridade.

Próximos passos

Depois de organizar chats, o próximo passo natural é organizar por contato — veja como gerenciar contatos pela API do WhatsApp para listar, consultar perfil e bloquear. Para medir o resultado desse fluxo de atendimento, métricas de campanha no WhatsApp mostra como capturar entrega, leitura e resposta pelo mesmo tipo de evento de webhook.