WhatsApp लिंक बटन

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

लिंक बटन भेजें

interactive.type को cta_url पर सेट करें, और साथ में एक body_text तथा एक cta_url ऑब्जेक्ट दें, जिसमें बटन का text और url हो:

const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  interactive: {
    type: "cta_url",
    body_text: "Tap the button below to see the available dates.",
    cta_url: { text: "See dates", url: "https://example.com/workshops?click_id=a1b2c3" },
  },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+16505551234",
    from_="+13124495648",
    interactive={
        "type": "cta_url",
        "body_text": "Tap the button below to see the available dates.",
        "cta_url": {"text": "See dates", "url": "https://example.com/workshops?click_id=a1b2c3"},
    },
)
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:     "cta_url",
			BodyText: "Tap the button below to see the available dates.",
			CtaUrl:   &bird.WhatsAppInteractiveCtaUrlSend{Text: "See dates", Url: "https://example.com/workshops?click_id=a1b2c3"},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$interactive = (new WhatsAppMessageSendRequestInteractive())
    ->setType('cta_url')
    ->setBodyText('Tap the button below to see the available dates.')
    ->setCtaUrl(
        (new WhatsAppInteractiveSendCtaUrl())
            ->setText('See dates')
            ->setUrl('https://example.com/workshops?click_id=a1b2c3'),
    );

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

bird whatsapp send \
  --from +13124495648 \
  --interactive '{"body_text":"Tap the button below to see the available dates.","cta_url":{"text":"See dates","url":"https://example.com/workshops?click_id=a1b2c3"},"type":"cta_url"}' \
  --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": "cta_url",
      "body_text": "Tap the button below to see the available dates.",
      "cta_url": {
        "text": "See dates",
        "url": "https://example.com/workshops?click_id=a1b2c3"
      }
    }
  }'

हर सर्विस संदेश पर from आवश्यक है: यह आपके वर्कस्पेस के स्वामित्व वाला नंबर होना चाहिए, Bird द्वारा प्रबंधित नंबर नहीं। पूरे ढांचे में एक वैकल्पिक हेडर, फुटर और किसी पिछले संदेश का उद्धरण भी जोड़ा जा सकता है:

{
  "to": "+16505551234",
  "from": "+13124495648",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "interactive": {
    "type": "cta_url",
    "header": {
      "type": "image",
      "url": "https://cdn.example.com/banners/workshop.png"
    },
    "body_text": "Tap the button below to see the available dates.",
    "footer_text": "Dates are subject to change.",
    "cta_url": {
      "text": "See dates",
      "url": "https://example.com/workshops?click_id=a1b2c3"
    }
  },
  "tags": [{ "name": "campaign", "value": "autumn-workshops" }],
  "metadata": { "order_id": "A-4192" }
}

in_reply_to_message_id उसी बातचीत के किसी पिछले संदेश को उद्धृत करता है। उद्धरण कैसे हल होता है और किन मामलों में यह चूक सकता है, यह जानने के लिए हब का जवाब से मिलान के लिए संदेश उद्धृत करना देखें।

यह प्रकार ठीक एक cta_url बटन भेजता है, और इसके साथ buttons, list या cards नहीं भेजे जा सकते। बटन के साझा ढांचे के लिए हब का बटन सेक्शन देखें। कैरोसेल कार्ड का अपना लिंक बटन भी इसी ढांचे का उपयोग करता है।

हेडर और फुटर

हेडर वैकल्पिक है, और यह चार में से किसी एक रूप में हो सकता है:

"header": { "type": "text",     "text": "New workshop dates" }
"header": { "type": "image",    "url": "https://cdn.example.com/a.png" }
"header": { "type": "video",    "url": "https://cdn.example.com/a.mp4" }
"header": { "type": "document", "url": "https://cdn.example.com/a.pdf" }

