Sign inGet started

WhatsApp मीडिया कैरोसेल

मीडिया कैरोसेल दो से दस कार्ड का एक सेट है जिन्हें प्राप्तकर्ता बगल में स्वाइप करके देखता है, हर एक का अपना इमेज या वीडियो, अपना छोटा टेक्स्ट, और अपने बटन होते हैं। इसका उपयोग कई आइटम एक साथ दिखाने के लिए करें, जैसे कुछ प्रोडक्ट, बजाय प्रति आइटम एक अलग मैसेज भेजने के।

कैरोसेल भेजें

interactive.type को carousel पर सेट करें, एक मैसेज-लेवल body_text और 2 से 10 एंट्री वाला एक cards ऐरे दें:
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  interactive: {
    type: "carousel",
    body_text: "Here are two of our latest arrivals, each under $25:",
    cards: [
      {
        header: { type: "image", url: "https://cdn.example.com/plants/blue-echeveria.jpeg" },
        buttons: [
          {
            type: "cta_url",
            cta_url: { text: "Buy now", url: "https://shop.example.com/blue-echeveria" },
          },
        ],
      },
      {
        header: { type: "image", url: "https://cdn.example.com/plants/zebra-haworthia.jpeg" },
        buttons: [
          {
            type: "cta_url",
            cta_url: { text: "Buy now", url: "https://shop.example.com/zebra-haworthia" },
          },
        ],
      },
    ],
  },
});
console.log(msg.id, msg.status);
from हर सर्विस मैसेज पर आवश्यक है: एक ऐसा नंबर जो आपके वर्कस्पेस का है, Bird-प्रबंधित नहीं। पूर्ण संरचना में कार्ड का अपना टेक्स्ट, दूसरा क्विक-रिप्लाई बटन, और पहले के मैसेज का उद्धरण जुड़ता है:
कोड उदाहरण
{
  "to": "+16505551234",
  "from": "+13124495648",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "interactive": {
    "type": "carousel",
    "body_text": "Here are two of our latest arrivals, each under $25:",
    "cards": [
      {
        "header": { "type": "image", "url": "https://cdn.example.com/plants/blue-echeveria.jpeg" },
        "body_text": "Blue Echeveria. Powdery blue leaves.",
        "buttons": [
          { "type": "quick_reply", "quick_reply": { "slug": "buy-echeveria", "text": "Buy" } },
          { "type": "quick_reply", "quick_reply": { "slug": "info-echeveria", "text": "Details" } }
        ]
      },
      {
        "header": { "type": "image", "url": "https://cdn.example.com/plants/zebra-haworthia.jpeg" },
        "body_text": "Zebra Haworthia. White stripes on deep green leaves.",
        "buttons": [
          { "type": "quick_reply", "quick_reply": { "slug": "buy-haworthia", "text": "Buy" } },
          { "type": "quick_reply", "quick_reply": { "slug": "info-haworthia", "text": "Details" } }
        ]
      }
    ]
  },
  "tags": [{ "name": "category", "value": "catalog" }],
  "metadata": { "order_id": "A-1" }
}
in_reply_to_message_id उसी वार्तालाप में पहले के मैसेज को उद्धृत करता है। रिज़ॉल्यूशन कैसे काम करता है और क्या छूट सकता है, इसके लिए हब का रिप्लाई सहसंबंधित करने के लिए मैसेज उद्धृत करना देखें।
कैरोसेल में कोई मैसेज-लेवल हेडर और कोई फ़ुटर नहीं होता: मैसेज का body_text कार्ड्स के ऊपर एकमात्र टेक्स्ट है। इस टाइप के कार्ड जिस शेयर्ड बटन शेप का उपयोग करते हैं, उसके लिए हब का बटन सेक्शन देखें।

कार्ड

हर कार्ड का अपना मीडिया हेडर, अपना छोटा टेक्स्ट, और अपने बटन होते हैं:
  • header हर कार्ड पर आवश्यक है, और यह केवल image या video हो सकता है: कोई टेक्स्ट और कोई डॉक्यूमेंट हेडर नहीं, अन्य इंटरैक्टिव टाइप्स के विपरीत।
  • body_text वैकल्पिक है। यह कार्ड के मीडिया के नीचे दिखता है, मैसेज बॉडी से छोटा सीमित है, और अधिकतम दो लाइन ब्रेक की अनुमति देता है।
  • buttons आवश्यक है: या तो एक cta_url बटन या तीन तक quick_reply बटन, एक ही कार्ड पर कभी मिक्स नहीं।
कार्ड cards ऐरे में जिस क्रम में दिखते हैं, उसी क्रम में बाएँ से दाएँ रेंडर होते हैं। कार्ड का कोई फ़ुटर और कोई अपना इंडेक्स फ़ील्ड नहीं होता; ऐरे में उसकी स्थिति ही कैरोसेल में उसकी स्थिति है।

हर कार्ड में समान बटन होते हैं

