Apple Messages API के ज़रिए जवाब दें

सार्वजनिक Bird API का उपयोग करके Apple Messages की किसी मौजूदा बातचीत में टेक्स्ट जवाब भेजें, फिर उसकी प्रोसेसिंग स्थिति जाँचें और ग्राहक के जवाब प्राप्त करें।

वर्कस्पेस और क्रेडेंशियल तैयार करें

किसी व्यवसाय को कनेक्ट करने और एक टेस्ट बातचीत खोलने के लिए डैशबोर्ड की पहली बातचीत वाली क्विकस्टार्ट पूरी करें। स्वीकृति मिलने से पहले, Testing स्थिति वाला व्यवसाय आपके टेस्ट उपयोगकर्ताओं को टेस्ट मैसेज भेज सकता है। सामान्य जवाबों में ग्राहक के Apple अपारदर्शी पहचानकर्ता का उपयोग होता है; फ़ोन नंबर उसकी जगह नहीं ले सकता।

amb:read, amb:write और amb_management:read के साथ एक वर्कस्पेस API कुंजी बनाएँ। curl, jq और uuidgen के साथ Bash का उपयोग करें। नीचे दिए गए ब्लॉक एक ही Bash स्क्रिप्ट या शेल में चलाएँ। अगर कोई अनुरोध या जाँच विफल होती है, तो त्रुटि सेटिंग्स इस प्रक्रिया को रोक देती हैं। क्रेडेंशियल सोर्स फ़ाइलों में नहीं, अपने एनवायरनमेंट में रखें:

set -euo pipefail
read -r -s -p "Bird API key: " BIRD_API_KEY
printf '\n'
export BIRD_API_KEY
case "$BIRD_API_KEY" in
  bk_eu1_*) BIRD_API_URL=https://eu1.platform.bird.com ;;
  bk_us1_*) BIRD_API_URL=https://us1.platform.bird.com ;;
  *) printf 'Use a workspace key for a supported region.\n' >&2; exit 1 ;;
esac

कुंजी से वर्कस्पेस का संदर्भ तय होता है। अगर आपको क्षेत्र मेल न खाने की त्रुटि मिलती है, तो क्षेत्र देखें।

व्यवसाय और बातचीत चुनें

व्यवसायों और बातचीतों की सूची देखें:

curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/business-accounts" \
  -H "Authorization: Bearer $BIRD_API_KEY" | jq .
curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/conversations" \
  -H "Authorization: Bearer $BIRD_API_KEY" | jq .
