Pular para o conteúdo
D-APITestar grátis

chats pela api

Gerenciar conversas do WhatsApp pela API, do inbox ao celular

Gerencie conversas do WhatsApp pela API dentro do seu SaaS: listar, buscar, arquivar, fixar, silenciar e marcar como lida, com paginação e webhooks que mantêm o seu inbox igual ao aparelho do cliente.

SaaS testa 14 dias com o time técnico ajudando na integração.

conexões na D-API
1.875
de uptime garantido em contrato
99,9%
datacenters no Brasil
4
por ligação de WhatsApp na API não-oficial
R$ 0
  • Listagem paginada e ordenável

    Chats por sessão com busca por nome ou telefone, ordenação por última mensagem ou não lidas e até 100 itens por página.

  • Busca em várias conexões

    Uma chamada procura chats ou mensagens em todas as sessões da conta, com filtro por tipo, remetente e intervalo de datas.

  • Estado espelhado no aparelho

    Arquivar, fixar, silenciar e marcar como não lida pela API reflete no WhatsApp do seu cliente, e o contrário chega por webhook.

  • Presença e leitura

    Mostre digitando ou gravando para o contato e envie recibo de leitura só das mensagens que o atendente abriu.

Gerenciar conversas do WhatsApp pela API é o que separa um SaaS que só dispara mensagens de um produto em que o seu cliente realmente atende. Quem vende helpdesk, CRM de vendas ou software de clínica precisa de um inbox: a lista de conversas com não lidas no topo, a busca pelo nome do paciente, o atendente arquivando o que já resolveu. Se cada uma dessas ações exige que alguém abra o celular, o seu produto vira uma segunda tela e o cliente volta para o aparelho.

Na API de WhatsApp da D-API, o grupo de rotas /api/v1/chats cobre esse inbox inteiro: listar, buscar, ler mensagens, mudar o estado do chat e sinalizar presença. Tudo amarrado ao sessionId da conexão do seu cliente.

O que o seu inbox ganha com a API de chats

O primeiro ganho é velocidade de tela. A listagem já vem pronta para paginação e ordenação, então a tela inicial do seu atendimento carrega 20 conversas ordenadas pela última mensagem, sem montar essa visão a partir de webhooks soltos.

O segundo é consistência. Quando o atendente arquiva uma conversa no seu painel, ela também fica arquivada no WhatsApp do cliente. Quando o dono da loja fixa um chat pelo celular, o evento chega no seu webhook e o seu inbox mostra o mesmo estado. Ninguém precisa perguntar “em qual tela está a versão certa?”.

O terceiro é busca. Um SaaS de clínica que atende várias unidades, cada uma com o seu número, consegue procurar “Mariana” em todas as conexões da conta com uma única chamada.

Listar e buscar conversas pela API

A listagem simples é um GET /api/v1/chats/ com sessionId obrigatório. Os parâmetros opcionais cobrem o que um inbox pede:

Parâmetro Para que serve
search Busca por nome do contato ou telefone normalizado
sort_field last_message_timestamp, unread_count, chat_name, id, created_at ou updated_at
sort_order asc ou desc (padrão desc)
limit / page Padrão de 20 itens, máximo de 100 por página
includeEmpty Inclui chats sem mensagens (padrão false)

Para telas mais ricas, o POST /api/v1/chats/search aceita sessionIds como lista. Lista vazia busca em todas as sessões do usuário dono da API key, o que resolve o caso do SaaS que mostra um inbox unificado para um cliente com vários números. O corpo também aceita isGroup para separar grupos de conversas individuais.

curl -X POST https://api.d-api.cloud/api/v1/chats/search \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionIds": ["clinica-unidade-centro", "clinica-unidade-norte"],
    "search": "Mariana",
    "isGroup": false,
    "sort_field": "unread_count",
    "sort_order": "desc",
    "limit": 50,
    "page": 1
  }'

Ler e pesquisar mensagens de um chat

Ao abrir uma conversa, o seu front chama GET /api/v1/chats/{chatId}/messages com o sessionId. A rota pagina com padrão de 50 mensagens (máximo de 100), ordena por timestamp e aceita search pelo conteúdo da mensagem.

Para relatórios e auditoria, o POST /api/v1/chats/messages/search vai além. Você pode filtrar por type (text, image, video, audio, document, sticker, location, contact, reaction), por fromMe e por intervalo com dateFrom e dateTo. E pode localizar a conversa por phone, sem precisar do ID interno do chat. Um CRM imobiliário que quer mostrar “todos os documentos que o corretor enviou para este lead no último mês” resolve com um filtro só.

Arquivar, fixar, silenciar e marcar como não lida

As quatro ações de estado seguem o mesmo formato: sessionId, to (número ou JID do chat) e um booleano. A ação é aplicada no WhatsApp da conexão, então aparece no celular do seu cliente.