मीडिया हेडर (image, video या document) अपनी फ़ाइल को अपलोड किए गए मीडिया हैंडल के बजाय एक सार्वजनिक https URL के रूप में रखता है, जिसे WhatsApp भेजते समय फ़ेच करता है। footer_text वैकल्पिक है और बटन के नीचे एक पंक्ति जोड़ता है।

सीमाएँ

url पर 2000 अक्षरों की सीमा Bird की अपनी है: Meta इस फ़ील्ड के लिए कोई लंबाई सीमा प्रकाशित नहीं करता। url यह भी जाँचता है कि format: uri हो, यानी स्कीम वाला पूर्ण पता, लेकिन Bird यह नहीं जाँचता कि स्कीम कौन-सी है: http:// पता भी Bird के सत्यापन में पास हो जाता है, और वह डिलीवर होगा या नहीं, इसका फ़ैसला सिर्फ़ Meta करता है।

क्लिक से क्या रिपोर्ट होता है

टैप करने पर पता प्राप्तकर्ता के ब्राउज़र में खुलता है, और API के ज़रिए आपको कुछ भी वापस नहीं मिलता। लिंक बटन का टैप interactive_reply नहीं है: interactive_reply बनाने वाला इनबाउंड मैपर सिर्फ़ रिप्लाई बटन के टैप और सूची की पंक्ति के टैप को संभालता है, और cta_url लिंक का कोई समकक्ष इनबाउंड रूप नहीं है। आप आउटबाउंड मैसेज के स्टेटस इवेंट (whatsapp.sent, whatsapp.delivered और whatsapp.read) ट्रैक कर सकते हैं, लेकिन read_at सिर्फ़ यह बताता है कि मैसेज खोला गया, यह नहीं कि बटन टैप किया गया। WhatsApp या Bird से न कोई क्लिक इवेंट मिलता है, न टाइमस्टैम्प, न ही हर प्राप्तकर्ता के टैप का कोई संकेत।

भेजने की प्रक्रिया खुद एट्रिब्यूशन नहीं देती, इसलिए इसे वापस पाने के दो तरीके हैं:

• लैंडिंग पेज पर ट्रैकिंग लगाएँ। क्लिक का एकमात्र उपलब्ध सबूत आपके अपने डेस्टिनेशन सर्वर पर होता है, उस URL से जो आपने भेजा था।
• हर प्राप्तकर्ता के लिए URL खुद बदलें। आप जो url भेजते हैं वह एक शाब्दिक स्ट्रिंग है: Bird उसे सहेजता है और बिना बदले Meta को भेज देता है, न कोई प्रतिस्थापन होता है, न कोई वेरिएबल सिंटैक्स। एक बार भेजने में यह हर प्राप्तकर्ता के लिए एक जैसा रहता है, इसलिए हर प्राप्तकर्ता का एट्रिब्यूशन पाने के लिए आपको अपना क्वेरी पैरामीटर बनाना होगा, जैसे ?click_id=<value>, और हर प्राप्तकर्ता के लिए एक POST /v1/whatsapp/messages कॉल करनी होगी। एंडपॉइंट पहले से ही हर कॉल में एक ही to लेता है, इसलिए यह आपकी ओर का हिसाब-किताब है, API में किसी फ़ीचर की कमी नहीं।

तीसरा विकल्प इस टाइप से पूरी तरह बाहर है: url बटन वेरिएबल वाले टेम्पलेट को WhatsApp खुद हर प्राप्तकर्ता के लिए पर्सनलाइज़ करता है, और यह मान भेजने के अनुरोध के button कंपोनेंट से दिया जाता है। यह वेरिएबल पते के अंत में होना चाहिए, {{1}} के रूप में लिखा हुआ, इसलिए यह आख़िरी पाथ सेगमेंट या क्वेरी मान बदल सकता है, लेकिन होस्ट या URL का बीच का हिस्सा कभी नहीं। फ़र्क़ यह है: टेम्पलेट से आपको हर प्राप्तकर्ता के लिए अलग URL और कस्टमर सर्विस विंडो के बाहर डिलीवरी मिलती है, बदले में Meta की समीक्षा और एक तय स्वीकृत रूप स्वीकार करना पड़ता है। वहीं cta_url भेजने से आप खुली विंडो के अंदर बिना समीक्षा के मुक्त रूप से भेज सकते हैं, और URL आप खुद बदलते हैं।

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

