---
title: "Gerenciar chats pela API do WhatsApp"
description: "Tutorial: como listar chats, ler mensagens, marcar como lido, fixar e deletar conversas pela API do WhatsApp — passo a passo com exemplos em cURL."
url: "https://api-wa.me/blog/tutorial-gerenciar-chats-whatsapp-api"
language: "pt-BR"
og:type: "article"
og:site_name: "WAME API"
---

[Início](https://api-wa.me/)/[Blog da API do WhatsApp](https://api-wa.me/blog)/Como gerenciar chats pela API do WhatsApp: guia prático

Raphael Serafim· Publicado em 17 de setembro de 2026· 8 min de leitura

Compartilhar

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

Tutorial: como listar chats, ler mensagens, marcar como lido, fixar e deletar conversas pela API do WhatsApp — passo a passo com exemplos em cURL.

Copiar para LLM[Ver como Markdown](https://api-wa.me/blog/tutorial-gerenciar-chats-whatsapp-api.md)

**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

sh

Copiar

```
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

sh

Copiar

```
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

sh

Copiar

```
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

sh

Copiar

```
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.

javascript

Copiar

```
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

sh

Copiar

```
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](https://api-wa.me/blog/multiatendimento-mesmo-numero-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:

javascript

Copiar

```
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](https://api-wa.me/blog/integrar-wame-api-chatwoot) — 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.

javascript

Copiar

```
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:

javascript

Copiar

```
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](https://api-wa.me/blog/labels-api-whatsapp-organizar-conversas-sem-crm) 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](https://api-wa.me/blog/tutorial-gerenciar-contatos-bloquear-whatsapp-api) para listar, consultar perfil e bloquear. Para medir o resultado desse fluxo de atendimento, [métricas de campanha no WhatsApp](https://api-wa.me/blog/metricas-campanha-whatsapp-api) mostra como capturar entrega, leitura e resposta pelo mesmo tipo de evento de webhook.

### Pronto para automatizar seu WhatsApp?

Crie sua conta gratuita e comece a enviar mensagens pela API em minutos.

[Começar grátis](https://portal.api-wa.me/sign-up)

## Perguntas frequentes

Como listar todos os chats de uma instância pela API?+

Um GET no endpoint de chat retorna a lista de conversas ativas da instância, cada uma identificada pelo número no formato usado internamente pelo WhatsApp.

Como buscar as mensagens de um chat específico?+

Passando o identificador do chat como parâmetro no endpoint de mensagens do chat, que devolve o histórico daquela conversa em vez da lista de todos os chats.

Marcar como lido pela API muda o que o cliente vê?+

Não altera nada do lado do cliente — ele já viu o que precisava ver. Marcar como lido do lado da instância serve para o seu sistema saber que aquela conversa foi tratada, sem depender de alguém abrir manualmente.

Fixar chat pela API serve para quê?+

Para manter uma conversa prioritária sempre visível no topo, útil quando uma automação identifica um chat de alta prioridade (reclamação, cliente VIP) e quer garantir que ele não se perca no meio de outras conversas ativas.

Deletar chat pela API remove a conversa também do lado do cliente?+

Não. Deletar chat aqui remove a conversa apenas da lista da sua instância — o mesmo efeito de apagar uma conversa pelo seu lado no app, sem afetar o que o outro contato vê do lado dele.

## Continue lendo

[### Coexistência e a nova cobrança do WhatsApp: o que muda para quem atende pelo celular e pela API

Quem usa Coexistência (API oficial + celular) sente a nova cobrança de agosto e outubro de 2026 de um jeito específico. Veja o que é cobrado e o que continua grátis.](https://api-wa.me/blog/coexistencia-nova-cobranca-whatsapp-2026)[### Como simular o custo da nova cobrança do WhatsApp antes de outubro de 2026

Passo a passo para medir, via webhook e API de analytics da Meta, quantas mensagens de serviço e de Business Agent seu número gera hoje — antes da cobrança começar.](https://api-wa.me/blog/simular-custo-mensagem-servico-whatsapp-2026)[### Automatizar grupos de WhatsApp pela API: guia completo

Como automatizar grupos de WhatsApp pela API: criar, adicionar participante, moderar entrada e enviar aviso automático, com exemplos práticos em cURL.](https://api-wa.me/blog/automatizar-grupos-whatsapp-api)

[Voltar ao blog](https://api-wa.me/blog)

## Structured data

```json
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "WAME API",
  "alternateName": "API Oficial e Não Oficial de WhatsApp, Instagram e Messenger",
  "url": "https://api-wa.me",
  "inLanguage": "pt-BR",
  "publisher": {
    "@id": "https://api-wa.me/#organization",
    "@type": "Organization",
    "name": "WAME API",
    "url": "https://api-wa.me"
  }
}
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://api-wa.me/#organization",
  "name": "WAME API",
  "alternateName": [
    "WAME",
    "Wame API",
    "wame.api.br",
    "api-wa.me"
  ],
  "url": "https://api-wa.me",
  "logo": {
    "@type": "ImageObject",
    "url": "https://api-wa.me/images/web-app-manifest-512x512.png",
    "width": 512,
    "height": 512
  },
  "disambiguatingDescription": "WAME API é uma empresa brasileira de software, fundada em 2017 e parceira oficial da Meta (Meta Business Partner), que fornece APIs de WhatsApp, Instagram Direct e Messenger. Não tem relação com o wa.me, que é o encurtador de links operado pela WhatsApp LLC.",
  "identifier": {
    "@type": "PropertyValue",
    "propertyID": "INPI-BR",
    "name": "Pedido de registro de marca (INPI, classe NCL 42)",
    "value": "944724159"
  },
  "foundingDate": "2017",
  "slogan": "Parceira Oficial da Meta — WhatsApp, Instagram e Messenger numa instância só. Desde 2017.",
  "description": "Plataforma brasileira e Parceira Oficial da Meta (Meta Business Partner) para as APIs oficiais de WhatsApp (Cloud API), Instagram Direct e Messenger — os três numa única instância, com os mesmos endpoints e um único formato de webhook. Também oferece a API não oficial via QR Code, na mesma plataforma. No mercado desde 2017, com mais de 50 mil instâncias criadas, 99,9% de uptime e suporte humano 24/7 em português. SDKs oficiais para Node.js/TypeScript e PHP.",
  "knowsAbout": [
    "WhatsApp Cloud API oficial (Meta)",
    "API oficial de Instagram (Direct)",
    "API oficial de Messenger",
    "API multicanal Meta",
    "Meta Business Partner",
    "WhatsApp API",
    "API não oficial de WhatsApp",
    "automação de WhatsApp",
    "números virtuais",
    "webhooks"
  ],
  "sameAs": [
    "https://github.com/wame-api",
    "https://www.linkedin.com/company/wameapi",
    "https://www.instagram.com/wame.api/",
    "https://www.youtube.com/@wameapi"
  ],
  "contactPoint": {
    "@type": "ContactPoint",
    "contactType": "customer support",
    "url": "https://api-wa.me/contact",
    "availableLanguage": [
      "Portuguese"
    ]
  }
}
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Como gerenciar chats pela API do WhatsApp: guia prático",
  "description": "Tutorial: como listar chats, ler mensagens, marcar como lido, fixar e deletar conversas pela API do WhatsApp — passo a passo com exemplos em cURL.",
  "image": "https://api-wa.me/blog/tutorial-gerenciar-chats-whatsapp-api/opengraph-image",
  "datePublished": "2026-09-17",
  "dateModified": "2026-09-17",
  "author": {
    "@type": "Person",
    "name": "Raphael Serafim",
    "url": "https://github.com/raphaelvserafim",
    "sameAs": [
      "https://github.com/raphaelvserafim"
    ]
  },
  "publisher": {
    "@type": "Organization",
    "name": "api-wa.me",
    "logo": {
      "@type": "ImageObject",
      "url": "https://api-wa.me/images/screenshot.png"
    }
  },
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://api-wa.me/blog/tutorial-gerenciar-chats-whatsapp-api"
  },
  "keywords": "gerenciar chats whatsapp api, listar chats whatsapp api, marcar como lido whatsapp api, fixar chat whatsapp api, deletar chat whatsapp api",
  "inLanguage": "pt-BR"
}
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://api-wa.me"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Blog da API do WhatsApp",
      "item": "https://api-wa.me/blog"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "Como gerenciar chats pela API do WhatsApp: guia prático",
      "item": "https://api-wa.me/blog/tutorial-gerenciar-chats-whatsapp-api"
    }
  ]
}
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Como listar todos os chats de uma instância pela API?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Um GET no endpoint de chat retorna a lista de conversas ativas da instância, cada uma identificada pelo número no formato usado internamente pelo WhatsApp."
      }
    },
    {
      "@type": "Question",
      "name": "Como buscar as mensagens de um chat específico?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Passando o identificador do chat como parâmetro no endpoint de mensagens do chat, que devolve o histórico daquela conversa em vez da lista de todos os chats."
      }
    },
    {
      "@type": "Question",
      "name": "Marcar como lido pela API muda o que o cliente vê?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Não altera nada do lado do cliente — ele já viu o que precisava ver. Marcar como lido do lado da instância serve para o seu sistema saber que aquela conversa foi tratada, sem depender de alguém abrir manualmente."
      }
    },
    {
      "@type": "Question",
      "name": "Fixar chat pela API serve para quê?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Para manter uma conversa prioritária sempre visível no topo, útil quando uma automação identifica um chat de alta prioridade (reclamação, cliente VIP) e quer garantir que ele não se perca no meio de outras conversas ativas."
      }
    },
    {
      "@type": "Question",
      "name": "Deletar chat pela API remove a conversa também do lado do cliente?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Não. Deletar chat aqui remove a conversa apenas da lista da sua instância — o mesmo efeito de apagar uma conversa pelo seu lado no app, sem afetar o que o outro contato vê do lado dele."
      }
    }
  ]
}
```