Contacts

Contacts API आपको WhatsApp पर phone numbers verify करने, contact जानकारी प्राप्त करने, और profile pictures fetch करने की सुविधा देता है। यह messages भेजने से पहले numbers validate करने और अपने contact data को enrich करने के लिए विशेष रूप से उपयोगी है। सभी contact endpoints एक specific instance से जुड़े हैं:

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

Number मौजूद है या नहीं जांचें

Message भेजने से पहले verify करें कि कोई phone number WhatsApp पर registered है या नहीं। यह विफल deliveries और बर्बाद API calls को रोकता है।

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

Response (number मौजूद है):

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

Response (number मौजूद नहीं है):

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

Messages भेजने से पहले numbers validate करने के लिए इस endpoint का उपयोग करें। यह message quota बचाता है और message.failed webhook events को रोकता है।

सभी Contacts प्राप्त करें

Connected WhatsApp account की पूर्ण contact list प्राप्त करें।

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

Response:

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

Contact Fields

Field	विवरण
`id`	Contact का WhatsApp ID (phone number + `@s.whatsapp.net`)।
`name`	Phone की address book में save किया गया contact name। यदि save नहीं है तो `null` हो सकता है।
`short_name`	Address book से short name।
`push_name`	वह name जो contact ने WhatsApp पर अपने लिए set किया है।
`is_business`	क्या यह WhatsApp Business account है।

name field आपके phone की address book से आता है। यदि contact save नहीं है, तो केवल push_name (contact द्वारा स्वयं set किया गया) उपलब्ध होगा।

Contact की जानकारी प्राप्त करें

किसी specific contact की विस्तृत जानकारी प्राप्त करें।

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

Response:

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

Profile Picture प्राप्त करें

किसी contact की WhatsApp profile picture URL प्राप्त करें।

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

Response:

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

Profile picture URLs temporary हैं और कुछ समय बाद expire हो जाती हैं। उन्हें स्थायी रूप से store न करें — जरूरत पड़ने पर fresh URL fetch करें।

यदि contact ने कोई profile picture सेट नहीं किया है या उसने अपनी privacy settings में दृश्यता प्रतिबंधित की है, तो profile_picture_url null होगा:

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

सामान्य Patterns

भेजने से पहले Validate करें

अनावश्यक failures से बचने के लिए message भेजने से पहले हमेशा जांचें कि number WhatsApp पर मौजूद है या नहीं:

async function sendMessageSafely(instanceId, phone, text) {
  // Step 1: जांचें कि number 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: Confirmed chat_id का उपयोग करके message भेजें
  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();
}

Contact Directory बनाएं

सभी contacts fetch करें और उन्हें profile pictures से enrich करें:

async function buildContactDirectory(instanceId) {
  // सभी 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();

  // Profile pictures से enrich करें (rate limits से बचने के लिए delay के साथ batch)
  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,
    });

    // Rate limits का सम्मान करने के लिए छोटा delay
    await new Promise((r) => setTimeout(r, 200));
  }

  return enriched;
}

कई contacts के लिए profile pictures fetch करते समय, rate limits के भीतर रहने के लिए requests के बीच delay जोड़ें। ऊपर के उदाहरण में 200ms delay उपयोग किया गया है।

Endpoint Reference

Method	Endpoint	विवरण
`GET`	`/api/instances/{id}/contacts`	सभी contacts की सूची
`GET`	`/api/instances/{id}/contacts/check?phone={phone}`	जांचें कि number WhatsApp पर मौजूद है
`GET`	`/api/instances/{id}/contacts/{contactId}`	Contact की जानकारी प्राप्त करें
`GET`	`/api/instances/{id}/contacts/{contactId}/profile-picture`	Profile picture प्राप्त करें

Error Handling

Status Code	विवरण
`400`	अमान्य phone number format। केवल अंक उपयोग करें, country code के साथ (जैसे, `5511999998888`)।
`404`	Instance नहीं मिला या contact नहीं मिला।
`429`	Rate limit पार हो गई। Rate Limits देखें।

शुरुआत करें

गाइड

Contacts

Contacts

Number मौजूद है या नहीं जांचें

सभी Contacts प्राप्त करें

Contact Fields

Contact की जानकारी प्राप्त करें

Profile Picture प्राप्त करें

सामान्य Patterns

भेजने से पहले Validate करें

Contact Directory बनाएं

Endpoint Reference

Error Handling

​Contacts

​Number मौजूद है या नहीं जांचें

​सभी Contacts प्राप्त करें

​Contact Fields

​Contact की जानकारी प्राप्त करें

​Profile Picture प्राप्त करें

​सामान्य Patterns

​भेजने से पहले Validate करें

​Contact Directory बनाएं

​Endpoint Reference

​Error Handling

Contacts

Number मौजूद है या नहीं जांचें

सभी Contacts प्राप्त करें

Contact Fields

Contact की जानकारी प्राप्त करें

Profile Picture प्राप्त करें

सामान्य Patterns

भेजने से पहले Validate करें

Contact Directory बनाएं

Endpoint Reference

Error Handling