कैरोसेल में हर कार्ड में समान बटन टाइप, समान संख्या, और समान क्रम होने चाहिए। एक कैरोसेल जहाँ कार्ड 1 में एक cta_url बटन है और कार्ड 2 में दो quick_reply बटन हैं, अस्वीकार किया जाता है, और वह कैरोसेल भी जहाँ हर कार्ड में दो quick_reply बटन हैं लेकिन अलग क्रम में।
इसका कारण यह है कि WhatsApp मैसेज को कैसे रेंडर करता है: कैरोसेल एक शेयर्ड लेआउट वाला एक कार्ड व्यू है, स्वतंत्र रूप से लेआउट किए गए कार्ड्स का सेट नहीं। अलग बटन पंक्ति वाला कार्ड उस शेयर्ड लेआउट को तोड़ देगा, इसलिए WhatsApp हर कार्ड का मिलान आवश्यक करता है और Bird सेंड बनने या चार्ज होने से पहले इसे जाँचता है। मिसमैच होने पर E15059 लौटता है।
बटन लेबल एक अलग नियम है, और इसका दायरा अलग है: लेबल एक कार्ड के अंदर अद्वितीय होना चाहिए, पूरे कैरोसेल में नहीं। दसों कार्ड में से हर एक पर "Buy now" ठीक है; एक ही कार्ड पर "Buy now" दो बार होने पर E15056 लौटता है।

सीमाएँ

फ़ील्डसीमा
cards2 से 10 एंट्री
कार्ड headerहर कार्ड पर आवश्यक; केवल image या video
कार्ड header.urlआवश्यक, कोई अधिकतम लंबाई नहीं
कार्ड body_textवैकल्पिक, 1 से 160 अक्षर, अधिकतम 2 लाइन ब्रेक
कार्ड buttons1 से 3 एंट्री: एक cta_url, या तीन तक quick_reply, कभी मिक्स नहीं
बटन लेबल (quick_reply.text, cta_url.text)आवश्यक, 1 से 20 अक्षर, कार्ड के अंदर अद्वितीय
quick_reply.slugआवश्यक, 1 से 256 अक्षर
cta_url.urlआवश्यक, 1 से 2,000 अक्षर
मैसेज body_textआवश्यक, 1 से 1,024 अक्षर
मैसेज हेडर, फ़ुटरकैरोसेल पर अनुमति नहीं: कोई header नहीं, कोई footer_text नहीं
Bird प्रति कार्ड quick_reply बटन को तीन तक सीमित करता है। Meta स्वयं कोई संख्यात्मक सीमा नहीं बताता, केवल यह कि कार्ड या तो एक लिंक बटन लेता है या एक या अधिक रिप्लाई बटन, इसलिए यह सीलिंग Bird की अपनी है, WhatsApp की नहीं।

रिप्लाई पढ़ना

केवल quick_reply कार्ड बटन रिप्लाई उत्पन्न करता है। इस पर टैप एक अलग इनबाउंड मैसेज के रूप में आता है, जिसमें interactive_reply होता है:
कोड उदाहरण
{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "from": { "phone_number": "+16505551234" },
  "to": { "phone_number": "+13124495648" },
  "status": "received",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "interactive_reply": {
    "type": "button",
    "button": {
      "slug": "buy-echeveria",
      "text": "Buy"
    }
  },
  "created_at": "2026-08-25T09:04:11Z"
}
टैप किए गए बटन पर आपने जो slug सेट किया था, वह interactive_reply.button.slug पर हूबहू वापस आता है, वही शेप जो रिप्लाई-बटन टैप उत्पन्न करता है। आप यह रिप्लाई मैसेज लिस्ट या GET /v1/whatsapp/messages/{id} के माध्यम से देखते हैं; उस पूरे पथ के लिए हब का रिप्लाई पढ़ना देखें।
कार्ड पर cta_url बटन प्राप्तकर्ता के ब्राउज़र में लिंक खोलता है और कुछ वापस नहीं भेजता, ठीक एक स्टैंडअलोन लिंक बटन की तरह।

फ़्री-फ़ॉर्म कैरोसेल और टेम्पलेट कैरोसेल

यह पेज उस फ़्री-फ़ॉर्म कैरोसेल के बारे में है जो आप interactive.type: "carousel" के साथ इनलाइन भेजते हैं, जो केवल खुली कस्टमर सर्विस विंडो के अंदर डिलीवर होता है और Meta द्वारा कभी रिव्यू नहीं किया जाता। WhatsApp templates का अपना अलग कैरोसेल है: एक टेम्पलेट कंपोनेंट जो एक बार लिखा जाता है, अप्रूवल के लिए Meta को सबमिट किया जाता है, और किसी भी अन्य टेम्पलेट की तरह slug से भेजा जाता है, विंडो के बाहर भी। दोनों में शब्द "carousel" और Meta की 2-से-10 कार्ड रेंज समान है, और बस: अलग वायर शेप, अलग रिव्यू पथ, और टेम्पलेट कैरोसेल का कार्ड काउंट टेम्पलेट की अप्रूवल के समय तय होता है, प्रति सेंड चुने जाने के बजाय। अगर आप टेम्पलेट ब्राउज़ कर रहे हैं और वहाँ "carousel" दिखे, तो वह टेम्पलेट टाइप है, यह पेज नहीं।

