WhatsApp संपर्क कार्ड

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

संपर्क कार्ड भेजें

contact_cards एक ऐरे है। हर कार्ड में एक name होना ज़रूरी है, और उस नाम में formatted_name के साथ कम से कम एक और भाग होना चाहिए:

const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  contact_cards: [
    {
      name: {
        formatted_name: "Barbara J. Johnson",
        first_name: "Barbara",
        last_name: "Johnson",
      },
      phone_numbers: [{ phone_number: "+16505559999", type: "Mobile" }],
    },
  ],
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+16505551234",
    from_="+13124495648",
    contact_cards=[
        {
            "name": {
                "formatted_name": "Barbara J. Johnson",
                "first_name": "Barbara",
                "last_name": "Johnson",
            },
            "phone_numbers": [{"phone_number": "+16505559999", "type": "Mobile"}],
        }
    ],
)
print(msg.id, msg.status)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
		To:   "+16505551234",
		From: "+13124495648",
		ContactCards: []bird.WhatsAppContactCardSend{{
			Name: bird.WhatsAppContactNameSend{
				FormattedName: "Barbara J. Johnson",
				FirstName:     bird.String("Barbara"),
				LastName:      bird.String("Johnson"),
			},
			PhoneNumbers: &[]bird.WhatsAppContactPhoneSend{{
				PhoneNumber: "+16505559999",
				Type:        bird.String("Mobile"),
			}},
		}},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$name = (new WhatsAppContactCardSendName())
    ->setFormattedName('Barbara J. Johnson')
    ->setFirstName('Barbara')
    ->setLastName('Johnson');
$phone = (new WhatsAppContactPhoneSend())
    ->setPhoneNumber('+16505559999')
    ->setType('Mobile');
$card = (new WhatsAppContactCardSend())
    ->setName($name)
    ->setPhoneNumbers([$phone]);
$message = $bird->whatsapp->send(
    to: '+16505551234',
    from: '+13124495648',
    contactCards: [$card],
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --to +16505551234 \
  --from +13124495648 \
  --contact-cards '[{"name":{"formatted_name":"Barbara J. Johnson","first_name":"Barbara","last_name":"Johnson"},"phone_numbers":[{"phone_number":"+16505559999","type":"Mobile"}]}]'

curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "to": "+16505551234",
      "from": "+13124495648",
      "contact_cards": [
        {
          "name": {
            "formatted_name": "Barbara J. Johnson",
            "first_name": "Barbara",
            "last_name": "Johnson"
          },
          "phone_numbers": [
            { "phone_number": "+16505559999", "type": "Mobile" }
          ]
        }
      ]
    }'

हर सेवा संदेश में from ज़रूरी है। यह ऐसा नंबर होना चाहिए जिसका स्वामित्व आपके वर्कस्पेस के पास हो, न कि Bird द्वारा प्रबंधित नंबर।

पूरी संरचना में नियोक्ता, जन्मदिन और संपर्क विवरण के बाकी ऐरे भी जुड़ते हैं:

{
  "to": "+16505551234",
  "from": "+13124495648",
  "contact_cards": [
    {
      "name": {
        "formatted_name": "Dr. Barbara J. Johnson Esq.",
        "prefix": "Dr.",
        "first_name": "Barbara",
        "middle_name": "Joana",
        "last_name": "Johnson",
        "suffix": "Esq."
      },
      "org": { "company": "Lucky Shrub", "department": "Legal", "title": "Lead Counsel" },
      "birthday": "1999-01-23",
      "phone_numbers": [
        { "phone_number": "+16505559999", "type": "Landline" },
        { "phone_number": "+19175559999", "type": "Mobile" }
      ],
      "emails": [{ "email": "bjohnson@example.com", "type": "Work" }],
      "urls": [{ "url": "https://example.com", "type": "Company" }],
      "addresses": [
        {
          "street": "1 Lucky Shrub Way",
          "city": "Menlo Park",
          "state": "CA",
          "zip": "94025",
          "country": "United States",
          "country_code": "US",
          "type": "Office"
        }
      ]
    }
  ]
}

