WhatsApp संदेश भेजना

यह गाइड भेजने वाले एंडपॉइंट POST /v1/whatsapp/messages के बारे में है। आप एक JSON पेलोड बनाते हैं, जिसमें एक प्राप्तकर्ता और ठीक एक प्रकार की सामग्री होती है: पहले से स्वीकृत टेम्पलेट, या एक सेवा संदेश जिसमें टेक्स्ट, छवि, वीडियो, ऑडियो, स्टिकर, दस्तावेज़, स्थान, संपर्क कार्ड या टैप करने लायक कोई तत्व हो। Bird एक संदेश ID के साथ 202 Accepted लौटाता है और संदेश असिंक्रोनस रूप से पहुँचाता है। आप इन दोनों में से कौन-सा भेज सकते हैं, यह ग्राहक सेवा विंडो पर निर्भर करता है। हर अनुरोध एक प्राप्तकर्ता को एक संदेश भेजता है, और कोई बैच एंडपॉइंट नहीं है।

सबसे छोटा अनुरोध

सबसे छोटे मान्य पेलोड में एक to प्राप्तकर्ता और अपने slug के साथ एक template होता है। कोई खास भाषा चाहिए तो language जोड़ें; इसे छोड़ने पर टेम्पलेट की डिफ़ॉल्ट भाषा भेजी जाती है। टेम्पलेट जो वेरिएबल घोषित करता है, उन्हें parameters से भरें।

curl कॉल में US होस्ट दिया गया है; अगर आपकी कुंजी bk_eu1_ से शुरू होती है, तो इसकी जगह https://eu1.platform.bird.com को कॉल करें। SDK आपकी कुंजी से क्षेत्र पढ़ लेते हैं, इसलिए उनमें होस्ट सेट नहीं किया जाता।

const msg = await bird.whatsapp.send({
  to: "+15551234567",
  template: {
    slug: "bird_otp",
    parameters: { code: "123456" },
  },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+15551234567",
    template="bird_otp",
    language="en",
    parameters={"code": "123456"},
)
print(msg.id, msg.status)

msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
	To:         "+15551234567",
	Template:   "bird_otp",
	Language:   "en",
	Parameters: map[string]any{"code": "123456"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_otp',
    language: 'en',
    parameters: ['code' => '123456'],
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --language en \
  --parameters '{"code":"123456"}' \
  --template bird_otp \
  --to +15551234567

curl -X POST "https://{region}.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "template": {
      "slug": "bird_otp",
      "language": "en",
      "parameters": {
        "code": "123456"
      }
    }
  }'

ग्राहक सेवा विंडो

आप दोनों में से कौन-सा भेज सकते हैं, यह एक ही स्थिति पर निर्भर करता है: ग्राहक सेवा विंडो खुली है या नहीं।

संपर्क आपके व्यावसायिक नंबर पर संदेश भेजकर या कॉल करके विंडो खोलता है। यह 24 घंटे खुली रहती है, और हर बार उनके नए संदेश पर फिर से शुरू हो जाती है। विंडो खुली रहने तक आप सेवा संदेश भेज सकते हैं, यानी कोई भी मुक्त सामग्री: टेक्स्ट, छवि, वीडियो, ऑडियो, स्टिकर, दस्तावेज़, स्थान, संपर्क कार्ड या इंटरैक्टिव संदेश। विंडो बंद होने के बाद उन तक केवल पहले से स्वीकृत टेम्पलेट पहुँचता है, और उस पर उनका जवाब विंडो को फिर से खोल देता है।

Bird आपके लिए विंडो पर नज़र रखता है। इसलिए बंद विंडो में भेजा गया सेवा संदेश कुछ भी बनाए जाने या शुल्क लगने से पहले ही अस्वीकार हो जाता है: अनुरोध 422 E15044 WhatsAppServiceWindowClosed लौटाता है। यह जाँच पूरी तरह गारंटीशुदा नहीं है और विफल होने पर अनुरोध को आगे जाने देती है। इसलिए 202 इस बात का प्रमाण नहीं है कि भेजते समय विंडो सचमुच खुली थी। अगर स्वीकार करने और भेजने के बीच विंडो बंद हो जाए, तो संदेश असिंक्रोनस रूप से विफल होता है, और संदेश के last_error पर service_window_expired दिखता है।

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

पेलोड तैयार करना

प्राप्तकर्ता

