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

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.

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.

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.