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"

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

Reponse (le numero existe) :

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

Reponse (le numero n’existe pas) :

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

Obtenir tous les contacts

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"

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

Reponse :

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

Champs du contact

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.

Obtenir les informations d’un contact

Recuperez les informations detaillees d’un contact specifique.

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

Reponse :

{
  "data": {
    "id": "5511999998888@s.whatsapp.net",
    "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/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");
}

Reponse :

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

Si le contact n’a pas de photo de profil ou a restreint la visibilite dans ses parametres de confidentialite, 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();
}

Construire un repertoire de contacts

Recuperez tous les contacts et enrichissez-les avec les photos de profil :

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.

Premiers Pas

Guides

Contacts

Contacts

Verifier si un numero existe

Obtenir tous les contacts

Champs du contact

Obtenir les informations d’un contact

Obtenir la photo de profil

Schemas courants

Valider avant d’envoyer

Construire un repertoire de contacts

Reference des endpoints

Gestion des erreurs

​Contacts

​Verifier si un numero existe

​Obtenir tous les contacts

​Champs du contact

​Obtenir les informations d’un contact

​Obtenir la photo de profil

​Schemas courants

​Valider avant d’envoyer

​Construire un repertoire de contacts

​Reference des endpoints

​Gestion des erreurs

Contacts

Verifier si un numero existe

Obtenir tous les contacts

Champs du contact

Obtenir les informations d’un contact

Obtenir la photo de profil

Schemas courants

Valider avant d’envoyer

Construire un repertoire de contacts

Reference des endpoints

Gestion des erreurs