> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wappfy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts

> Messages भेजने से पहले contacts देखें, phone numbers verify करें, और profile pictures प्राप्त करें।

# 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 को रोकता है।

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.wappfy.io/api/instances/inst_abc123/contacts/check?phone=5511999998888" \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  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");
  }
  ```
</CodeGroup>

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

```json theme={null}
{
  "data": {
    "exists": true,
    "phone": "5511999998888",
    "chat_id": "5511999998888@s.whatsapp.net"
  }
}
```

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

```json theme={null}
{
  "data": {
    "exists": false,
    "phone": "5511999998888",
    "chat_id": null
  }
}
```

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

***

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

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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.wappfy.io/api/instances/inst_abc123/contacts \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  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}`);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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 है।                                                        |

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

***

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

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

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.wappfy.io/api/instances/inst_abc123/contacts/5511999998888@s.whatsapp.net" \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  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}`);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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 प्राप्त करें।

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.wappfy.io/api/instances/inst_abc123/contacts/5511999998888@s.whatsapp.net/profile-picture" \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  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");
  }
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "profile_picture_url": "https://pps.whatsapp.net/v/t61.24694-24/..."
  }
}
```

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

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

```json theme={null}
{
  "data": {
    "profile_picture_url": null
  }
}
```

***

## सामान्य Patterns

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

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

```javascript theme={null}
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 करें:

```javascript theme={null}
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;
}
```

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

***

## 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](/hi/rate-limits) देखें।                                   |