Contactos
La API de Contactos te permite verificar numeros de telefono en WhatsApp, recuperar informacion de contacto y obtener fotos de perfil. Esto es especialmente util para validar numeros antes de enviar mensajes y enriquecer tus datos de contacto.
Todos los endpoints de contactos estan asociados a una instancia especifica:
/api/instances/{instanceId}/contacts/...
Verificar si un numero existe
Verifica si un numero de telefono esta registrado en WhatsApp antes de enviar un mensaje. Esto evita entregas fallidas y llamadas a la API innecesarias.
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
}
}
Usa este endpoint para validar numeros antes de enviar mensajes. Ahorra cuota de mensajes y previene eventos de webhook message.failed.
Recupera la lista completa de contactos de la cuenta de WhatsApp conectada.
curl https://api.wappfy.io/api/instances/inst_abc123/contacts \
-H "X-Api-Key: YOUR_API_KEY"
{
"data": [
{
"id": "[email protected]",
"name": "Maria Silva",
"short_name": "Maria",
"push_name": "Mari",
"is_business": false
},
{
"id": "[email protected]",
"name": "Carlos Oliveira",
"short_name": "Carlos",
"push_name": "Carlos",
"is_business": true
}
]
}
| Campo | Descripcion |
|---|
id | El ID de WhatsApp del contacto (numero de telefono + @s.whatsapp.net). |
name | Nombre del contacto guardado en la agenda del telefono. Puede ser null si no esta guardado. |
short_name | Nombre corto de la agenda. |
push_name | El nombre que el contacto ha configurado para si mismo en WhatsApp. |
is_business | Si esta es una cuenta de WhatsApp Business. |
El campo name proviene de la agenda de tu telefono. Si el contacto no esta guardado, solo estara disponible push_name (configurado por el propio contacto).
Recupera informacion detallada sobre un contacto especifico.
curl "https://api.wappfy.io/api/instances/inst_abc123/contacts/[email protected]" \
-H "X-Api-Key: YOUR_API_KEY"
{
"data": {
"id": "[email protected]",
"name": "Maria Silva",
"short_name": "Maria",
"push_name": "Mari",
"is_business": false
}
}
Obtener foto de perfil
Recupera la URL de la foto de perfil de WhatsApp de un contacto.
curl "https://api.wappfy.io/api/instances/inst_abc123/contacts/[email protected]/profile-picture" \
-H "X-Api-Key: YOUR_API_KEY"
{
"data": {
"profile_picture_url": "https://pps.whatsapp.net/v/t61.24694-24/..."
}
}
Las URLs de fotos de perfil son temporales y expiran despues de un tiempo. No las almacenes de forma permanente — obtiene una URL nueva cuando la necesites.
profile_picture_url sera null:
{
"data": {
"profile_picture_url": null
}
}
Patrones comunes
Validar antes de enviar
Siempre verifica si un numero existe en WhatsApp antes de enviar un mensaje para evitar fallas innecesarias:
async function sendMessageSafely(instanceId, phone, text) {
// Step 1: Check if the number is on 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} is not on WhatsApp, skipping`);
return null;
}
// Step 2: Send the message using the confirmed chat_id
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();
}
async function buildContactDirectory(instanceId) {
// Get all contacts
const contactsRes = await fetch(
`https://api.wappfy.io/api/instances/${instanceId}/contacts`,
{ headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
const { data: contacts } = await contactsRes.json();
// Enrich with profile pictures (batch with delay to avoid rate limits)
const enriched = [];
for (const contact of contacts) {
const picRes = await fetch(
`https://api.wappfy.io/api/instances/${instanceId}/contacts/${contact.id}/profile-picture`,
{ headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
const { data: pic } = await picRes.json();
enriched.push({
...contact,
profile_picture_url: pic.profile_picture_url,
});
// Small delay to respect rate limits
await new Promise((r) => setTimeout(r, 200));
}
return enriched;
}
Al obtener fotos de perfil de muchos contactos, agrega un retraso entre solicitudes para mantenerte dentro de los limites de tasa. El ejemplo anterior usa un retraso de 200ms.
Referencia de endpoints
| Metodo | Endpoint | Descripcion |
|---|
GET | /api/instances/{id}/contacts | Listar todos los contactos |
GET | /api/instances/{id}/contacts/check?phone={phone} | Verificar si un numero existe en WhatsApp |
GET | /api/instances/{id}/contacts/{contactId} | Obtener informacion del contacto |
GET | /api/instances/{id}/contacts/{contactId}/profile-picture | Obtener foto de perfil |
Manejo de errores
| Codigo de estado | Descripcion |
|---|
400 | Formato de numero de telefono invalido. Usa solo digitos, con codigo de pais (por ejemplo, 5511999998888). |
404 | Instancia no encontrada o contacto no encontrado. |
429 | Limite de tasa excedido. Consulta Limites de tasa. |
