WhatsApp इंटरैक्टिव संदेश

इंटरैक्टिव संदेश बॉडी टेक्स्ट के साथ कुछ ऐसा होता है जिसे प्राप्तकर्ता टैप कर सके: एक WhatsApp बटन, एक मेन्यू, एक लिंक, एक कार्ड, या उनके लोकेशन या संपर्क विवरण का अनुरोध। जहाँ टेम्प्लेट उत्तर का मतलब फ़्री टेक्स्ट पार्स करना होता है, वहाँ WhatsApp मेन्यू या WhatsApp बटनों का एक सेट प्राप्तकर्ता को विकल्पों का एक निश्चित सेट देता है और आपको वह वैल्यू लौटाता है जो आपने परिभाषित की। यह पेज बताता है कि छह प्रकारों में क्या समान है; हर प्रकार का अपना पेज उसके वायर शेप और उसकी अपनी सीमाएँ कवर करता है।

छह प्रकार

हर प्रकार फ़्री-फ़ॉर्म है: केवल एक खुली कस्टमर सर्विस विंडो के अंदर डिलीवर किया जा सकता है, और Meta द्वारा कभी भी उस तरह रिव्यू नहीं किया जाता जैसे एक टेम्प्लेट किया जाता है।

इंटरैक्टिव संदेश फ़्री-फ़ॉर्म कंटेंट हैं, इसलिए कस्टमर सर्विस विंडो नियम लागू होता है: इसका क्या अर्थ है और बंद विंडो क्या लौटाती है, इसके लिए कस्टमर सर्विस विंडो देखें।

हर इंटरैक्टिव सेंड को from की भी ज़रूरत होती है, जो आपके वर्कस्पेस का अपना नंबर है। Bird के मैनेज्ड नंबर इसे नहीं ले जा सकते, इसलिए इंटरैक्टिव सेंड के लिए पहले आपका अपना नंबर कनेक्ट होना ज़रूरी है।

इंटरैक्टिव कंटेंट आर्म

interactive POST /v1/whatsapp/messages पर म्यूचुअली एक्सक्लूसिव कंटेंट फ़ील्ड्स में से एक है, template, text, image, और बाकी के साथ: एक सेंड पर इनमें से ठीक एक ही मौजूद हो सकता है। interactive के अंदर, type बताता है कि यह छह वेरिएंट में से कौन सा है, और उस वेरिएंट की अपनी फ़ील्ड बाकी सब ले जाती है (buttons, list, cta_url, या cards)। स्कीमा हर दूसरे वेरिएंट की फ़ील्ड को रोकती है, इसलिए एक सेंड पर दो वेरिएंट मिलाने पर हैंडलर तक पहुँचने से पहले ही वैलिडेशन फ़ेल हो जाता है।

रिक्वेस्ट एनवेलप, 202 रिस्पॉन्स मॉडल, और सुरक्षित रीट्राई के लिए, इस पेज पर दोबारा सिखाने की बजाय WhatsApp संदेश भेजना देखें।

यहाँ एक न्यूनतम इंटरैक्टिव संदेश है: एक रिप्लाई-बटन सेंड पर दो WhatsApp बटन, एक समय में एक भाषा।

