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

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

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

contact_cards एक array है। हर कार्ड को एक 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-प्रबंधित नहीं।

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

{
  "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" के रूप में खुलने वाला संदेश फ़ीचर होने से पहले एक स्पैम वेक्टर है। बाद में सीमा बढ़ाना एक additive बदलाव होगा, तो पूछें कि क्या आप जो बना रहे हैं उसके लिए पाँच कम हैं।

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

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

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

जन्मदिन एक वास्तविक तारीख होनी चाहिए। 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 webhook
• WhatsApp मैसेज भेजना: रिक्वेस्ट एनवेलप, 202 मॉडल, और सुरक्षित फिर से प्रयास