हर type लेबल, चाहे वह फ़ोन, ईमेल, वेबसाइट या पते पर हो, आपके द्वारा लिखा गया मुक्त टेक्स्ट है। यह ठीक वैसा ही भेजा जाता है जैसा आपने लिखा, और प्राप्तकर्ता के प्रोफ़ाइल व्यू में मान के बगल में दिखता है। WhatsApp इनके लिए कोई तय शब्दावली परिभाषित नहीं करता, इसलिए Mobile, Landline, Pop-Up और Work (old) सभी समान रूप से मान्य हैं।

कार्ड को बटन कब मिलता है

अगर फ़ोन नंबर E.164 में लिखा है, यानी देश कोड और शुरुआती + के साथ, तो उस कार्ड को एक बटन मिलता है जो उस नंबर के साथ WhatsApp चैट खोलता है। जिस नंबर को Bird E.164 के रूप में नहीं पढ़ पाता, वह भी कार्ड पर ठीक वैसा ही दिखता है जैसा आपने लिखा, बस उसे बटन नहीं मिलता।

इसमें वह नंबर भी शामिल है जो शुरुआती + के बिना लिखा गया हो। Bird आपके लिए इसे नहीं जोड़ता। किसी एक देश के राष्ट्रीय फ़ॉर्मैट वाले नंबर में + जोड़ देने पर वह किसी दूसरे देश का मान्य नंबर बन सकता है, और तब बटन किसी अजनबी की ओर इशारा करेगा। अनुमान न लगाने से केवल एक बटन छूटता है, जबकि गलत अनुमान से प्राप्तकर्ता की चैट गलत व्यक्ति से हो जाती है।

जिस कार्ड में कोई फ़ोन नंबर नहीं होता, वह बिना चैट बटन के दिखता है और उसे केवल एड्रेस बुक में सहेजा जा सकता है।

सीमाएँ

पाँच कार्ड की सीमा Bird की है, और यह जानबूझकर WhatsApp द्वारा स्वीकार की जाने वाली संख्या से बहुत कम रखी गई है। WhatsApp का अपना प्रकाशित API विवरण पाँच बताता है, और उसका दस्तावेज़ उपयोगिता और नकारात्मक प्रतिक्रिया के कारणों से इससे कम कार्ड भेजने की सलाह देता है। जो संदेश "Contact 1 and 256 other contacts" के रूप में खुलता है, वह फ़ीचर से पहले स्पैम का ज़रिया बन जाता है। सीमा को बाद में बढ़ाना एक अतिरिक्त बदलाव होगा, इसलिए अगर आप जो बना रहे हैं उसके लिए पाँच कम पड़ते हैं, तो हमसे पूछें।

ऊपर दी गई हर लंबाई सीमा भी Bird की है। WhatsApp कोई ठोस सीमा लागू नहीं करता, और उसका क्लाइंट इसकी भरपाई नहीं करता। 500 वर्णों का type एक ही अक्षर की दस दोहराई गई पंक्तियों के रूप में दिखता है, और 4000 वर्णों का url बिना किसी सूचना के हटा दिया जाता है, जिससे प्रोफ़ाइल व्यू खाली रह जाता है। गलत फ़ील्ड का नाम बताने वाला 422 ऐसे कार्ड से बेहतर है जिसे प्राप्तकर्ता पढ़ ही न सके।

दो नियम जिन्हें स्कीमा व्यक्त नहीं कर सकता

नाम में दूसरा हिस्सा होना ज़रूरी है। केवल formatted_name होने पर अनुरोध 422 E15061 WhatsAppContactNameIncomplete के साथ अस्वीकार कर दिया जाता है, जो contact_cards.<n>.name का नाम बताता है। prefix, first_name, middle_name, last_name या suffix में से कोई भी एक इस शर्त को पूरा करता है, लेकिन खाली या केवल स्पेस वाला मान नहीं गिना जाता, और org भी इसकी भरपाई नहीं करता। यह WhatsApp की अपनी शर्त है, जो उसके रेफ़रेंस में कहीं दर्ज नहीं है। Bird इसे स्वीकार करते समय ही पकड़ लेता है, ताकि आपको एसिंक्रोनस विफलता के बजाय ऐसी त्रुटि मिले जिस पर आप कार्रवाई कर सकें।