to एक गंतव्य बताता है, जो फ़ोन नंबर, बिज़नेस-स्कोप्ड यूज़र आईडी या ग्रुप आईडी के रूप में दिया जाता है। फ़ोन नंबर E.164 फ़ॉर्मैट में होता है: शुरू में +, फिर देश कोड और सब्सक्राइबर नंबर, जैसे +14155550100। हम नंबर की जाँच करते हैं, इसलिए जो मान असली, डायल किया जा सकने वाला नंबर नहीं हो सकता (गलत लंबाई, अनअसाइन्ड प्रीफ़िक्स), उसे कोई शुल्क लगने से पहले 422 WhatsAppInvalidRecipient के साथ अस्वीकार कर दिया जाता है। प्राप्तकर्ताओं की कोई ऐरे या बैच सेंड नहीं है, इसलिए जो लोग एक ग्रुप में नहीं हैं, उन तक पहुँचने के लिए हर प्राप्तकर्ता के लिए एक कॉल करनी होती है।

US.13491208655302741918 जैसी बिज़नेस-स्कोप्ड यूज़र आईडी उस संपर्क को संबोधित करती है जिसका फ़ोन नंबर आपके पास नहीं है। इसी तरह आप उस संपर्क को जवाब देते हैं जिसने बिना नंबर बताए आपसे संपर्क किया। दो बातें बदलती हैं: भेजने वाला नंबर उसी बिज़नेस पोर्टफ़ोलियो का होना चाहिए जिससे आईडी जुड़ी है, और वन-टाइम-पासकोड टेम्पलेट के लिए फ़ोन नंबर चाहिए। Bird द्वारा प्रबंधित ऐसा टेम्पलेट स्वीकार करते समय ही 422 WhatsAppRecipientNotSupportedForTemplate के साथ अस्वीकार हो जाता है। आपके वर्कस्पेस द्वारा बनाया गया ऑथेंटिकेशन टेम्पलेट स्वीकार होता है और फिर विफल हो जाता है, क्योंकि Meta को इसके लिए फ़ोन नंबर चाहिए।

to एक और रूप भी लेता है: wag_01krdgeqcxet5s7t44vh8rt9mg जैसी WhatsApp ग्रुप आईडी, जो उस ग्रुप चैट के हर सदस्य को संदेश भेजती है। ग्रुप सेंड में from नहीं दिया जाता और डिलीवरी एक प्राप्तकर्ता के बजाय पूरे ग्रुप के स्तर पर रिपोर्ट होती है, इसलिए WhatsApp ग्रुप को भेजना इसे अलग पेज पर बताता है।

टेम्पलेट

template भेजे जाने वाले पहले से स्वीकृत टेम्पलेट का नाम बताता है:

• slug (आवश्यक): टेम्पलेट का स्लग, जैसे bird_order_confirmation। यह आपके कैटलॉग के किसी टेम्पलेट से मेल खाना चाहिए (छोटे अक्षर, अंक और अंडरस्कोर)।
• language: टेम्पलेट का भाषा टैग, जैसे en या pt-BR। टेम्पलेट की डिफ़ॉल्ट भाषा भेजने के लिए इसे छोड़ दें। ऐसी भाषा बताने पर जो टेम्पलेट में नहीं है, 422 लौटता है जिसमें उपलब्ध भाषाएँ सूचीबद्ध होती हैं। स्वीकृत संदेश में तय की गई भाषा वापस दिखाई जाती है।
• parameters: टेम्पलेट के वेरिएबल भरने वाले मान, नाम के आधार पर कुंजियों वाले एक ऑब्जेक्ट के रूप में (कंपोनेंट और पैरामीटर देखें)। जिस टेम्पलेट में वेरिएबल नहीं हैं, उसके लिए इसे छोड़ दें।
• components: parameters के बजाय यही मान Meta के कंपोनेंट स्वरूप में। कुछ टेम्पलेट केवल यही रूप स्वीकार करते हैं।

अपने टेम्पलेट, उनकी भाषाएँ और हर एक का रेंडर किया गया पूर्वावलोकन टेम्पलेट पेज पर देखें।

कंपोनेंट और पैरामीटर

