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

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

A few things we thought you’d love. Swipe to explore.

Considered details.

A closer look

Room to grow.

A closer look

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

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);

msg = client.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"}}],
            },
        ],
    },
)
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",
		Interactive: &bird.WhatsAppInteractiveSend{
			Type:     "carousel",
			BodyText: "Here are two of our latest arrivals, each under $25:",
			Cards: &[]bird.WhatsAppInteractiveCardSend{
				{
					Header:  bird.WhatsAppInteractiveCardHeaderSend{Type: "image", Url: "https://cdn.example.com/plants/blue-echeveria.jpeg"},
					Buttons: []bird.WhatsAppInteractiveButtonSend{{Type: "cta_url", CtaUrl: &bird.WhatsAppInteractiveCtaUrlSend{Text: "Buy now", Url: "https://shop.example.com/blue-echeveria"}}},
				},
				{
					Header:  bird.WhatsAppInteractiveCardHeaderSend{Type: "image", Url: "https://cdn.example.com/plants/zebra-haworthia.jpeg"},
					Buttons: []bird.WhatsAppInteractiveButtonSend{{Type: "cta_url", CtaUrl: &bird.WhatsAppInteractiveCtaUrlSend{Text: "Buy now", Url: "https://shop.example.com/zebra-haworthia"}}},
				},
			},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$interactive = (new WhatsAppMessageSendRequestInteractive())
    ->setType('carousel')
    ->setBodyText('Here are two of our latest arrivals, each under $25:')
    ->setCards([
        (new WhatsAppInteractiveCardSend())
            ->setHeader((new WhatsAppInteractiveCardSendHeader())->setType('image')->setUrl('https://cdn.example.com/plants/blue-echeveria.jpeg'))
            ->setButtons([
                (new WhatsAppInteractiveButtonSend())
                    ->setType('cta_url')
                    ->setCtaUrl((new WhatsAppInteractiveButtonSendCtaUrl())->setText('Buy now')->setUrl('https://shop.example.com/blue-echeveria')),
            ]),
        (new WhatsAppInteractiveCardSend())
            ->setHeader((new WhatsAppInteractiveCardSendHeader())->setType('image')->setUrl('https://cdn.example.com/plants/zebra-haworthia.jpeg'))
            ->setButtons([
                (new WhatsAppInteractiveButtonSend())
                    ->setType('cta_url')
                    ->setCtaUrl((new WhatsAppInteractiveButtonSendCtaUrl())->setText('Buy now')->setUrl('https://shop.example.com/zebra-haworthia')),
            ]),
    ]);

$message = $bird->whatsapp->send(
    to: '+16505551234',
    from: '+13124495648',
    interactive: $interactive,
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --from +13124495648 \
  --interactive '{"body_text":"Here are two of our latest arrivals, each under $25:","cards":[{"buttons":[{"cta_url":{"text":"Buy now","url":"https://shop.example.com/blue-echeveria"},"type":"cta_url"}],"header":{"type":"image","url":"https://cdn.example.com/plants/blue-echeveria.jpeg"}},{"buttons":[{"cta_url":{"text":"Buy now","url":"https://shop.example.com/zebra-haworthia"},"type":"cta_url"}],"header":{"type":"image","url":"https://cdn.example.com/plants/zebra-haworthia.jpeg"}}],"type":"carousel"}' \
  --to +16505551234

curl -X POST "https://{region}.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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" } }]
        }
      ]
    }
  }'

हर सर्विस संदेश पर 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 array में हैं। किसी कार्ड का अपना कोई फ़ुटर या index फ़ील्ड नहीं होता; array में उसकी जगह ही कैरोसेल में उसकी जगह है।

हर कार्ड पर एक जैसे बटन होते हैं

कैरोसेल के हर कार्ड पर एक ही प्रकार के बटन, उतनी ही संख्या में और उसी क्रम में होने चाहिए। अगर कार्ड 1 पर एक cta_url बटन है और कार्ड 2 पर दो quick_reply बटन हैं, तो कैरोसेल अस्वीकार हो जाता है। अगर हर कार्ड पर दो quick_reply बटन हैं लेकिन उनका क्रम अलग है, तो भी कैरोसेल अस्वीकार होता है।

