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

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

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

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

amb:read, amb:write और amb_management:read के साथ एक वर्कस्पेस API key बनाएँ। 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

key वर्कस्पेस कॉन्टेक्स्ट प्रदान करती है। यदि आपको रीजन मिसमैच मिलता है तो रीजन देखें।

बिज़नेस और कन्वर्सेशन चुनें

बिज़नेस और कन्वर्सेशन लिस्ट करें:

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'

यह उदाहरण अधिकृत टेस्ट बातचीत के लिए है; Draft स्थिति सार्वजनिक लॉन्च की अनुमति नहीं देती। किसी भी जाँच में 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 और अपरिवर्तित बॉडी बनाए रखें; दूसरी key जनरेट करने से एक और मैसेज बन सकता है। देखें आइडेम्पोटेंसी।

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

मैसेज प्राप्त करें और मैसेज इवेंट सूचीबद्ध करें का उपयोग करें:

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 के लिए, इनकमिंग कंटेंट जाँचें और कन्वर्सेशन को अपने लंबित कस्टमर कार्य से मिलाएँ। जहाँ उपलब्ध हों, भेजे गए आइडेंटिफ़ायर का उपयोग करके नेटिव उत्तर प्रोसेस करें; time-picker के जवाब में एक चयनित लेबल हो सकता है। कोई अपरिवर्तनीय एक्शन लेने या उसका परिणाम पुष्टि करने से पहले बुकिंग, ऑर्डर या केस सिस्टम जाँचें।

मैसेज कंटेंट विस्तृत करें

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

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

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

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

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

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