टेम्पलेट में वेरिएबल होते हैं, जो नाम वाले ({{ref}}, {{amount}}) या क्रमांक वाले ({{1}}, {{2}}) होते हैं। इन्हें parameters के ज़रिए एक ऑब्जेक्ट में भरें। टेम्पलेट संस्करण का variables उन कुंजियों की सूची देता है जिन्हें वह स्वीकार करता है, और वैकल्पिक कुंजियों को चिह्नित करता है। हर कुंजी इनमें से एक होती है:

• नाम वाले वेरिएबल का अपना नाम, जैसे order_id
• क्रमांक वाले वेरिएबल का क्रमांक, जैसे 1
• मीडिया या लोकेशन हेडर के लिए header_url, header_filename या header_location, और कैरोसेल कार्ड के हेडर के लिए header_url_1, header_url_2 आदि
• URL बटन के क्रमांक वाले प्रत्यय के लिए button_url, और कैरोसेल कार्ड के बटन के लिए button_url_1, button_url_2 आदि। नाम वाला प्रत्यय अपना नाम लेता है।
• ऑथेंटिकेशन टेम्पलेट के कोड के लिए, और कोड कॉपी करने वाले बटन के मान के लिए code
• ऐसा इनपुट जिसे भाषा के पैरामीटर बाइंडिंग पढ़ते हैं

हर मान एक स्ट्रिंग, संख्या या बूलियन होता है। header_location एक ऑब्जेक्ट लेता है जिसमें latitude और longitude होते हैं। अगर आप मीडिया हेडर छोड़ देते हैं, तो टेम्पलेट का स्वीकृत नमूना भेजा जाता है। Meta से आयात किए गए टेम्पलेट में कोई नमूना नहीं होता, इसलिए उसके लिए मीडिया हेडर की कुंजी देनी होती है। जिन कुंजियों का भाषा उपयोग नहीं करती, उन्हें अनदेखा किया जाता है।

{
  "to": "+15551234567",
  "from": "+13124495648",
  "template": {
    "slug": "order_update",
    "language": "en",
    "parameters": { "order_id": "A-4192", "first_name": "Ava" }
  }
}

CLI में ऑब्जेक्ट को --parameters के साथ पास करें:

bird whatsapp send --to +15551234567 --from +13124495648 \
  --template order_update --language en \
  --parameters '{"order_id":"A-4192","first_name":"Ava"}'

जिस ऑथेंटिकेशन टेम्पलेट का बॉडी {{1}} is your verification code है और जिसका बटन कोड कॉपी करता है, वह कोड को एक बार code के रूप में लेता है। Bird उसी कोड से बॉडी और बटन दोनों भरता है:

{
  "parameters": { "code": "481920" }
}

जिस भाषा के बाइंडिंग संपर्क का डेटा पढ़ते हैं, जैसे bird.contact.first_name, उसे एकल संदेश के रूप में नहीं भेजा जा सकता और वह E15091 लौटाती है। इसके बजाय उसे ब्रॉडकास्ट में भेजें, जहाँ हर प्राप्तकर्ता का संपर्क डेटा उसे भरता है। अगर किसी प्राप्तकर्ता के संपर्क डेटा से कोई ज़रूरी मान खाली रह जाता है, तो ब्रॉडकास्ट उस प्राप्तकर्ता को छोड़ देता है। parameters या components में से एक ही भेजें, दोनों नहीं। कुछ टेम्पलेट केवल parameters स्वीकार करते हैं: ऐसा टेम्पलेट जिसकी भाषा पैरामीटर बाइंडिंग से अपने मान निकालती है, और ऐसा टेम्पलेट जिसके कैरोसेल कार्ड या बटन URL में नाम वाले वेरिएबल हों।

कुछ टेम्पलेट केवल components स्वीकार करते हैं, क्योंकि एक कुंजी उनके स्लॉट को अलग-अलग नहीं पहचान सकती। ऐसा तब होता है जब कोई टेम्पलेट एक से अधिक ब्लॉक में {{1}} को क्रमांकित करता है, जैसे हेडर और बॉडी में। ऐसा तब भी होता है जब एक ब्लॉक में क्रमांकित सफ़िक्स वाले दो url बटन हों, या किसी क्रमांकित url बटन के साथ {{button_url}} वेरिएबल हो। ऐसे टेम्पलेट को parameters के साथ भेजने पर 422 लौटता है।