इसका कारण यह है कि WhatsApp मैसेज को कैसे दिखाता है: कैरोसेल साझा लेआउट वाला एक कार्ड व्यू है, अलग-अलग लेआउट वाले कार्डों का समूह नहीं। अलग बटन पंक्ति वाला कार्ड उस साझा लेआउट को तोड़ देगा, इसलिए WhatsApp हर कार्ड का मेल खाना ज़रूरी करता है और Bird भेजने का अनुरोध बनने या शुल्क लगने से पहले इसकी जाँच करता है। मेल न खाने पर E15059 लौटता है।

बटन लेबल का नियम अलग है, और उसका दायरा भी अलग है: लेबल एक कार्ड के भीतर यूनिक होना चाहिए, पूरे कैरोसेल में नहीं। दस कार्डों में से हर एक पर "Buy now" होना ठीक है; एक ही कार्ड पर दो बार "Buy now" होने पर E15056 लौटता है।

सीमाएँ

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 टेम्पलेट का अपना अलग कैरसेल होता है: यह एक टेम्पलेट कंपोनेंट है जिसे एक बार बनाया जाता है, अनुमोदन के लिए Meta को सबमिट किया जाता है, और किसी भी अन्य टेम्पलेट की तरह slug से भेजा जाता है, विंडो के बाहर भी। दोनों में केवल "carousel" शब्द और Meta की 2 से 10 कार्ड की सीमा समान है, इसके अलावा कुछ नहीं। उनके वायर शेप अलग हैं, समीक्षा की प्रक्रिया अलग है, और टेम्पलेट कैरसेल में कार्डों की संख्या हर भेजने पर नहीं चुनी जाती, बल्कि टेम्पलेट के अनुमोदन के समय तय हो जाती है। अगर टेम्पलेट देखते समय आपको वहाँ "carousel" दिखे, तो वह टेम्पलेट टाइप है, इस पेज वाला कैरसेल नहीं।

सीमाएँ और विशेष स्थितियाँ

• ग्राहक सेवा विंडो खुली होनी चाहिए। कैरसेल एक सर्विस मैसेज है, जिसे केवल खुली विंडो के भीतर डिलीवर किया जा सकता है। हब का ग्राहक सेवा विंडो सेक्शन देखें। विंडो की जाँच विफल होने पर भी भेजना रुकता नहीं, इसलिए 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 की जगह buy-echeveria।
• cta_url कार्ड बटन से कोई इनबाउंड इवेंट नहीं बनता। अगर आपको जानना है कि किसी कार्ड से इंटरैक्शन हुआ, तो उस कार्ड पर इसकी जगह quick_reply बटन इस्तेमाल करें, या अपने डेस्टिनेशन URL पर क्लिक ट्रैक करें।

E15059 के अलावा कैरसेल से जुड़ी एकमात्र इंटरैक्टिव त्रुटि E15056 है, जो एक ही कार्ड पर बटन लेबल दोहराने पर मिलती है। जो कोट रिज़ॉल्व नहीं होता, उससे अनुरोध कुछ भी बनने या शुल्क लगने से पहले विफल हो जाता है। अगर id इस वर्कस्पेस के किसी मैसेज की ओर इशारा नहीं करता, तो 404 E15071 मिलता है। अगर वह ऐसे मैसेज की ओर इशारा करता है जिसे कोट नहीं किया जा सकता, तो 422 E15072 मिलता है। बंद विंडो, गायब या अमान्य सेंडर, या अमान्य प्राप्तकर्ता जैसी त्रुटियाँ किसी भी WhatsApp मैसेज को भेजते समय आ सकती हैं। इनके लिए हब का त्रुटियाँ सेक्शन और WhatsApp मैसेज भेजना देखें।

अगले कदम

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