Contatos

A API de Contatos permite verificar números de telefone no WhatsApp, recuperar informações de contatos e buscar fotos de perfil. Isso é especialmente útil para validar números antes de enviar mensagens e enriquecer seus dados de contato. Todos os endpoints de contatos são vinculados a uma instância específica:

/api/instances/{instanceId}/contacts/...

Verificar se um Número Existe

Verifique se um número de telefone está registrado no WhatsApp antes de enviar uma mensagem. Isso previne entregas falhas e chamadas de API desperdiçadas.

curl "https://api.wappfy.io/api/instances/inst_abc123/contacts/check?phone=5511999998888" \
  -H "X-Api-Key: YOUR_API_KEY"

const response = await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/contacts/check?phone=5511999998888",
  {
    headers: { "X-Api-Key": "YOUR_API_KEY" },
  }
);

const { data } = await response.json();
if (data.exists) {
  console.log(`Número existe no WhatsApp: ${data.chat_id}`);
} else {
  console.log("Número não está no WhatsApp");
}

Resposta (número existe):

{
  "data": {
    "exists": true,
    "phone": "5511999998888",
    "chat_id": "5511999998888@s.whatsapp.net"
  }
}

Resposta (número não existe):

{
  "data": {
    "exists": false,
    "phone": "5511999998888",
    "chat_id": null
  }
}

Use este endpoint para validar números antes de enviar mensagens. Isso economiza cota de mensagens e previne eventos message.failed no webhook.

Listar Todos os Contatos

Recupere a lista completa de contatos da conta WhatsApp conectada.

curl https://api.wappfy.io/api/instances/inst_abc123/contacts \
  -H "X-Api-Key: YOUR_API_KEY"

const response = await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/contacts",
  {
    headers: { "X-Api-Key": "YOUR_API_KEY" },
  }
);

const { data } = await response.json();
console.log(`Total de contatos: ${data.length}`);

Campos do Contato

Campo	Descrição
`id`	ID do contato no WhatsApp (número + `@s.whatsapp.net`).
`name`	Nome do contato salvo na agenda do telefone. Pode ser `null` se não salvo.
`short_name`	Nome curto da agenda.
`push_name`	Nome que o contato definiu para si mesmo no WhatsApp.
`is_business`	Se é uma conta WhatsApp Business.

O campo name vem da agenda do telefone. Se o contato não está salvo, apenas push_name (definido pelo próprio contato) estará disponível.

Informações do Contato

Recupere informações detalhadas sobre um contato específico.

curl "https://api.wappfy.io/api/instances/inst_abc123/contacts/5511999998888@s.whatsapp.net" \
  -H "X-Api-Key: YOUR_API_KEY"

Foto de Perfil

Recupere a URL da foto de perfil do WhatsApp de um contato.

curl "https://api.wappfy.io/api/instances/inst_abc123/contacts/5511999998888@s.whatsapp.net/profile-picture" \
  -H "X-Api-Key: YOUR_API_KEY"

const response = await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/contacts/5511999998888@s.whatsapp.net/profile-picture",
  {
    headers: { "X-Api-Key": "YOUR_API_KEY" },
  }
);

const { data } = await response.json();
if (data.profile_picture_url) {
  console.log(`Foto de perfil: ${data.profile_picture_url}`);
} else {
  console.log("Sem foto de perfil definida");
}

URLs de fotos de perfil são temporárias e expiram após algum tempo. Não as armazene permanentemente — busque uma URL nova quando necessário.

Padrões Comuns

Validar Antes de Enviar

Sempre verifique se um número existe no WhatsApp antes de enviar uma mensagem:

async function enviarMensagemComSeguranca(instanceId, phone, text) {
  // Passo 1: Verificar se o número está no WhatsApp
  const checkResponse = await fetch(
    `https://api.wappfy.io/api/instances/${instanceId}/contacts/check?phone=${phone}`,
    { headers: { "X-Api-Key": "YOUR_API_KEY" } }
  );
  const { data: checkResult } = await checkResponse.json();

  if (!checkResult.exists) {
    console.log(`${phone} não está no WhatsApp, pulando`);
    return null;
  }

  // Passo 2: Enviar a mensagem usando o chat_id confirmado
  const sendResponse = await fetch(
    `https://api.wappfy.io/api/instances/${instanceId}/messages/send`,
    {
      method: "POST",
      headers: {
        "X-Api-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        chat_id: checkResult.chat_id,
        type: "text",
        text,
      }),
    }
  );

  return sendResponse.json();
}

Ao buscar fotos de perfil para muitos contatos, adicione um atraso entre as requisições para respeitar os limites de taxa. Recomendamos 200ms entre chamadas.

Referência de Endpoints

Método	Endpoint	Descrição
`GET`	`/api/instances/{id}/contacts`	Listar todos os contatos
`GET`	`/api/instances/{id}/contacts/check?phone={phone}`	Verificar se número existe no WhatsApp
`GET`	`/api/instances/{id}/contacts/{contactId}`	Informações do contato
`GET`	`/api/instances/{id}/contacts/{contactId}/profile-picture`	Foto de perfil

Tratamento de Erros

Código	Descrição
`400`	Formato de número inválido. Use apenas dígitos, com código do país (ex: `5511999998888`).
`404`	Instância ou contato não encontrado.
`429`	Limite de taxa excedido. Veja Limites de Taxa.

Primeiros Passos

Guias

Contatos

Contatos

Verificar se um Número Existe

Listar Todos os Contatos

Campos do Contato

Informações do Contato

Foto de Perfil

Padrões Comuns

Validar Antes de Enviar

Referência de Endpoints

Tratamento de Erros

​Contatos

​Verificar se um Número Existe

​Listar Todos os Contatos

​Campos do Contato

​Informações do Contato

​Foto de Perfil

​Padrões Comuns

​Validar Antes de Enviar

​Referência de Endpoints

​Tratamento de Erros

Contatos

Verificar se um Número Existe

Listar Todos os Contatos

Campos do Contato

Informações do Contato

Foto de Perfil

Padrões Comuns

Validar Antes de Enviar

Referência de Endpoints

Tratamento de Erros