कंपोनेंट के अनुसार टेम्पलेट भरें। components, parameters का विकल्प है, और उस टेम्पलेट के लिए एकमात्र तरीका है जिसे एक कुंजी से संबोधित नहीं किया जा सकता। हर कंपोनेंट एक type (header, body, button या carousel) और एक parameters ऐरे बताता है। carousel इसके बजाय एक cards ऐरे लेता है, जिसमें हर स्वीकृत कार्ड के लिए एक प्रविष्टि होती है, स्वीकृति के क्रम में। हर कार्ड में header, body और button प्रविष्टियों वाला अपना components ऐरे होता है। हर पैरामीटर अपना type (text, image, video, gif, document या location) बताता है और उससे मेल खाता फ़ील्ड रखता है: text के लिए सादी स्ट्रिंग, image/video/gif/document के लिए सार्वजनिक https url, और location के लिए मानचित्र पर एक बिंदु। नामित पैरामीटर वाले टेम्पलेट में हर पैरामीटर पर name आवश्यक है, जो टेम्पलेट द्वारा घोषित नामों से ठीक मेल खाए (फ़ील्ड संदर्भ देखें)। स्थितिगत टेम्पलेट name को छोड़ देता है और अपने मान {{n}} क्रम में लेता है, इसलिए पहला पैरामीटर {{1}} को भरता है। दोनों ही स्थितियों में, जो पैरामीटर टेम्पलेट की घोषणा से मेल नहीं खाते, वे 422 WhatsAppTemplateParameterMismatch लौटाते हैं। Bird-प्रबंधित टेम्पलेट पर header कंपोनेंट हटा दिया जाता है, क्योंकि कोई भी Bird-प्रबंधित टेम्पलेट हेडर वेरिएबल घोषित नहीं करता, लेकिन आपके वर्कस्पेस द्वारा बनाए गए टेम्पलेट पर इसे आगे भेजा जाता है, और इसी तरह मीडिया-हेडर वाले यूटिलिटी या मार्केटिंग टेम्पलेट को अपनी छवि मिलती है।

वही सत्यापन कोड टेम्पलेट कोड को बॉडी पैरामीटर और बटन पैरामीटर दोनों के रूप में, स्थितिगत रूप से लेता है (name के बिना):

{
  "components": [
    { "type": "body", "parameters": [{ "type": "text", "text": "481920" }] },
    { "type": "button", "parameters": [{ "type": "text", "text": "481920" }] }
  ]
}

श्रेणी और प्रेषक

टेम्पलेट की श्रेणी (authentication, utility या marketing) तय करती है कि WhatsApp संदेश को कैसे संभालता है, और गंतव्य देश के साथ मिलकर यह भी कि उसकी लागत कितनी है।

प्रेषक का स्वामी कौन है, इससे तय होता है कि आपको उसे बताना है या नहीं:

• Bird-प्रबंधित टेम्पलेट (जिसका स्लग bird_ से शुरू होता है) उस नंबर से भेजा जाता है जिसे Bird उस श्रेणी के लिए रखता है, इसलिए from न दें। इसे सेट करने पर 422 WhatsAppSenderNotAllowed लौटता है।
• बाकी सभी संदेश अपना प्रेषक from में बताते हैं: किसी भी प्रकार का सर्विस संदेश, और आपके वर्कस्पेस द्वारा बनाया गया कोई भी टेम्पलेट। नंबर आपके वर्कस्पेस के स्वामित्व वाला होना चाहिए। इसे छोड़ने पर 422 WhatsAppSenderRequired लौटता है, और ऐसा नंबर जिससे वर्कस्पेस भेज नहीं सकता, 422 WhatsAppSenderNotFound लौटाता है। आपका बनाया टेम्पलेट भी उसी WhatsApp Business Account पर होना चाहिए जिस पर नंबर है, अन्यथा भेजने पर 422 WhatsAppSenderWABAMismatch लौटता है।

फ़ोन नंबर सेटअप में दोनों प्रकार के नंबर और अपना नंबर जोड़ने का तरीका बताया गया है।

सर्विस संदेश

template के बजाय, text, image, video, audio, sticker, document, location, contact_cards या interactive में से ठीक एक भेजें। ये नौों सर्विस संदेश हैं, इसलिए इनके लिए खुली ग्राहक सेवा विंडो आवश्यक है। इनमें से हर एक के लिए from भी आवश्यक है, जो आपके वर्कस्पेस के स्वामित्व वाला नंबर हो; Bird के प्रबंधित नंबर इन्हें नहीं भेज सकते।

