Contacts
L’API Contacts vous permet de verifier les numeros de telephone sur WhatsApp, de recuperer les informations de contact et d’obtenir les photos de profil. C’est particulierement utile pour valider les numeros avant d’envoyer des messages et pour enrichir vos donnees de contact.
Tous les endpoints de contacts sont limites a une instance specifique :
/api/instances/{instanceId}/contacts/...
Verifier si un numero existe
Verifiez si un numero de telephone est enregistre sur WhatsApp avant d’envoyer un message. Cela evite les echecs de livraison et les appels API inutiles.
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
}
}
Utilisez cet endpoint pour valider les numeros avant d’envoyer des messages. Cela economise le quota de messages et evite les evenements webhook message.failed.
Recuperez la liste complete des contacts du compte WhatsApp connecte.
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
}
]
}
| Champ | Description |
|---|
id | L’identifiant WhatsApp du contact (numero de telephone + @s.whatsapp.net). |
name | Nom du contact tel qu’enregistre dans le repertoire du telephone. Peut etre null si non enregistre. |
short_name | Nom court du repertoire. |
push_name | Le nom que le contact a defini pour lui-meme sur WhatsApp. |
is_business | Indique s’il s’agit d’un compte WhatsApp Business. |
Le champ name provient du repertoire de votre telephone. Si le contact n’est pas enregistre, seul push_name (defini par le contact lui-meme) sera disponible.
Recuperez les informations detaillees d’un contact specifique.
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
}
}
Obtenir la photo de profil
Recuperez l’URL de la photo de profil WhatsApp d’un contact.
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/..."
}
}
Les URL des photos de profil sont temporaires et expirent apres un certain temps. Ne les stockez pas de maniere permanente — recuperez une URL fraiche lorsque necessaire.
profile_picture_url sera null :
{
"data": {
"profile_picture_url": null
}
}
Schemas courants
Valider avant d’envoyer
Verifiez toujours si un numero existe sur WhatsApp avant d’envoyer un message pour eviter les echecs inutiles :
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;
}
Lors de la recuperation des photos de profil pour de nombreux contacts, ajoutez un delai entre les requetes pour rester dans les limites de debit. L’exemple ci-dessus utilise un delai de 200 ms.
Reference des endpoints
| Methode | Endpoint | Description |
|---|
GET | /api/instances/{id}/contacts | Lister tous les contacts |
GET | /api/instances/{id}/contacts/check?phone={phone} | Verifier si un numero existe sur WhatsApp |
GET | /api/instances/{id}/contacts/{contactId} | Obtenir les infos d’un contact |
GET | /api/instances/{id}/contacts/{contactId}/profile-picture | Obtenir la photo de profil |
Gestion des erreurs
| Code de statut | Description |
|---|
400 | Format de numero de telephone invalide. Utilisez uniquement des chiffres, avec l’indicatif pays (par ex., 5511999998888). |
404 | Instance ou contact non trouve. |
429 | Limite de debit depassee. Voir Limites de debit. |
