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
sessionIdidentifica a conexão de um cliente. Antes de chamar/chats/archiveem nome de um usuário, confira que aquelesessionIdpertence 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 umcommandIde 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.