• text: { "body": "..." }, अधिकतम 4,096 वर्ण। body में पहले URL का लिंक प्रीव्यू दिखाने के लिए "preview_url": true जोड़ें।
• image, video, audio, sticker, document: हर एक एक सार्वजनिक https URL लेता है, जिसे WhatsApp भेजते समय प्राप्त करता है (url), इसलिए साइन किया गया URL भेजने की प्रक्रिया पूरी होने तक मान्य रहना चाहिए। http URL सीधे अस्वीकार कर दिया जाता है। फ़ाइल WhatsApp स्वयं प्राप्त करता है, इसलिए ऐसा URL जिस तक वह पहुँच नहीं पाता, असमर्थित प्रकार देने वाला URL, या अपने प्रकार की आकार सीमा से बड़ी फ़ाइल पहले स्वीकार होती है और फिर विफल हो जाती है। तब संदेश के last_error पर media_rejected आता है और description में WhatsApp का अपना कारण होता है। image, video और document एक वैकल्पिक caption भी लेते हैं; document एक वैकल्पिक filename भी लेता है; audio वॉइस नोट के रूप में दिखाने के लिए एक वैकल्पिक voice फ़्लैग लेता है।
• location: { "latitude": ..., "longitude": ... } (दोनों आवश्यक, दशमलव डिग्री में) और साथ में वैकल्पिक name और address।
• contact_cards: एक संदेश में साझा किए गए अधिकतम पाँच संपर्कों की ऐरे। हर कार्ड के name में formatted_name और कम से कम एक अन्य भाग (first_name, last_name, middle_name, prefix या suffix) होना चाहिए; phone_numbers, emails, urls और addresses में से हर एक अधिकतम दस प्रविष्टियाँ लेता है, और org तथा birthday (YYYY-MM-DD के रूप में) वैकल्पिक हैं। E.164 में दिया गया phone_number उस कार्ड पर एक बटन जोड़ता है, जो उस नंबर के साथ चैट खोलता है।
• interactive: मुख्य टेक्स्ट और साथ में टैप करने लायक कुछ, छह प्रकारों में से एक में: जवाब बटन, सूची मेनू, लिंक बटन, मीडिया कैरोसेल, या एक अकेला बटन जो प्राप्तकर्ता से उसका स्थान या फ़ोन नंबर माँगता है। इंटरैक्टिव संदेश में हर प्रकार की वायर संरचना, टैप से बनने वाले जवाब और सीमाएँ बताई गई हैं।

{
  "to": "+16505551234",
  "from": "+13124495648",
  "text": { "body": "Your order shipped: https://example.com/track/A1B2C3", "preview_url": true }
}

जिस अनुरोध में कोई सामग्री नहीं है, या एक से अधिक प्रकार की सामग्री है, उसे 422 के साथ अस्वीकार कर दिया जाता है।

किसी संदेश को उद्धृत करना

अपने संदेश को किसी WhatsApp संदेश के जवाब के रूप में भेजने के लिए in_reply_to_message_id को उस संदेश की ID पर सेट करें, ठीक वैसे ही जैसे WhatsApp ऐप में जवाब पर टैप करने से संदेश उद्धृत होता है। प्राप्तकर्ता को आपका संदेश दिखता है और उसके ऊपर उद्धृत संदेश होता है, और यह फ़ील्ड संदेश को हर बार पढ़ने पर वापस मिलती है।

यह उल्टी दिशा में भी काम करता है: जिस इनबाउंड संदेश को WhatsApp जवाब के रूप में चिह्नित करता है, उसकी इसी फ़ील्ड में उद्धृत संदेश की ID होती है, और इसी से आप जानते हैं कि जवाब आपके किस संदेश का है। जिस इनबाउंड संदेश को WhatsApp चिह्नित नहीं करता, उसमें कोई ID नहीं होती, और पहचान कभी-कभी चूक भी सकती है। भरोसेमंद मिलान के लिए, स्पष्ट इंटरैक्टिव जवाब पहचानकर्ताओं को अपने एप्लिकेशन में सहेजी गई बातचीत या कार्य की स्थिति के साथ इस्तेमाल करें। आउटगोइंग metadata आउटगोइंग रिकॉर्ड पर ही रहता है और जवाब पर अपने आप कॉपी नहीं होता।

