WhatsApp contact cards प्राप्त करना

contact_cards एकमात्र ऐसा arm है जो दोनों दिशाओं में एक ही field रखता है। कोई contact अपनी address book से card शेयर कर सकता है, और आपके भेजे गए contact info request पर टैप भी यहीं आता है, उसमें वह नंबर होता है जो उन्होंने बताना चुना।

एक inbound contact card में क्या होता है

contact_cards हमेशा एक array होता है, और origin बताता है कि card कैसे आया:

{
  "id": "wam_01kyg9v3timy1w7n0r4cbh9ukf",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "contact_cards": [
    {
      "origin": "contact_request",
      "phone_numbers": [{ "phone_number": "+14155550100", "type": "cell" }]
    }
  ],
  "created_at": "2026-08-25T09:27:45Z"
}

किसी card को अपने अनुरोध का जवाब मानने से पहले origin जाँचें। यही एकमात्र संकेत है जो दोनों को अलग करता है, और बिना अनुरोध के शेयर किए गए card में contact के बजाय पूरी तरह किसी तीसरे व्यक्ति का नाम हो सकता है। वैल्यू लिस्ट खुली है, इसलिए जो वैल्यू आप नहीं पहचानते उसे बाद में जोड़ा गया शेयरिंग का एक और तरीका मानें।

इस वर्कस्पेस ने जो card भेजा था वह वापस पढ़ने पर बिना किसी origin के आता है, और इसी तरह एक ही field पर outbound card को inbound card से अलग पहचाना जाता है।

टैप में क्या आता है, और शेयर किए गए card में क्या आता है

दोनों अलग-अलग मात्रा में विवरण लेकर आते हैं, और card पर कुछ भी अनिवार्य नहीं है: WhatsApp card में जो हिस्से मौजूद हैं वे भेजता है और बाकी छोड़ देता है, इसलिए केवल origin वाला card भी ड्रॉप होने के बजाय पहुँच जाता है।

{
  "contact_cards": [
    {
      "origin": "other",
      "vcard": "BEGIN:VCARD\nVERSION:3.0\nN:Johnson;Barbara;;;\nTEL;type=CELL:+16505551234\nEND:VCARD\n",
      "name": {
        "formatted_name": "Barbara J. Johnson",
        "first_name": "Barbara",
        "last_name": "Johnson"
      },
      "org": { "company": "Northside Plumbing" },
      "phone_numbers": [{ "phone_number": "+16505551234", "type": "cell" }]
    }
  ]
}

दो fields को पार्स करते समय सावधानी चाहिए। phone_number को जहाँ पार्स किया जा सके वहाँ E.164 में सामान्यीकृत किया जाता है, और जहाँ न हो सके वहाँ contact के डिवाइस ने जैसा स्टोर किया ठीक वैसे ही पास किया जाता है; extension भी उनमें शामिल है, इसलिए E.164 मानने के बजाय सुरक्षित ढंग से पार्स करें। birthday उस डिवाइस से बिना सत्यापन के आता है और YYYY-MM-DD आकार में टेक्स्ट के रूप में पास होता है, date के रूप में टाइप नहीं, इसलिए यह न मानें कि यह पार्स होगा। प्राप्त card पर type लेबल lowercase होता है, और WhatsApp इसके लिए कोई शब्दावली परिभाषित नहीं करता, इसलिए CELL पर switch करने के बजाय case-insensitively मैच करें।

contact द्वारा बताया गया फ़ोन नंबर

जिस contact ने WhatsApp username अपनाया है वह from पर बिना फ़ोन नंबर के business-scoped user ID से आप तक पहुँचता है। contact info request से आप नंबर माँगते हैं, और यह arm वह जगह है जहाँ जवाब आता है, origin: "contact_request" के साथ और नंबर phone_numbers में।

वे जो नंबर बताते हैं वह ज़रूरी नहीं कि वही हो जिससे वे चैट करते हैं: Meta चेतावनी देता है कि किसी user का identifier और फ़ोन नंबर हमेशा मेल नहीं खा सकते, इसलिए बताए गए नंबर को from पर identity ओवरराइट करने के बजाय अलग तथ्य के रूप में स्टोर करें।

webhook पेलोड

whatsapp.received event envelope पर contact_cards array रखता है:

{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:27:45.019Z",
  "data": {
    "whatsapp_id": "wam_01kyg9v3timy1w7n0r4cbh9ukf",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100", "bsuid": "US.13491208655302741918" },
    "to": { "phone_number": "+13124495569" },
    "contact_cards": [
      {
        "origin": "contact_request",
        "phone_numbers": [{ "phone_number": "+14155550100", "type": "cell" }]
      }
    ],
    "tags": null,
    "metadata": null
  }
}

ध्यान देने योग्य बातें

• अस्वीकृत अनुरोध से कुछ नहीं आता। WhatsApp contact को एक share sheet दिखाता है, और उसे dismiss करने पर न कोई संदेश जाता है और न कोई webhook फ़ायर होता है, इसलिए नंबर की प्रतीक्षा कर रहे flow को decline event की जगह अपना timeout रखना चाहिए।
• दो लंबित अनुरोध अलग नहीं किए जा सकते। contact info request का जवाब देने वाले card में कोई in_reply_to_message_id नहीं होता, इसलिए पहले का जवाब आने से पहले भेजा गया दूसरा अनुरोध अपने जवाब से नहीं जोड़ा जा सकता।
• array में कई cards हो सकते हैं। एक संदेश में कई cards शेयर करने वाला contact कई entries भरता है, हर एक का अपना origin होता है।
• card वह contact data है जो आपने एकत्र नहीं किया। इसमें किसी तीसरे व्यक्ति का नाम, नंबर और जन्मतिथि हो सकती है, इसलिए इसे स्टोर करने से पहले वही retention और सहमति नियम लागू करें जो आप किसी भी अन्य व्यक्तिगत डेटा पर करते हैं।

अगले कदम

• रिसीविंग कैसे काम करती है: inbound envelope, media fetching, और whatsapp.received webhook
• WhatsApp contact cards: इसी arm का send पक्ष
• Business-scoped user IDs: contact बिना फ़ोन नंबर के क्यों आता है, और अनुरोध बातचीत में कैसे फ़िट होता है
• WhatsApp contact info requests: वह बटन जो नंबर माँगता है