Kontakte

Die Kontakte-API ermoeglicht es Ihnen, Telefonnummern auf WhatsApp zu verifizieren, Kontaktinformationen abzurufen und Profilbilder zu laden. Dies ist besonders nuetzlich, um Nummern vor dem Senden von Nachrichten zu validieren und Ihre Kontaktdaten anzureichern. Alle Kontakt-Endpunkte beziehen sich auf eine bestimmte Instanz:

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

Pruefen, ob eine Nummer existiert

Ueberpruefen Sie, ob eine Telefonnummer auf WhatsApp registriert ist, bevor Sie eine Nachricht senden. Dies verhindert fehlgeschlagene Zustellungen und unnoetige API-Aufrufe.

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

Antwort (Nummer existiert):

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

Antwort (Nummer existiert nicht):

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

Verwenden Sie diesen Endpunkt, um Nummern vor dem Senden von Nachrichten zu validieren. Das spart Nachrichtenkontingent und verhindert message.failed-Webhook-Ereignisse.

Alle Kontakte abrufen

Rufen Sie die vollstaendige Kontaktliste des verbundenen WhatsApp-Kontos ab.

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

Antwort:

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

Kontaktfelder

Feld	Beschreibung
`id`	Die WhatsApp-ID des Kontakts (Telefonnummer + `@s.whatsapp.net`).
`name`	Kontaktname wie im Adressbuch des Telefons gespeichert. Kann `null` sein, wenn nicht gespeichert.
`short_name`	Kurzname aus dem Adressbuch.
`push_name`	Der Name, den der Kontakt fuer sich selbst auf WhatsApp festgelegt hat.
`is_business`	Ob es sich um ein WhatsApp-Business-Konto handelt.

Das Feld name stammt aus dem Adressbuch Ihres Telefons. Wenn der Kontakt nicht gespeichert ist, ist nur push_name (vom Kontakt selbst festgelegt) verfuegbar.

Kontaktinformationen abrufen

Rufen Sie detaillierte Informationen zu einem bestimmten Kontakt ab.

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

Antwort:

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

Profilbild abrufen

Rufen Sie die WhatsApp-Profilbild-URL eines Kontakts ab.

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

Antwort:

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

Profilbild-URLs sind temporaer und laufen nach einiger Zeit ab. Speichern Sie sie nicht dauerhaft — rufen Sie bei Bedarf eine aktuelle URL ab.

Wenn der Kontakt kein Profilbild hat oder die Sichtbarkeit in seinen Datenschutzeinstellungen eingeschraenkt hat, ist profile_picture_url null:

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

Haeufige Muster

Vor dem Senden validieren

Pruefen Sie immer, ob eine Nummer auf WhatsApp existiert, bevor Sie eine Nachricht senden, um unnoetige Fehler zu vermeiden:

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

Kontaktverzeichnis erstellen

Rufen Sie alle Kontakte ab und reichern Sie sie mit Profilbildern an:

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

Wenn Sie Profilbilder fuer viele Kontakte abrufen, fuegen Sie eine Verzoegerung zwischen den Anfragen hinzu, um innerhalb der Ratenlimits zu bleiben. Das obige Beispiel verwendet eine Verzoegerung von 200ms.

Endpunkt-Referenz

Methode	Endpunkt	Beschreibung
`GET`	`/api/instances/{id}/contacts`	Alle Kontakte auflisten
`GET`	`/api/instances/{id}/contacts/check?phone={phone}`	Pruefen, ob eine Nummer auf WhatsApp existiert
`GET`	`/api/instances/{id}/contacts/{contactId}`	Kontaktinformationen abrufen
`GET`	`/api/instances/{id}/contacts/{contactId}/profile-picture`	Profilbild abrufen

Fehlerbehandlung

Statuscode	Beschreibung
`400`	Ungueltiges Telefonnummernformat. Verwenden Sie nur Ziffern mit Laendervorwahl (z.B. `5511999998888`).
`404`	Instanz nicht gefunden oder Kontakt nicht gefunden.
`429`	Ratenlimit ueberschritten. Siehe Ratenlimits.

Erste Schritte

Anleitungen

Kontakte

Kontakte

Pruefen, ob eine Nummer existiert

Alle Kontakte abrufen

Kontaktfelder

Kontaktinformationen abrufen

Profilbild abrufen

Haeufige Muster

Vor dem Senden validieren

Kontaktverzeichnis erstellen

Endpunkt-Referenz

Fehlerbehandlung

​Kontakte

​Pruefen, ob eine Nummer existiert

​Alle Kontakte abrufen

​Kontaktfelder

​Kontaktinformationen abrufen

​Profilbild abrufen

​Haeufige Muster

​Vor dem Senden validieren

​Kontaktverzeichnis erstellen

​Endpunkt-Referenz

​Fehlerbehandlung

Kontakte

Pruefen, ob eine Nummer existiert

Alle Kontakte abrufen

Kontaktfelder

Kontaktinformationen abrufen

Profilbild abrufen

Haeufige Muster

Vor dem Senden validieren

Kontaktverzeichnis erstellen

Endpunkt-Referenz

Fehlerbehandlung