भेजना स्वीकार होने से पहले उद्धरण की पहचान की जाती है, इसलिए जो उद्धरण दिखाया नहीं जा सकता, उससे अनुरोध ही विफल हो जाता है और न कुछ बनता है, न कोई शुल्क लगता है। ऐसी id जो इस वर्कस्पेस के किसी संदेश की नहीं है, या ऐसा संदेश जो उद्धृत किए जा सकने की 15 दिन की अवधि से पुराना है, 404 E15071 WhatsAppReferencedMessageNotFound लौटाता है। ऐसा संदेश जो कभी WhatsApp तक नहीं पहुँचा, या ऐसा संदेश जो इस भेजे जा रहे संदेश के to और from से अलग बातचीत का है, 422 E15072 WhatsAppMessageNotQuotable लौटाता है। अगर Bird उस स्टोर तक नहीं पहुँच पाता जो यह जाँच करता है, तो भेजने का अनुरोध 503 E15073 WhatsAppMessageLookupUnavailable लौटाता है, जिसके लिए फिर से प्रयास करना उचित है। उद्धरण टेम्पलेट वाले और मुक्त रूप वाले, दोनों तरह के संदेशों पर काम करता है।

{
  "to": "+16505551234",
  "from": "+13124495648",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "text": { "body": "Yes, that slot is still free." }
}

टैग और मेटाडेटा

तीन वैकल्पिक फ़ील्ड किसी संदेश के साथ आपका अपना संदर्भ जोड़ती हैं; तीनों API से पढ़ने पर वापस मिलती हैं और संदेश के हर वेबहुक इवेंट के साथ जाती हैं:

• tags: अधिकतम 20 संरचित { "name": ..., "value": ... } लेबल, कम विविधता वाले उन आयामों के लिए जिनसे आप फ़िल्टर और रिपोर्ट करते हैं (जैसे कोई अभियान या प्रयोग का कोई संस्करण)। नामों और मानों में ASCII अक्षर, अंक, अंडरस्कोर और हाइफ़न हो सकते हैं; नाम अधिकतम 32 वर्णों के होते हैं और एक संदेश में अद्वितीय होने चाहिए, मान अधिकतम 64 वर्णों के। संदेश सूची को टैग से फ़िल्टर करें (?tag=campaign या ?tag=campaign:launch-week), और Metrics पेज डिलीवरी को टैग के अनुसार बाँटकर दिखाता है।
• metadata: एक मनमाना JSON ऑब्जेक्ट, सीरियलाइज़ होने पर अधिकतम 2 KB, उस प्रति-भेजाई संदर्भ के लिए जिसे आपको फ़िल्टर आयाम के रूप में नहीं चाहिए (जैसे कोई आंतरिक ऑर्डर ID या सत्र संदर्भ)।
• reference: 1 से 255 अक्षरों की एक स्ट्रिंग, जिससे आप संदेश को खोजना चाहते हैं, जैसे कोई ऑर्डर या टिकट नंबर। संदेश सूची पर ?reference= इसका सटीक, केस-संवेदी मिलान करता है, और कई संदेशों में एक ही मान हो सकता है। इसे केवल तब सेट करें जब आपको इस पर खोजना हो, और बाकी कोई भी डेटा metadata में रखें।

{
  "tags": [{ "name": "campaign", "value": "order-confirmations" }],
  "metadata": { "order_id": "ord_8271" },
  "reference": "ord_8271"
}

फ़ील्ड संदर्भ

* language वैकल्पिक है; इसे छोड़ने पर टेम्पलेट की डिफ़ॉल्ट भाषा भेजी जाती है। † नामित पैरामीटर वाले टेम्पलेट में हर पैरामीटर पर name आवश्यक है। स्थितिगत टेम्पलेट में इसे छोड़ दें। देखें घटक और पैरामीटर। ** template या सेवा संदेश की कोई एक सामग्री फ़ील्ड (text, image, video, audio, sticker, document, location, contact_cards, interactive) में से ठीक एक भेजें; देखें सेवा संदेश।

एसिंक मॉडल: 202 का अर्थ