सीमाएँ और एज केस

  • कस्टमर सर्विस विंडो खुली होनी चाहिए। कैरोसेल एक सर्विस मैसेज है, जो केवल खुली विंडो के अंदर डिलीवर होता है; हब की कस्टमर सर्विस विंडो देखें। विंडो जाँच fail-open है, इसलिए 202 इस बात का प्रमाण नहीं है कि सेंड जाते समय विंडो वास्तव में खुली थी।
  • from आपके वर्कस्पेस के स्वामित्व वाला नंबर होना चाहिए। इसे छोड़ देना, या ऐसा नंबर देना जो कनेक्टेड सेंडर नहीं है, सेंड बनने से पहले ही अस्वीकार कर दिया जाता है।
  • सेंड डिस्पैच होते समय कार्ड मीडिया सार्वजनिक रूप से पहुँचने योग्य होना चाहिए। Bird फ़ाइल को स्टोर या प्रॉक्सी नहीं करता: WhatsApp हर कार्ड का url सेंड के समय स्वयं फ़ेच करता है, इसलिए साइन किए गए URL की वैधता सेंड से अधिक होनी चाहिए।
  • जो कार्ड मीडिया URL WhatsApp फ़ेच नहीं कर सकता, वह स्वीकार किया जाता है, फिर असिंक्रोनस रूप से विफल होता है, और फिर भी चार्ज किया जाता है। Bird की रिक्वेस्ट वैलिडेशन केवल यह जाँचती है कि कार्ड का url एक सही-फ़ॉर्मेट URI है, यह नहीं कि WhatsApp इसे एक्सेस कर सकता है या यह https उपयोग करता है। बड़ी फ़ाइल, 404, अनरिज़ॉल्वेबल होस्ट, या गलत फ़ाइल टाइप सब स्वीकृति पर 202 के रूप में आते हैं, फिर whatsapp.accepted फिर whatsapp.sent फिर whatsapp.failed, मैसेज के last_error पर media_rejected के साथ और सेंड की लागत बिना रिफ़ंड पथ के पहले ही चार्ज हो चुकी होती है। भेजने से पहले हर कार्ड का URL टेस्ट करें, क्योंकि टूटा हुआ URL बाद में ही पकड़ में आता है।
  • हर कार्ड में समान बटन होने चाहिए। ऊपर हर कार्ड में समान बटन होते हैं देखें; यह एकमात्र कैरोसेल नियम है जो रिक्वेस्ट स्कीमा अकेले व्यक्त नहीं कर सकती, इसलिए इसे अलग से जाँचा जाता है और जेनेरिक वैलिडेशन त्रुटि के बजाय E15059 लौटता है।
  • कोई मैसेज-लेवल हेडर या फ़ुटर नहीं। कैरोसेल में कार्ड्स के ऊपर एकमात्र टेक्स्ट body_text है; जिस तरह अन्य टाइप footer_text का उपयोग करते हैं, वैसे छोटे प्रिंट के लिए कोई जगह नहीं है।
  • रिप्लाई में कोई कार्ड इंडेक्स नहीं होता। कार्ड का quick_reply टैप केवल {slug, text} रिपोर्ट करता है, रिप्लाई-बटन टैप जैसा ही शेप, जिसमें कोई फ़ील्ड यह नहीं बताती कि यह किस कार्ड से आया। अगर आपको जानना है कि कौन सा कार्ड टैप हुआ, तो हर बटन के slug में कार्ड एनकोड करें, जैसे buy-echeveria न कि सिर्फ buy
  • cta_url कार्ड बटन कोई इनबाउंड इवेंट उत्पन्न नहीं करता। अगर आपको जानना है कि कार्ड के साथ इंटरैक्शन हुआ, तो उस कार्ड पर quick_reply बटन उपयोग करें, या अपने डेस्टिनेशन URL पर क्लिक ट्रैक करें।
E15059 के अलावा, कैरोसेल के लिए एकमात्र विशिष्ट इंटरैक्टिव त्रुटि एक कार्ड पर दोहराए गए बटन लेबल के लिए E15056 है। जो उद्धरण रिज़ॉल्व नहीं होता वह कुछ भी बनने या चार्ज होने से पहले रिक्वेस्ट को विफल कर देता है: 404 E15071 जब id ऐसे मैसेज का नाम देती है जो इस वर्कस्पेस में नहीं है, 422 E15072 जब ऐसे मैसेज का नाम देती है जिसे उद्धृत नहीं किया जा सकता। किसी भी WhatsApp सेंड में आने वाली त्रुटियों के लिए, बंद विंडो, गायब या अमान्य सेंडर, या अमान्य प्राप्तकर्ता, हब के त्रुटियाँ और WhatsApp मैसेज भेजना देखें।

अगले कदम