• ग्राहक सेवा विंडो खुली होनी चाहिए। लिंक बटन एक सेवा संदेश है, जो केवल खुली विंडो के भीतर ही डिलीवर हो सकता है; हब का ग्राहक सेवा विंडो देखें। विंडो की जाँच विफल होने पर भी अनुरोध को आगे जाने देती है, इसलिए 202 इस बात का प्रमाण नहीं है कि भेजते समय विंडो वास्तव में खुली थी।
• from ऐसा नंबर होना चाहिए जिसका स्वामी आपका वर्कस्पेस हो। इसे छोड़ देने पर, या ऐसा नंबर देने पर जो कनेक्टेड सेंडर नहीं है, भेजने का अनुरोध बनने से पहले ही अस्वीकार कर दिया जाता है।
• URL पूरे भेजने के लिए स्थिर रहता है और हर प्राप्तकर्ता के लिए एक जैसा होता है। इस प्रकार में प्रति-प्राप्तकर्ता कोई वेरिएबल नहीं है। फिर भी क्लिक का श्रेय तय करने के तरीके के लिए क्लिक से क्या रिपोर्ट होता है देखें।
• टैप का कोई संकेत कभी नहीं मिलता। लिंक बटन पर टैप से न कोई इनबाउंड संदेश बनता है और न कोई वेबहुक इवेंट। केवल इस प्रकार के भरोसे क्लिक मेट्रिक्स का वादा करने वाली सुविधा न बनाएँ।
• Bird URL की संरचना जाँचता है, उसकी स्कीम नहीं। url स्कीम सहित एक पूर्ण पता होना चाहिए, लेकिन Bird https की माँग नहीं करता, और Meta भी स्कीम पर कोई प्रतिबंध प्रकाशित नहीं करता। इसकी तुलना मीडिया हेडर के url से करें, जिसके लिए https आवश्यक होना प्रलेखित है।
• जिस मीडिया हेडर URL को WhatsApp प्राप्त नहीं कर पाता, वह भेजने का अनुरोध स्वीकार होने के बाद विफल होता है। WhatsApp भेजते समय हेडर फ़ाइल प्राप्त करता है और उसे 10 मिनट तक कैश रखता है; साइन किए गए URL की वैधता भेजने की प्रक्रिया से अधिक समय तक रहनी चाहिए, और पहुँच से बाहर URL एसिंक्रोनस रूप से विफल होता है, जिसमें संदेश के last_error पर media_rejected आता है।

हब की त्रुटियाँ तालिका में दी गई संरचना-जाँचों में से कोई भी इस प्रकार पर लागू नहीं होती: वे सूची की पंक्तियों, buttons ऐरे या कैरोसेल के कार्ड की जाँच करती हैं, और cta_url संदेश में इन तीनों में से कुछ नहीं होता। संरचना की गलती, जैसे 20 अक्षरों से लंबा text लेबल, इन कोड में से किसी के बजाय एक सामान्य अनुरोध-सत्यापन त्रुटि के रूप में लौटती है। जो उद्धरण हल नहीं होता, वह कुछ भी बनने या शुल्क लगने से पहले अनुरोध को विफल कर देता है: जब id इस वर्कस्पेस के किसी संदेश की ओर इशारा नहीं करती, तो 404 E15071, और जब वह ऐसे संदेश की ओर इशारा करती है जिसे उद्धृत नहीं किया जा सकता, तो 422 E15072। किसी भी WhatsApp भेजने में आ सकने वाली त्रुटियों, जैसे बंद विंडो, अनुपस्थित या अमान्य सेंडर, या अमान्य प्राप्तकर्ता, के लिए हब का त्रुटियाँ और WhatsApp संदेश भेजना देखें।

अगले चरण

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