सफल भेजने पर संदेश ID और status: accepted के साथ 202 Accepted लौटता है। 202 तभी लौटता है जब भेजने का अनुरोध स्थायी रूप से स्वीकार हो चुका हो; स्वीकार किया गया अनुरोध कभी चुपचाप छोड़ा नहीं जाता। जिन गंभीर विफलताओं को आप ठीक कर सकते हैं, वे तुरंत 422 के साथ विफल होती हैं: अमान्य प्राप्तकर्ता, अज्ञात टेम्पलेट स्लग या भाषा, पैरामीटर का मेल न खाना, या बंद ग्राहक सेवा विंडो में भेजा गया सेवा संदेश (WhatsAppServiceWindowClosed)। वॉलेट में धनराशि न होना इनमें शामिल नहीं है: भेजने का अनुरोध स्वीकार होता है, और जब Bird शुल्क लेने का प्रयास करता है, तब संदेश insufficient_balance के साथ rejected स्थिति में समाप्त होता है। वास्तविक डिलीवरी एसिंक्रोनस रूप से होती है: जब हम संदेश WhatsApp को सौंपते हैं, तब वह sent स्थिति में जाता है, फिर रसीद आने पर अंतिम स्थिति (delivered या failed) में पहुँचता है। यह जानकारी इवेंट, वेबहुक और रीड एंडपॉइंट से मिलती है। पढ़े जाने की रसीद स्थिति के रूप में नहीं, बल्कि अलग से read_at टाइमस्टैम्प और whatsapp.read इवेंट के रूप में दिखाई जाती है।

गोपनीयता से जुड़ी एक बात: authentication श्रेणी के टेम्पलेट के लिए API भरे गए मान कभी नहीं लौटाता। ऐसे संदेशों के लिए 202 प्रतिक्रिया और बाद का हर रीड खाली components ऐरे लौटाता है, ताकि सत्यापन कोड फिर कभी सामने न आए।

सुरक्षित रूप से फिर से प्रयास करना

हर तार्किक भेजने के लिए एक अद्वितीय मान के साथ Idempotency-Key हेडर भेजें, तो फिर से प्रयास करना सुरक्षित हो जाता है। यदि आपका पहला अनुरोध सफल रहा पर आपको प्रतिक्रिया नहीं मिली (टाइमआउट, टूटा कनेक्शन), तो उसी कुंजी के साथ अनुरोध दोहराने पर डुप्लिकेट संदेश भेजा नहीं जाता और उसका शुल्क नहीं लगता; इसके बजाय मूल परिणाम लौटता है। दोहराई गई प्रतिक्रिया में Idempotency-Replay हेडर होता है। कुंजी के फ़ॉर्मेट और उसे रखे जाने की अवधि के लिए आइडेम्पोटेंसी देखें।

जवाब प्राप्त करना

आने वाले संदेश उसी रिसोर्स पर आते हैं जिस पर भेजे गए संदेश होते हैं, और उनमें से हर संदेश सेवा विंडो को रीसेट करता है। WhatsApp संदेश प्राप्त करना में API के ज़रिए उन्हें पढ़ना, संपर्क द्वारा भेजा गया मीडिया प्राप्त करना और whatsapp.received वेबहुक शामिल हैं।

लागत और बिलिंग

WhatsApp की कीमत प्रति संदेश तय होती है, जो टेम्पलेट की श्रेणी और प्राप्तकर्ता के देश पर निर्भर करती है; WhatsApp मूल्य निर्धारण देखें। संदेश का शुल्क दो चरणों में, दो अलग-अलग समय पर लगता है, और संदेश का cost ऑब्जेक्ट दोनों की जानकारी देता है:

दोनों राशियाँ दशमलव स्ट्रिंग होती हैं और इनमें कर शामिल नहीं होता।

नोट: 30 सितंबर 2026 तक किसी सेवा संदेश पर Meta का कोई हिस्सा नहीं लगता, और खुली ग्राहक सेवा विंडो के भीतर डिलीवर हुए यूटिलिटी टेम्पलेट पर भी नहीं। 1 अक्टूबर 2026 से Meta दोनों के लिए शुल्क लेता है, सिवाय 72 घंटे की निःशुल्क एंट्री पॉइंट विंडो के भीतर, और हर बिज़नेस फ़ोन नंबर पर हर महीने 1,000 सेवा संदेश निःशुल्क रहते हैं: अक्टूबर 2026 के मूल्य परिवर्तन।