जन्मदिन एक वास्तविक तारीख होना चाहिए। birthday का प्रारूप YYYY-MM-DD है। कोई भी दूसरा प्रारूप, और कैलेंडर में मौजूद न होने वाली कोई भी तारीख, जैसे 2026-02-30, 422 E15062 WhatsAppContactBirthdayInvalid के साथ अस्वीकार कर दी जाती है। WhatsApp स्वयं 2026-02-30 को स्वीकार करके प्राप्तकर्ता को दिखा देता है, जो आपके डेटा में बग जैसा लगता है।

भेजे गए कार्ड को वापस पढ़ना

आपका भेजा गया कार्ड उसी contact_cards फ़ील्ड में वापस पढ़ा जाता है जिसका उपयोग इनबाउंड कार्ड करता है, चाहे आप संदेश सूची से पढ़ें या GET /v1/whatsapp/messages/{id} से:

{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "outbound",
  "status": "delivered",
  "contact_cards": [
    {
      "name": { "formatted_name": "Barbara J. Johnson", "first_name": "Barbara" },
      "phone_numbers": [{ "phone_number": "+16505559999", "type": "Mobile" }]
    }
  ]
}

आपके भेजे गए कार्ड पर origin और vcard मौजूद नहीं होते: जब कोई संपर्क कार्ड साझा करता है, तब WhatsApp ये दोनों सेट करता है। आपका भेजा गया type लेबल ठीक वैसा ही वापस पढ़ा जाता है जैसा आपने लिखा था, जबकि प्राप्त कार्ड पर लेबल छोटे अक्षरों में बदल दिया जाता है। इनबाउंड पक्ष के लिए WhatsApp संपर्क कार्ड प्राप्त करना देखें।

विशेष स्थितियाँ

• ग्राहक सेवा विंडो खुली होनी चाहिए। संपर्क कार्ड भेजना एक सेवा संदेश है, जिसे केवल खुली विंडो के भीतर डिलीवर किया जा सकता है; हब की ग्राहक सेवा विंडो देखें।
• भेजने के लिए कोई wa_id नहीं है। WhatsApp कार्ड के संपर्क की पहचान एक अकाउंट ID से करता है; Bird इसे स्वीकार करने के बजाय हर E.164 phone_number से निकालता है। इसलिए कार्ड का बटन कभी भी उस पर छपे अंकों के अलावा किसी और नंबर पर नहीं ले जा सकता।
• vcard केवल पढ़ने के लिए है। जब कोई संपर्क कार्ड साझा करता है, तब WhatsApp इसे बनाता है। कार्ड को कच्चे vCard टेक्स्ट के रूप में भेजने का कोई तरीका नहीं है।
• कार्ड कोई संपर्क रिकॉर्ड नहीं है। कार्ड भेजने से विवरण एक संदेश में साझा होते हैं; आपके वर्कस्पेस में कुछ भी नहीं बनता। प्राप्तकर्ता का उसे सहेजना उसकी अपनी कार्रवाई है, जो आपको दिखाई नहीं देती।

अगले चरण

• WhatsApp सेवा संदेश: ग्राहक सेवा विंडो और वह मॉडल जो हर सेवा संदेश में समान है
• संपर्क जानकारी अनुरोध: अपना नंबर भेजने के बजाय किसी संपर्क से उसका नंबर माँगें
• WhatsApp संदेश प्राप्त करना: इनबाउंड संदेश, मीडिया और whatsapp.received वेबहुक
• WhatsApp संदेश भेजना: अनुरोध की संरचना, 202 मॉडल और सुरक्षित रूप से फिर से प्रयास करना