Balas melalui API Apple Messages

Kirim balasan teks ke percakapan Apple Messages yang sudah ada menggunakan Bird publik API, lalu periksa status pemrosesannya dan terima balasan pelanggan.

Siapkan workspace dan kredensial

Selesaikan panduan cepat percakapan pertama di dasbor untuk menghubungkan bisnis dan membuka percakapan uji. Bisnis berstatus Draft dapat mengirim pesan uji sebelum disetujui. Balasan biasa menggunakan pengenal opak Apple milik pelanggan; nomor telepon tidak dapat menggantikannya.

Buat kunci API workspace dengan amb:read, amb:write, dan amb_management:read. Gunakan Bash dengan curl, jq, dan uuidgen. Jalankan blok-blok berikut dalam satu skrip Bash atau shell. Pengaturan error menghentikan panduan ini jika permintaan atau validasi gagal. Simpan kredensial di environment Anda, bukan di file sumber:

Contoh kode

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

Kunci ini menyediakan konteks workspace. Lihat region jika Anda menerima ketidakcocokan region.

Pilih bisnis dan percakapan

Daftarkan bisnis dan percakapan:

Contoh kode

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'

Contoh ini untuk percakapan uji yang diizinkan; status Draft tidak mengizinkan peluncuran publik. Berhenti jika salah satu pemeriksaan mengembalikan false atau permintaan gagal. Pilih catatan dari bisnis yang sama. Untuk hasil lainnya, ikuti paginasi kursor; halaman pertama bukan inventaris lengkap.

Tinjau dan kirim balasan

Bangun permintaan menggunakan apple_business_id sebagai from dan opaque_user_id sebagai to:

Contoh kode

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 .

Tinjau bisnis, penerima, dan teks. Permintaan berikutnya mengantrikan pesan nyata yang berpotensi dikenai biaya:

Contoh kode

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')

Respons 202 mengonfirmasi penerimaan untuk pemrosesan asinkron. Pertahankan REQUEST_ID dan body yang tidak berubah saat mencoba lagi permintaan logis tersebut; membuat kunci baru dapat menghasilkan pesan tambahan. Lihat idempotensi.

Periksa pemrosesan dan terima balasan

Gunakan Get message dan List message events:

Contoh kode

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 .

Untuk pembaruan asinkron, konfigurasikan webhook untuk amb.accepted, amb.sent, amb.send_failed, amb.rejected, amb.received, dan event siklus hidup percakapan yang diperlukan. Verifikasi tanda tangan, deduplikasi pengiriman webhook, dan toleransi event yang tidak berurutan. Ambil pesan saat merekonsiliasi status yang tidak pasti.

Untuk amb.received, periksa konten masuk dan cocokkan percakapan dengan tugas pelanggan yang tertunda. Proses jawaban native menggunakan identifier yang dikirim jika tersedia; balasan time-picker dapat berisi label yang dipilih. Periksa sistem pemesanan, pesanan, atau kasus sebelum mengambil aksi yang tidak dapat dibatalkan atau mengonfirmasi hasilnya.

Perluas konten pesan

Referensi Send message mendefinisikan konten text, rich_link, dan interactive. Pesan interaktif mencakup quick reply, daftar, time picker, formulir, dan aplikasi iMessage kustom. Gunakan panduan desain pesan native untuk pengalaman pelanggan.

Untuk pratinjau yang dibuat Apple, gunakan alur tautan dasbor yang didukung. URL sumber media diambil saat pemrosesan dan dapat gagal setelah penerimaan; gunakan persyaratan media.

Instalasi CLI atau MCP yang mengekspos bird amb atau tool amb_* yang sesuai menggunakan semantik pengalamatan dan status yang sama. Periksa skema perintah atau tool yang terinstal sebelum menggunakannya; walkthrough ini bergantung langsung pada spesifikasi HTTP publik.

Atasi kesalahan

404 dapat menunjukkan percakapan yang tidak dikenal atau workspace yang salah. 403 memerlukan cakupan operasi tersebut. Percakapan yang ditutup atau interaksi native yang tidak didukung dapat mengembalikan 422; pelanggan harus membuka kembali percakapan yang ditutup. Untuk 429, ikuti Retry-After dan panduan pembatasan laju permintaan bersama.

Setelah diterima, periksa event dan status pesan untuk kegagalan pemrosesan atau penagihan. Sent adalah penerimaan oleh gateway Apple; ini tidak memberikan konfirmasi pengiriman ke perangkat atau konfirmasi pesan dibaca. Ukur hasil bisnis secara terpisah.