दोनों घटकों की कीमत अलग-अलग इनपुट पर तय होती है। Bird का शुल्क आपके भेजे गए टेम्पलेट की श्रेणी और प्राप्तकर्ता के देश पर आधारित होता है। देश फ़ोन नंबर के देश कोड से तय होता है, या बिज़नेस-स्कोप्ड यूज़र ID पर भेजे गए संदेश में उस ID के दो अक्षरों वाले उपसर्ग से। Meta का हिस्सा उस श्रेणी पर आधारित होता है जो Meta स्वयं संबंधित रसीद में बताता है, और यह टेम्पलेट की श्रेणी से अलग हो सकती है: जब Meta के गंतव्य, बिज़नेस-स्थान और पात्रता नियम लागू होते हैं, तब वह authentication-international बता सकता है। देखें WhatsApp authentication-international दरें।

cost में क्या दिखता है, यह इस पर निर्भर करता है कि संदेश कितना आगे पहुँचा है:

• 202 के समय, cost null होता है। अभी किसी चीज़ की कीमत तय नहीं हुई है।
• प्रोसेसिंग के बाद, transaction_amount सेट हो जाता है और amount उसके बराबर होता है। passthrough_amount null ही रहता है।
• संबंधित delivered या read रसीद आने के बाद, सफलतापूर्वक दर्ज हुआ Meta शुल्क passthrough_amount में भर जाता है, और amount दर्ज घटकों को दर्शाता है।

null घटक का अर्थ है कि उस प्रोजेक्शन में कोई राशि दर्ज नहीं है; इससे यह सिद्ध नहीं होता कि संदेश निःशुल्क था। जिस घटक की कीमत स्पष्ट रूप से शून्य तय हुई है, उसमें "0.00000" दिखता है।

दोनों शुल्कों के विफल होने का तरीका भी अलग है। Bird का शुल्क विफल होने पर भेजना रोक देता है: यदि 202 के बाद वॉलेट में भेजने लायक राशि न हो या रूट की कोई कीमत कॉन्फ़िगर न हो, तो संदेश rejected पर समाप्त होता है, त्रुटि कोड insufficient_balance या price_not_found के साथ, और कोई शुल्क नहीं लगता। rejected संदेश कभी WhatsApp तक नहीं पहुँचा, और यही इसे failed से अलग करता है। Meta का हिस्सा विफल होने पर भेजना नहीं रोकता: यदि रसीद आने पर वॉलेट में कमी हो या दर उपलब्ध न हो, तो शुल्क छोड़ दिया जाता है और संदेश की देखी गई स्थिति नहीं बदली जाती। दूसरे शुल्क के कारण आपकी डिलीवरी कभी नहीं रुकती।

जिस संदेश पर Bird ने शुल्क लगाया है, बाद में डिलीवरी विफल होने पर भी वह आउटबाउंड शुल्क बना रहता है। Meta शुल्क संबंधित delivered या read कॉलबैक से तब प्रोसेस होता है, जब Meta सामान्य मूल्य निर्धारण के साथ ऐसी श्रेणी और गंतव्य बताता है जिन्हें पहचाना जा सके। दोनों कॉलबैक रास्ते एक ही शुल्क पहचान का उपयोग करते हैं और बिलिंग सेवा के डुप्लिकेट-हटाने पर निर्भर रहते हैं। दोबारा आई रसीदों का मिलान बिलिंग रिकॉर्ड से करें, संदेश प्रोजेक्शन को स्थायी डेबिट रसीद न मानें। सेवा या निःशुल्क एंट्री मूल्य निर्धारण से Meta घटक शून्य हो सकता है; जो घटक तय नहीं हुआ है, वह इस बात का प्रमाण नहीं है कि संदेश निःशुल्क था।

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

WhatsApp इवेंट में लागत नहीं होती। किसी भी घटक को पढ़ने के लिए GET /v1/whatsapp/messages/{id} से संदेश को फिर से पढ़ें।

अगले कदम

• सेवा संदेश: ग्राहक सेवा विंडो के भीतर टेक्स्ट, मीडिया और इंटरैक्टिव सामग्री भेजें
• टेम्पलेट: कोई टेम्पलेट चुनें और उसके वेरिएबल भरें
• WhatsApp संदेश प्राप्त करना: जवाब पढ़ें और आने वाला मीडिया प्राप्त करें
• संदेश स्थिति वेबहुक: डिलीवरी और विफलता के अपडेट प्राप्त करें
• आइडेम्पोटेंसी: Idempotency-Key हेडर के साथ सुरक्षित रूप से फिर से प्रयास करें