const msg = await bird.whatsapp.send({
  to: "+15551234567",
  from: "+13124495648",
  interactive: {
    type: "button",
    body_text: "Your gardening workshop is scheduled for 9am tomorrow.",
    buttons: [
      { type: "quick_reply", quick_reply: { slug: "change-booking", text: "Change" } },
      { type: "quick_reply", quick_reply: { slug: "cancel-booking", text: "Cancel" } },
    ],
  },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+15551234567",
    from_="+13124495648",
    interactive={
        "type": "button",
        "body_text": "Your gardening workshop is scheduled for 9am tomorrow.",
        "buttons": [
            {"type": "quick_reply", "quick_reply": {"slug": "change-booking", "text": "Change"}},
            {"type": "quick_reply", "quick_reply": {"slug": "cancel-booking", "text": "Cancel"}},
        ],
    },
)
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:   "+15551234567",
		From: "+13124495648",
		Interactive: &bird.WhatsAppInteractiveSend{
			Type:     "button",
			BodyText: "Your gardening workshop is scheduled for 9am tomorrow.",
			Buttons: &[]bird.WhatsAppInteractiveButtonSend{
				{Type: "quick_reply", QuickReply: &bird.WhatsAppInteractiveQuickReplyButtonSend{Slug: "change-booking", Text: "Change"}},
				{Type: "quick_reply", QuickReply: &bird.WhatsAppInteractiveQuickReplyButtonSend{Slug: "cancel-booking", Text: "Cancel"}},
			},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$interactive = (new WhatsAppMessageSendRequestInteractive())
    ->setType('button')
    ->setBodyText('Your gardening workshop is scheduled for 9am tomorrow.')
    ->setButtons([
        (new WhatsAppInteractiveButtonSend())
            ->setType('quick_reply')
            ->setQuickReply((new WhatsAppInteractiveButtonSendQuickReply())->setSlug('change-booking')->setText('Change')),
        (new WhatsAppInteractiveButtonSend())
            ->setType('quick_reply')
            ->setQuickReply((new WhatsAppInteractiveButtonSendQuickReply())->setSlug('cancel-booking')->setText('Cancel')),
    ]);

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

bird whatsapp send \
  --from +13124495648 \
  --interactive '{"body_text":"Your gardening workshop is scheduled for 9am tomorrow.","buttons":[{"quick_reply":{"slug":"change-booking","text":"Change"},"type":"quick_reply"},{"quick_reply":{"slug":"cancel-booking","text":"Cancel"},"type":"quick_reply"}],"type":"button"}' \
  --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",
    "from": "+13124495648",
    "interactive": {
      "type": "button",
      "body_text": "Your gardening workshop is scheduled for 9am tomorrow.",
      "buttons": [
        { "type": "quick_reply", "quick_reply": { "slug": "change-booking", "text": "Change" } },
        { "type": "quick_reply", "quick_reply": { "slug": "cancel-booking", "text": "Cancel" } }
      ]
    }
  }'

बटन

छह में से चार प्रकार एक बटन रखते हैं, और वे सभी एक ही शेप पर आधारित हैं: एक डिस्क्रिमिनेटेड ऑब्जेक्ट जिसका type quick_reply या cta_url है, हर एक उसी नाम की अपनी नेस्टेड फ़ील्ड ले जाता है। एक quick_reply बटन slug और text ले जाता है; एक cta_url बटन text और url ले जाता है। कौन से प्रकार कौन सा बटन शेप स्वीकार करते हैं:

• रिप्लाई बटन केवल quick_reply बटन भेजते हैं, 1 से 3 तक।
• लिंक बटन ठीक एक cta_url बटन भेजते हैं।
• मीडिया कैरोसेल हर कार्ड पर बटन रखते हैं: या तो एक cta_url बटन, या तीन तक quick_reply बटन, और कैरोसेल में हर कार्ड का मिलान होना चाहिए।
• लिस्ट मेन्यू इस बटन ऑब्जेक्ट के बजाय सेक्शन के अंदर रो का उपयोग करते हैं, जो उनके अपने पेज पर कवर है।

एक quick_reply बटन का slug उस बटन के लिए आपका अपना हैंडल है। यह प्राप्तकर्ता को कभी नहीं दिखाया जाता, केवल इसका text लेबल दिखाया जाता है, और रिप्लाई पर slug ज्यों-का-त्यों इको होता है। यही राउंड ट्रिप रिप्लाई को उस बटन से सहसंबद्ध बनाती है जिसने इसे उत्पन्न किया, इसलिए यह हर लीफ़ पेज पर कहने के बजाय यहाँ एक बार कहना उचित है।

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

बटन दबाने या मेन्यू रो चुनने पर अपना इनबाउंड संदेश भेजा जाता है, जो एक interactive_reply ऑब्जेक्ट ले जाता है। interactive_reply.type button या list होता है; जो भी हो, नेस्टेड ऑब्जेक्ट आपके द्वारा डिक्लेयर किया गया slug और text ले जाता है, वह टैप किया गया लेबल जो प्राप्तकर्ता ने वास्तव में देखा। दो अनुरोध प्रकार, लोकेशन अनुरोध और संपर्क जानकारी अनुरोध, अलग तरह से उत्तर देते हैं: लोकेशन अनुरोध की रिप्लाई एक सामान्य इनबाउंड लोकेशन संदेश है, और संपर्क जानकारी अनुरोध की रिप्लाई एक इनबाउंड संपर्क कार्ड है, interactive_reply बिलकुल नहीं।

रिप्लाई आप तक मैसेज लिस्ट और GET /v1/whatsapp/messages/{id} के ज़रिए पहुँचती है, ठीक उसी तरह जैसे कोई भी इनबाउंड WhatsApp संदेश पहुँचता है। पोलिंग के बजाय आने पर तुरंत कार्रवाई करने के लिए, whatsapp.received webhook सब्सक्राइब करें: इसका पेलोड interactive_reply ले जाता है, इसलिए यह पहले से ही टैप किए गए बटन या रो का नाम बताता है। इंटरैक्टिव रिप्लाई प्राप्त करना टैप की रीड शेप, webhook पेलोड, और दूसरे आर्म पर आने वाले टैप को कवर करता है।

रिप्लाई को सहसंबद्ध करने के लिए संदेश उद्धृत करना

सेंड पर in_reply_to_message_id उसी वार्तालाप से एक पहले के संदेश को उद्धृत करता है, और हर संदेश, भेजा या प्राप्त, रीड पर इसे वापस इको करता है। यह दोनों दिशाओं के लिए एक ही फ़ील्ड है।

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

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

संदेश जिस विंडो में उद्धृत किया जा सकता है वह 15 दिनों तक सीमित है; इसके बाद सेंड 404 E15071 के साथ फ़ेल हो जाता है, क्योंकि Bird अब वह प्रोवाइडर id नहीं रखता जो एक उद्धरण के लिए ज़रूरी है। WhatsApp संदेश भेजना सेंड-साइड फ़ील्ड का मालिक है: इसकी लंबाई, इसका रिज़ॉल्यूशन, और रिक्वेस्ट शेप।

त्रुटियाँ

तीन त्रुटि कोड इंटरैक्टिव कंटेंट के लिए विशिष्ट हैं। हर एक केवल उन प्रकारों पर फ़ायर होता है जिनमें वह फ़ील्ड है जिसे वह जाँचता है, इसलिए चौथा कॉलम बताता है कि कौन से प्रकार वास्तव में हर एक तक पहुँच सकते हैं।

हर इंटरैक्टिव सेंड उन त्रुटियों से भी टकरा सकता है जो कोई भी WhatsApp सेंड दे सकता है: एक बंद कस्टमर सर्विस विंडो, एक गायब या अमान्य सेंडर, एक अमान्य प्राप्तकर्ता, या अस्पष्ट कंटेंट। ये हर WhatsApp कंटेंट प्रकार में साझा हैं, इंटरैक्टिव संदेशों के लिए विशिष्ट नहीं; उस सूची के लिए यहाँ कॉपी के बजाय WhatsApp संदेश भेजना देखें।

अगले कदम

• WhatsApp संदेश भेजना: रिक्वेस्ट एनवेलप, 202 मॉडल, और सुरक्षित रीट्राई
• WhatsApp इवेंट: प्रति संदेश डिलीवरी ट्रैक करें, API या वेबहुक के ज़रिए
• WhatsApp टेम्प्लेट: वे संदेश जो विंडो बंद होने के बाद भी आप भेज सकते हैं