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"

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(`Number exists on WhatsApp: ${data.chat_id}`);
} else {
  console.log("Number is not on WhatsApp");
}

Respuesta (el numero existe):

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

Respuesta (el numero no existe):

{
  "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.

Obtener todos los contactos

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"

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 contacts: ${data.length}`);

Respuesta:

{
  "data": [
    {
      "id": "5511999998888@s.whatsapp.net",
      "name": "Maria Silva",
      "short_name": "Maria",
      "push_name": "Mari",
      "is_business": false
    },
    {
      "id": "5511888887777@s.whatsapp.net",
      "name": "Carlos Oliveira",
      "short_name": "Carlos",
      "push_name": "Carlos",
      "is_business": true
    }
  ]
}

Campos de contacto

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).

Obtener informacion de un contacto

Recupera informacion detallada sobre un contacto especifico.

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

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

const { data } = await response.json();
console.log(`Contact: ${data.push_name || data.name}`);

Respuesta:

{
  "data": {
    "id": "5511999998888@s.whatsapp.net",
    "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/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(`Profile picture: ${data.profile_picture_url}`);
} else {
  console.log("No profile picture set");
}

Respuesta:

{
  "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.

Si el contacto no tiene foto de perfil o ha restringido la visibilidad en su configuracion de privacidad, 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();
}

Construir un directorio de contactos

Obtiene todos los contactos y enriquecelos con fotos de perfil:

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.

Primeros Pasos

Guías

Contactos

Contactos

Verificar si un numero existe

Obtener todos los contactos

Campos de contacto

Obtener informacion de un contacto

Obtener foto de perfil

Patrones comunes

Validar antes de enviar

Construir un directorio de contactos

Referencia de endpoints

Manejo de errores

​Contactos

​Verificar si un numero existe

​Obtener todos los contactos

​Campos de contacto

​Obtener informacion de un contacto

​Obtener foto de perfil

​Patrones comunes

​Validar antes de enviar

​Construir un directorio de contactos

​Referencia de endpoints

​Manejo de errores

Contactos

Verificar si un numero existe

Obtener todos los contactos

Campos de contacto

Obtener informacion de un contacto

Obtener foto de perfil

Patrones comunes

Validar antes de enviar

Construir un directorio de contactos

Referencia de endpoints

Manejo de errores