Rota Campo Observação
POST /api/v1/chats/archive archive Arquivar também desafixa o chat
POST /api/v1/chats/pin pin false desafixa
POST /api/v1/chats/mute mute, durationSeconds 0 ou ausente silencia sem prazo; máximo de 366 dias
POST /api/v1/chats/mark-unread unread Só muda a marcação, sem recibo de leitura
{
  "sessionId": "clinica-unidade-centro",
  "to": "5511999999999",
  "archive": true
}

Para conferir o resultado em tela, GET /api/v1/chats/archived e GET /api/v1/chats/pinned listam esses chats pela última mensagem, paginados com hasMore. Essas ações de estado rodam como comando na conexão do número, por isso valem para as conexões da API não-oficial, que mantêm o WhatsApp do aparelho sincronizado.

Leitura e presença: o que o contato vê

Recibo de leitura é decisão de produto. Em atendimento, faz sentido marcar como lida só quando o atendente abre a conversa no seu painel. O POST /api/v1/chats/read recebe sessionId, to e a lista messageIds (mínimo de um item), e aceita participant para mensagens de grupo.

A presença dá ao contato o sinal de que alguém está respondendo. O POST /api/v1/chats/presence envia available ou unavailable para a conta inteira, ou typing, recording e paused para um chat específico. Com durationMs, o estado de digitando ou gravando se mantém pelo tempo informado e pausa sozinho. Um agente de IA que leva alguns segundos para responder pode mostrar “digitando” durante a geração da resposta.

Existe também a configuração de sessão markPreviousAsRead: quando ligada, as mensagens anteriores do chat são marcadas como lidas automaticamente depois que a conexão envia uma mensagem. Útil para quem não quer controlar leitura mensagem a mensagem.

Mantendo o inbox sincronizado com webhooks

A API cobre o que o seu sistema faz. Os webhooks cobrem o que acontece no aparelho. Os eventos chats.upsert (chat novo ou recebido na sincronização) e chats.update (chat existente alterado) trazem o mesmo formato de data:

{
  "event": "chats.update",
  "sessionId": "clinica-unidade-centro",
  "timestamp": "2026-01-24T23:05:00.000Z",
  "data": {
    "jid": "[email protected]",
    "name": "João",
    "unread_count": 2,
    "conversation_timestamp": 1769295900,
    "archived": false,
    "pinned": 0,
    "mute_end_time": 0
  }
}

Com archived, pinned, mute_end_time e unread_count, o seu banco atualiza a linha do chat sem consultar a API de novo. Os eventos chats.upsert passam por debounce de 2 segundos por chat, então várias mudanças seguidas chegam agrupadas. O formato completo está na documentação da D-API, e o artigo sobre webhooks da API de WhatsApp cobre retentativas e idempotência.

Desenho recomendado para um SaaS multi-tenant

Algumas escolhas deixam o inbox rápido e correto quando a sua base cresce:

  • Banco próprio como fonte da tela. Use a listagem da API para a carga inicial e os webhooks para manter a sua tabela de chats atualizada. A tela do atendente lê do seu banco, paginada.
  • Tenant em toda consulta. O sessionId identifica a conexão de um cliente. Antes de chamar /chats/archive em nome de um usuário, confira que aquele sessionId pertence ao tenant dele. O artigo sobre API de WhatsApp multi-tenant detalha esse desenho.
  • Ações em lote fora do request. Arquivar 300 conversas antigas de uma vez é trabalho de fila. As rotas de estado aceitam async: true, que responde na hora com um commandId e entrega o resultado depois.
  • Etiquetas para organizar. Arquivar resolve o que acabou; para classificar o que está aberto, combine com as etiquetas pela API.

Se o seu cliente já tem anos de conversa no celular e quer ver isso no seu produto desde o primeiro dia, o próximo passo é sincronizar o histórico de conversas.

Time D-API. Atualizado em .

Perguntas frequentes

Marcar como não lida envia recibo de leitura para o contato?

Não. O POST /api/v1/chats/mark-unread só muda a marcação do chat, como no aplicativo. Para enviar o recibo de leitura, use o POST /api/v1/chats/read com os messageIds.

Por quanto tempo dá para silenciar um chat pela API?

O POST /api/v1/chats/mute aceita durationSeconds até 366 dias. Com durationSeconds igual a 0 ou ausente, o chat fica silenciado sem prazo. Para reativar, envie mute: false.

Consigo listar só as conversas que estão arquivadas ou fixadas?

Sim. GET /api/v1/chats/archived e GET /api/v1/chats/pinned retornam esses chats ordenados pela última mensagem, com limit padrão de 20 e máximo de 100, e um campo hasMore na paginação.

A busca de mensagens precisa do ID interno do chat?

Não. O POST /api/v1/chats/messages/search aceita chatId ou phone, então você pode buscar pelo número do contato que já está no seu CRM.

Se a conexão estiver com armazenamento de mensagens desligado, a listagem funciona?

Com disableMessageStorage ativo, o conteúdo das mensagens daquela conexão não é gravado no banco da D-API. Os webhooks continuam chegando, então o histórico passa a ser responsabilidade do seu banco.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.