read -r -p "Bird business record ID: " BUSINESS_ID
read -r -p "Bird conversation record ID: " CONVERSATION_ID
BUSINESS=$(curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/business-accounts/$BUSINESS_ID" \
  -H "Authorization: Bearer $BIRD_API_KEY")
CONVERSATION=$(curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/conversations/$CONVERSATION_ID" \
  -H "Authorization: Bearer $BIRD_API_KEY")
printf '%s' "$BUSINESS" | jq -e '.status == "pending" or .status == "active"'
printf '%s' "$CONVERSATION" | jq -e --arg business "$BUSINESS_ID" \
  '.status == "open" and .business_account_id == $business'

यह उदाहरण किसी अधिकृत टेस्ट बातचीत के लिए है; Testing स्थिति से सार्वजनिक लॉन्च की अनुमति नहीं मिलती। अगर कोई भी जाँच false लौटाती है या कोई अनुरोध विफल होता है, तो रुक जाएँ। एक ही व्यवसाय के रिकॉर्ड चुनें। और परिणामों के लिए कर्सर पेजिनेशन का पालन करें; पहले पेज में पूरी सूची नहीं होती।

जवाब की समीक्षा करें और भेजें

apple_business_id को from के रूप में और opaque_user_id को to के रूप में इस्तेमाल करके अनुरोध बनाएँ:

APPLE_BUSINESS_ID=$(printf '%s' "$BUSINESS" | jq -er '.apple_business_id')
OPAQUE_USER_ID=$(printf '%s' "$CONVERSATION" | jq -er '.opaque_user_id')
REQUEST=$(jq -n --arg from "$APPLE_BUSINESS_ID" --arg to "$OPAQUE_USER_ID" \
  '{from:$from,to:$to,content:{type:"text",body:"We can help arrange your visit. Which day works for you?"}}')
printf '%s\n' "$REQUEST" | jq .

बिज़नेस, प्राप्तकर्ता और टेक्स्ट की समीक्षा करें। अगला अनुरोध एक असली संदेश को कतार में डालता है, जिसका शुल्क लग सकता है:

REQUEST_ID=$(uuidgen)
RESPONSE=$(curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $REQUEST_ID" \
  --data "$REQUEST")
printf '%s\n' "$RESPONSE" | jq .
MESSAGE_ID=$(printf '%s' "$RESPONSE" | jq -er '.id')

202 प्रतिक्रिया पुष्टि करती है कि अनुरोध असिंक्रोनस प्रोसेसिंग के लिए स्वीकार कर लिया गया है। उसी तार्किक अनुरोध के लिए फिर से प्रयास करते समय REQUEST_ID और बिना बदली बॉडी को बनाए रखें; नई कुंजी बनाने से एक और संदेश बन सकता है। आइडेम्पोटेंसी देखें।

प्रोसेसिंग की जाँच करें और जवाब प्राप्त करें

संदेश प्राप्त करें और संदेश इवेंट की सूची का इस्तेमाल करें:

curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $BIRD_API_KEY" | jq .
curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/messages/$MESSAGE_ID/events" \
  -H "Authorization: Bearer $BIRD_API_KEY" | jq .

असिंक्रोनस अपडेट के लिए amb.accepted, amb.sent, amb.send_failed, amb.rejected, amb.received और ज़रूरी बातचीत लाइफ़साइकल इवेंट के लिए वेबहुक कॉन्फ़िगर करें। सिग्नेचर सत्यापित करें, दोहराई गई वेबहुक डिलीवरी हटाएँ और क्रम से बाहर आने वाले इवेंट संभालें। अनिश्चित स्थिति का मिलान करते समय संदेश प्राप्त करें।

amb.received के लिए आने वाली सामग्री की जाँच करें और बातचीत को अपने लंबित ग्राहक कार्य से मिलाएँ। जहाँ उपलब्ध हों, भेजे गए आइडेंटिफ़ायर से नेटिव जवाबों को प्रोसेस करें; टाइम-पिकर के जवाब में चुना गया लेबल हो सकता है। कोई अपरिवर्तनीय कार्रवाई करने या उसके परिणाम की पुष्टि करने से पहले बुकिंग, ऑर्डर या केस सिस्टम की जाँच करें।

संदेश की सामग्री का विस्तार करें

संदेश भेजें संदर्भ text, rich_link और interactive सामग्री को परिभाषित करता है। इंटरैक्टिव संदेशों में क्विक रिप्लाई, सूचियाँ, टाइम पिकर, फ़ॉर्म और कस्टम iMessage ऐप शामिल हैं। ग्राहक अनुभव के लिए नेटिव संदेश डिज़ाइन मार्गदर्शन का इस्तेमाल करें।

Apple से बनने वाले प्रीव्यू के लिए समर्थित डैशबोर्ड लिंक वर्कफ़्लो का इस्तेमाल करें। मीडिया स्रोत URL प्रोसेसिंग के दौरान लाए जाते हैं और स्वीकृति के बाद भी विफल हो सकते हैं; मीडिया आवश्यकताओं का पालन करें।

bird amb या संबंधित amb_* टूल उपलब्ध कराने वाले CLI या MCP इंस्टॉलेशन वही एड्रेसिंग और स्थिति अर्थ इस्तेमाल करते हैं। इस्तेमाल से पहले इंस्टॉल की गई कमांड या टूल स्कीमा जाँचें; यह walkthrough सीधे सार्वजनिक HTTP अनुबंध पर निर्भर है।

त्रुटियाँ हल करें

404 का अर्थ हो सकता है कि बातचीत अज्ञात है या वर्कस्पेस गलत है। 403 मिलने पर ऑपरेशन का आवश्यक स्कोप चाहिए। बंद बातचीत या असमर्थित नेटिव इंटरैक्शन पर 422 लौट सकता है; बंद बातचीत को ग्राहक को ही फिर से खोलना होगा। 429 मिलने पर Retry-After का पालन करें और साझा अनुरोध दर सीमित करने संबंधी मार्गदर्शन देखें।

स्वीकृति के बाद, प्रोसेसिंग या बिलिंग विफलता का पता लगाने के लिए संदेश इवेंट और स्टेटस जाँचें। Sent का अर्थ है कि Apple गेटवे ने संदेश स्वीकार कर लिया है; इससे डिवाइस पर डिलीवरी या पढ़े जाने की रसीद नहीं मिलती। व्यावसायिक परिणामों को अलग से मापें।