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"
{
"data": {
"exists": true,
"phone": "5511999998888",
"chat_id": "[email protected]"
}
}
{
"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"
{
"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
}
]
}
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).
Recupera informazioni dettagliate su un contatto specifico.
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
}
}
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/[email protected]/profile-picture" \
-H "X-Api-Key: YOUR_API_KEY"
{
"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.
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. |
