contatos
API WhatsApp contatos para validar números e enriquecer o cadastro do seu SaaS
Com a API WhatsApp contatos da D-API, o seu SaaS confere se um número tem WhatsApp antes de salvar, traz foto, recado e perfil comercial do contato e controla a lista de bloqueados, tudo pela mesma conexão 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
Verificação em lote
Mande uma lista de números para POST /contacts/check e saiba quais têm WhatsApp antes de cadastrar ou disparar qualquer mensagem.
Perfil comercial completo
Para contas business, a consulta traz descrição, site, endereço, categorias, horário de atendimento e as redes vinculadas.
Foto com link durável
O link de foto do WhatsApp expira rápido. A D-API copia a imagem para storage e devolve uma URL que continua funcionando.
A API WhatsApp contatos responde às perguntas que todo SaaS faz antes de conversar com alguém: esse número tem WhatsApp? É de uma empresa? Qual a foto e o nome que a pessoa usa? Para um CRM, é a diferença entre um card de lead com um telefone solto e um card com foto, nome de exibição, site e horário de atendimento. Para uma clínica, é saber no cadastro do paciente se o lembrete por WhatsApp vai chegar ou se o melhor é outro canal.
As rotas ficam em /api/v1/contacts e usam a conexão da API não oficial do seu cliente para consultar o WhatsApp.
Verificar se o número tem WhatsApp
POST /api/v1/contacts/check recebe uma lista de números e devolve, para cada um, se ele está registrado no WhatsApp.
curl -X POST https://api.d-api.cloud/api/v1/contacts/check \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "crm-imobi-vendas",
"numbers": ["5511999999999", "5511988887777"]
}'
O lugar mais útil para essa chamada é o formulário de cadastro. Quando o corretor salva um lead no CRM imobiliário, o seu backend verifica o número e marca o card como “tem WhatsApp” ou “ligar por telefone”. O resultado evita mensagens que nunca chegariam e deixa os relatórios de entrega mais honestos.
A rota exige a sessão conectada. Para listas maiores, use async: true: a API responde com um commandId e entrega o resultado no webhook command.result.
Consultar o perfil do contato
GET /api/v1/contacts/{phone} traz tudo que o WhatsApp mostra sobre o contato. A mesma resposta vem de POST /api/v1/contacts/getuser, com os parâmetros no corpo.
{
"success": true,
"data": {
"jid": "[email protected]",
"phone": "5511988887777",
"lid": "163896103039140@lid",
"pushName": "Minha Empresa",
"isBusiness": true,
"isOfficial": false,
"isOnWhatsApp": true,
"status": "Atendimento de segunda a sábado",
"avatar": "https://s3.us-east-005.backblazeb2.com/d-api-media/avatars/5511988887777.jpg",
"businessProfile": {
"description": "Agência de marketing digital",
"websites": ["https://minhaempresa.com.br"],
"categories": [{ "id": "123377808095874", "name": "Agência de marketing" }],
"businessHours": { "timezone": "America/Sao_Paulo", "days": [] }
}
}
}
Os campos principais: pushName é o nome que a pessoa definiu no WhatsApp, status é o recado do perfil, isBusiness indica conta do app WhatsApp Business ou da API Oficial, e isOfficial separa as contas da API Oficial. Um número fora do WhatsApp volta só com phone e isOnWhatsApp: false, então a mesma rota também serve de verificação individual.
Guarde também o LID. É o identificador que o WhatsApp usa internamente para o contato, e em alguns eventos ele aparece no lugar do telefone. Com os dois salvos no cadastro, o seu sistema reconhece o contato em qualquer formato.
Perfil comercial para enriquecer o CRM
Quando o contato é uma empresa, a resposta traz businessProfile com o perfil comercial público: descrição, e-mail, endereço, sites, localização, categorias, horário de atendimento por dia da semana, contas vinculadas do Instagram e do Facebook, serviços oferecidos e foto de capa.
Para um CRM B2B, isso é enriquecimento de lead sem integração extra. O vendedor abre o card e já vê o segmento, o site e o horário em que a empresa atende. Para uma plataforma de agendamento, o horário de atendimento em businessHours vem estruturado com dayOfWeek, mode e horários em HH:MM, incluindo turnos partidos como duas entradas no mesmo dia.
O perfil comercial vem por padrão e custa uma consulta a mais ao WhatsApp, de até 10 segundos. Se a tela não precisa dele, desligue com business=false na query. Trate o campo como opcional: em contato pessoal, ou se o WhatsApp não responder a tempo, ele não vem.
A coverPhotoUrl do perfil é um link assinado que expira. Se for exibir a capa depois, baixe e guarde a imagem.
Foto do contato com cache e link durável
Os links de foto de perfil do WhatsApp têm vida curta. Se o seu CRM salvar o link direto, a foto quebra em pouco tempo. A D-API resolve isso copiando a imagem para storage e devolvendo uma URL própria no campo avatar, que continua válida.
Para buscar só a foto, use GET /api/v1/contacts/{phone}/avatar. A rota consulta primeiro o cache e só vai ao WhatsApp quando não encontra a imagem. Três parâmetros ajustam o comportamento:
| Parâmetro | Efeito |
|---|---|
force=true |
Ignora o cache e busca a foto atual direto no WhatsApp |
preview=true |
Traz a foto em baixa resolução, boa para listas e miniaturas |
avatar=false |
Em GET /contacts/{phone}, pula a busca da foto |
Numa lista de conversas com centenas de contatos, preview=true deixa a tela leve. No card de detalhe, a foto em resolução cheia faz mais sentido. E quando o contato chega no webhook contacts.update com foto nova, vale chamar com force=true para atualizar o cache.
A documentação da D-API lista todos os campos de businessProfile.
Bloquear, desbloquear e reportar contatos
Atendimento também tem lado chato: o contato que manda mensagem ofensiva, o golpista tentando se passar por cliente. O seu SaaS pode dar ao atendente o botão de bloquear sem que ele precise pegar o celular.
POST /api/v1/contacts/blocklist recebe phone e action, com block ou unblock. GET /api/v1/contacts/blocklist devolve a lista de contatos bloqueados da conta, com JIDs e telefones, para exibir numa tela de configurações.
{
"sessionId": "helpdesk-acme",
"phone": "5511977776666",
"action": "block"
}
Para casos mais graves, POST /api/v1/contacts/report reporta o contato ao WhatsApp e, com block: true, já bloqueia na mesma chamada. A resposta separa o resultado das duas etapas, em report e block, porque uma pode dar certo e a outra não.
Onde os contatos entram no seu produto
A agenda da conta, com os contatos salvos no celular do cliente, sai em GET /api/v1/contacts. Novos contatos e mudanças de nome ou foto chegam pelos eventos contacts.upsert e contacts.update, listados em eventos de webhook.
Combine com as etiquetas para levar a classificação do funil do seu CRM para dentro do WhatsApp do cliente, e com o envio de mensagens para fechar o ciclo: valida o número, enriquece o cadastro, conversa. A visão completa está na página da API de WhatsApp.
Time D-API. Atualizado em .
Perguntas frequentes
Preciso que o número esteja salvo na agenda do celular para consultar?
Não. A verificação e a consulta de perfil funcionam com qualquer número informado. Os contatos salvos na agenda da conta podem ser listados à parte em GET /api/v1/contacts.
A verificação funciona com a sessão desconectada?
Não. A rota de verificação exige a sessão conectada e responde Session not connected quando ela não está.
Consigo saber quando um contato muda de nome ou de foto?
Sim. O webhook contacts.update avisa quando um contato é atualizado, incluindo nome e foto, e contacts.upsert avisa sobre contato novo.
Como sei se a empresa usa o app WhatsApp Business ou uma API?
Pelo campo accountType do businessProfile. O valor smb indica o app WhatsApp Business, e ent indica uma conta hospedada por API.