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"
{
"data": {
"exists": true,
"phone": "5511999998888",
"chat_id": "[email protected]"
}
}
{
"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"
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.
Recupere informações detalhadas sobre um contato específico.
curl "https://api.wappfy.io/api/instances/inst_abc123/contacts/[email protected]" \
-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/[email protected]/profile-picture" \
-H "X-Api-Key: YOUR_API_KEY"
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. |
