Kontak
API Kontak memungkinkan Anda memverifikasi nomor telepon di WhatsApp, mengambil informasi kontak, dan mendapatkan foto profil. Ini sangat berguna untuk memvalidasi nomor sebelum mengirim pesan dan memperkaya data kontak Anda.
Semua endpoint kontak terikat pada instance tertentu:
/api/instances/{instanceId}/contacts/...
Memeriksa Keberadaan Nomor
Verifikasi apakah nomor telepon terdaftar di WhatsApp sebelum mengirim pesan. Ini mencegah pengiriman gagal dan panggilan API yang sia-sia.
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
}
}
Gunakan endpoint ini untuk memvalidasi nomor sebelum mengirim pesan. Ini menghemat kuota pesan dan mencegah event webhook message.failed.
Mendapatkan Semua Kontak
Ambil seluruh daftar kontak untuk akun WhatsApp yang terhubung.
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
}
]
}
Field Kontak
| Field | Deskripsi |
|---|
id | ID WhatsApp kontak (nomor telepon + @s.whatsapp.net). |
name | Nama kontak yang tersimpan di buku alamat ponsel. Bisa null jika tidak disimpan. |
short_name | Nama pendek dari buku alamat. |
push_name | Nama yang ditetapkan kontak untuk diri mereka sendiri di WhatsApp. |
is_business | Apakah ini adalah akun WhatsApp Business. |
Field name berasal dari buku alamat ponsel Anda. Jika kontak tidak disimpan, hanya push_name (ditetapkan oleh kontak itu sendiri) yang akan tersedia.
Mendapatkan Info Kontak
Ambil informasi detail tentang kontak tertentu.
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
}
}
Mendapatkan Foto Profil
Ambil URL foto profil WhatsApp kontak.
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/..."
}
}
URL foto profil bersifat sementara dan kedaluwarsa setelah beberapa waktu. Jangan menyimpannya secara permanen — ambil URL baru saat diperlukan.
profile_picture_url akan bernilai null:
{
"data": {
"profile_picture_url": null
}
}
Pola Umum
Validasi Sebelum Mengirim
Selalu periksa apakah nomor ada di WhatsApp sebelum mengirim pesan untuk menghindari kegagalan yang tidak perlu:
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();
}
Membangun Direktori Kontak
Ambil semua kontak dan perkaya dengan foto 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;
}
Saat mengambil foto profil untuk banyak kontak, tambahkan jeda antar permintaan agar tetap dalam batas laju. Contoh di atas menggunakan jeda 200ms.
Referensi Endpoint
| Method | Endpoint | Deskripsi |
|---|
GET | /api/instances/{id}/contacts | Melihat daftar semua kontak |
GET | /api/instances/{id}/contacts/check?phone={phone} | Memeriksa apakah nomor ada di WhatsApp |
GET | /api/instances/{id}/contacts/{contactId} | Mendapatkan info kontak |
GET | /api/instances/{id}/contacts/{contactId}/profile-picture | Mendapatkan foto profil |
Penanganan Error
| Kode Status | Deskripsi |
|---|
400 | Format nomor telepon tidak valid. Gunakan angka saja, dengan kode negara (misalnya, 5511999998888). |
404 | Instance tidak ditemukan atau kontak tidak ditemukan. |
429 | Batas laju terlampaui. Lihat Batas Laju. |
