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

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

छह प्रकार

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

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

हर इंटरैक्टिव भेजने के लिए from भी ज़रूरी है, यानी ऐसा नंबर जो आपके वर्कस्पेस का हो। Bird के प्रबंधित नंबर इसे नहीं ले जा सकते, इसलिए इंटरैक्टिव संदेश भेजने से पहले आपको अपना नंबर कनेक्ट करना होगा।

इंटरैक्टिव सामग्री फ़ील्ड

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

अनुरोध की संरचना, 202 प्रतिक्रिया मॉडल और सुरक्षित रूप से फिर से प्रयास करने के लिए WhatsApp संदेश भेजना देखें।

यह एक न्यूनतम इंटरैक्टिव संदेश है: reply-buttons भेजने में दो 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" } }
      ]
    }
  }'

बटन

छह में से चार प्रकारों में बटन होता है, और ये सभी एक ही संरचना का उपयोग करते हैं: एक discriminated ऑब्जेक्ट, जिसका 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 वेबहुक की सदस्यता लें: इसके पेलोड में interactive_reply होता है, इसलिए उसमें पहले से ही टैप किए गए बटन या पंक्ति का नाम होता है। इंटरैक्टिव जवाब प्राप्त करना में टैप की पढ़ी जाने वाली संरचना, वेबहुक पेलोड, और दूसरे arm पर आने वाले टैप का विवरण है।

जवाब को जोड़ने के लिए मैसेज को कोट करना

भेजते समय in_reply_to_message_id उसी बातचीत के किसी पिछले मैसेज को कोट करता है, और हर मैसेज, चाहे भेजा गया हो या प्राप्त, पढ़ते समय इसे वापस लौटाता है। दोनों दिशाओं के लिए यह एक ही फ़ील्ड है।

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

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

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

त्रुटियाँ

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

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

अगले कदम

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