Kontakty
API Kontaktow umozliwia weryfikacje numerow telefonow na WhatsApp, pobieranie informacji o kontaktach i pobieranie zdjec profilowych. Jest to szczegolnie przydatne do walidacji numerow przed wysylaniem wiadomosci i wzbogacania danych kontaktowych.
Wszystkie endpointy kontaktow sa przypisane do konkretnej instancji:
/api/instances/{instanceId}/contacts/...
Sprawdzanie istnienia numeru
Zweryfikuj, czy numer telefonu jest zarejestrowany na WhatsApp przed wyslaniem wiadomosci. Zapobiega to nieudanym dostarczeniom i zmarnowanym wywolaniom API.
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
}
}
Uzyj tego endpointu do walidacji numerow przed wysylaniem wiadomosci. Oszczedza to limit wiadomosci i zapobiega zdarzeniom webhook message.failed.
Pobieranie wszystkich kontaktow
Pobierz pelna liste kontaktow dla polaczonego konta WhatsApp.
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
}
]
}
Pola kontaktu
| Pole | Opis |
|---|
id | Identyfikator WhatsApp kontaktu (numer telefonu + @s.whatsapp.net). |
name | Nazwa kontaktu zapisana w ksiazce adresowej telefonu. Moze byc null, jesli nie jest zapisany. |
short_name | Krotka nazwa z ksiazki adresowej. |
push_name | Nazwa, ktora kontakt sam ustawil na WhatsApp. |
is_business | Czy jest to konto WhatsApp Business. |
Pole name pochodzi z ksiazki adresowej Twojego telefonu. Jesli kontakt nie jest zapisany, dostepna bedzie tylko wartosc push_name (ustawiona przez samego kontaktu).
Pobierz szczegolowe informacje o konkretnym kontakcie.
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
}
}
Zdjecie profilowe
Pobierz URL zdjecia profilowego WhatsApp kontaktu.
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/..."
}
}
Adresy URL zdjec profilowych sa tymczasowe i wygasaja po pewnym czasie. Nie przechowuj ich na stale — pobieraj swiezy URL, gdy jest potrzebny.
profile_picture_url bedzie rowne null:
{
"data": {
"profile_picture_url": null
}
}
Typowe wzorce
Walidacja przed wyslaniem
Zawsze sprawdzaj, czy numer istnieje na WhatsApp przed wyslaniem wiadomosci, aby uniknac niepotrzebnych niepowodzen:
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();
}
Budowanie katalogu kontaktow
Pobierz wszystkie kontakty i wzbogac je o zdjecia profilowe:
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;
}
Przy pobieraniu zdjec profilowych dla wielu kontaktow dodaj opoznienie miedzy zapytaniami, aby nie przekroczyc limitow zapytan. Powyzszy przyklad uzywa opoznienia 200ms.
| Metoda | Endpoint | Opis |
|---|
GET | /api/instances/{id}/contacts | Lista wszystkich kontaktow |
GET | /api/instances/{id}/contacts/check?phone={phone} | Sprawdz, czy numer istnieje na WhatsApp |
GET | /api/instances/{id}/contacts/{contactId} | Informacje o kontakcie |
GET | /api/instances/{id}/contacts/{contactId}/profile-picture | Zdjecie profilowe |
Obsluga bledow
| Kod statusu | Opis |
|---|
400 | Nieprawidlowy format numeru telefonu. Uzyj samych cyfr, z kodem kraju (np. 5511999998888). |
404 | Instancja nie znaleziona lub kontakt nie znaleziony. |
429 | Przekroczono limit zapytan. Zobacz Limity zapytan. |
