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"
{
"data": {
"exists": true,
"phone": "5511999998888",
"chat_id": "[email protected]"
}
}
{
"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"
{
"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
}
]
}
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.
Rufen Sie detaillierte Informationen zu einem bestimmten Kontakt ab.
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
}
}
Profilbild abrufen
Rufen Sie die WhatsApp-Profilbild-URL eines Kontakts ab.
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/..."
}
}
Profilbild-URLs sind temporaer und laufen nach einiger Zeit ab. Speichern Sie sie nicht dauerhaft — rufen Sie bei Bedarf eine aktuelle URL ab.
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. |
