Contatti

L’API Contatti ti permette di verificare i numeri di telefono su WhatsApp, recuperare informazioni sui contatti e ottenere le immagini del profilo. Questo e particolarmente utile per validare i numeri prima di inviare messaggi e arricchire i dati dei tuoi contatti. Tutti gli endpoint dei contatti sono associati a un’istanza specifica:

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

Verificare se un numero esiste

Verifica se un numero di telefono e registrato su WhatsApp prima di inviare un messaggio. Questo previene consegne fallite e chiamate API inutili.

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");
}

Risposta (numero esistente):

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

Risposta (numero inesistente):

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

Usa questo endpoint per validare i numeri prima di inviare messaggi. Risparmia sulla quota messaggi e previene gli eventi webhook message.failed.

Ottenere tutti i contatti

Recupera l’elenco completo dei contatti dell’account WhatsApp connesso.

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}`);

Risposta:

{
  "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
    }
  ]
}

Campi del contatto

Campo	Descrizione
`id`	L’ID WhatsApp del contatto (numero di telefono + `@s.whatsapp.net`).
`name`	Nome del contatto salvato nella rubrica del telefono. Puo essere `null` se non salvato.
`short_name`	Nome abbreviato dalla rubrica.
`push_name`	Il nome che il contatto ha impostato per se stesso su WhatsApp.
`is_business`	Se si tratta di un account WhatsApp Business.

Il campo name proviene dalla rubrica del tuo telefono. Se il contatto non e salvato, sara disponibile solo il push_name (impostato dal contatto stesso).

Ottenere informazioni su un contatto

Recupera informazioni dettagliate su un contatto specifico.

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}`);

Risposta:

{
  "data": {
    "id": "5511999998888@s.whatsapp.net",
    "name": "Maria Silva",
    "short_name": "Maria",
    "push_name": "Mari",
    "is_business": false
  }
}

Ottenere l’immagine del profilo

Recupera l’URL dell’immagine del profilo WhatsApp di un contatto.

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");
}

Risposta:

{
  "data": {
    "profile_picture_url": "https://pps.whatsapp.net/v/t61.24694-24/..."
  }
}

Gli URL delle immagini del profilo sono temporanei e scadono dopo un certo periodo. Non memorizzarli in modo permanente — recupera un URL aggiornato quando necessario.

Se il contatto non ha un’immagine del profilo o ha limitato la visibilita nelle impostazioni di privacy, profile_picture_url sara null:

{
  "data": {
    "profile_picture_url": null
  }
}

Pattern comuni

Validare prima dell’invio

Verifica sempre se un numero esiste su WhatsApp prima di inviare un messaggio per evitare errori inutili:

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();
}

Creare una rubrica contatti

Recupera tutti i contatti e arricchiscili con le immagini del profilo:

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;
}

Quando recuperi le immagini del profilo per molti contatti, aggiungi un ritardo tra le richieste per rispettare i limiti di frequenza. L’esempio sopra utilizza un ritardo di 200ms.

Riferimento degli endpoint

Metodo	Endpoint	Descrizione
`GET`	`/api/instances/{id}/contacts`	Elenca tutti i contatti
`GET`	`/api/instances/{id}/contacts/check?phone={phone}`	Verifica se un numero esiste su WhatsApp
`GET`	`/api/instances/{id}/contacts/{contactId}`	Ottieni informazioni su un contatto
`GET`	`/api/instances/{id}/contacts/{contactId}/profile-picture`	Ottieni l’immagine del profilo

Gestione degli errori

Codice di stato	Descrizione
`400`	Formato del numero di telefono non valido. Usa solo cifre, con prefisso internazionale (es. `5511999998888`).
`404`	Istanza non trovata o contatto non trovato.
`429`	Limite di frequenza superato. Consulta Limiti di frequenza.

Per Iniziare

Guide

Contatti

Contatti

Verificare se un numero esiste

Ottenere tutti i contatti

Campi del contatto

Ottenere informazioni su un contatto

Ottenere l’immagine del profilo

Pattern comuni

Validare prima dell’invio

Creare una rubrica contatti

Riferimento degli endpoint

Gestione degli errori

​Contatti

​Verificare se un numero esiste

​Ottenere tutti i contatti

​Campi del contatto

​Ottenere informazioni su un contatto

​Ottenere l’immagine del profilo

​Pattern comuni

​Validare prima dell’invio

​Creare una rubrica contatti

​Riferimento degli endpoint

​Gestione degli errori

Contatti

Verificare se un numero esiste

Ottenere tutti i contatti

Campi del contatto

Ottenere informazioni su un contatto

Ottenere l’immagine del profilo

Pattern comuni

Validare prima dell’invio

Creare una rubrica contatti

Riferimento degli endpoint

Gestione degli errori