Membalas percakapan Apple Messages

Kirim balasan teks ke pelanggan yang telah membuka percakapan Apple Messages for Business, lalu periksa hasil pengiriman pesan.

Prasyarat

Workspace Anda memerlukan bisnis Apple yang disetujui dan percakapan terbuka yang dimulai oleh pelanggannya. Paket CLI dan SDK dengan dukungan AMB menunggu publikasi. Perintah-perintah ini memerlukan build yang menyertakan bird amb; periksa bird amb --help sebelum melanjutkan. Hingga paket dengan perintah ini dipublikasikan, gunakan referensi API atau dasbor Apple Messages. Lakukan autentikasi untuk region yang menghosting workspace Anda.

Gunakan Bash dengan jq dan uuidgen terinstal. Autentikasi CLI untuk workspace tersebut. Kredensial Anda memerlukan amb:read untuk memeriksa percakapan dan pesan, amb:write untuk mengirim, dan amb_management:read untuk memeriksa bisnis. Gunakan percakapan uji coba yang sudah ada dengan izin untuk menghubungi penerimanya.

1. Pilih bisnis dan percakapan

Contoh kode

bird amb businesses list
bird amb conversations list

Pada prompt, tempelkan ID rekaman yang Anda pilih dari daftar tersebut:

Contoh kode

read -r -p "Business record ID: " BUSINESS_ID
read -r -p "Conversation record ID: " CONVERSATION_ID
bird amb businesses get "$BUSINESS_ID"
bird amb conversations get "$CONVERSATION_ID"

Verifikasi bahwa bisnis disetujui, percakapan terbuka, dan bisnisnya cocok dengan rekaman yang dipilih. Ekstrak identifier Apple yang digunakan permintaan pengiriman:

Contoh kode

APPLE_BUSINESS_ID=$(bird amb businesses get "$BUSINESS_ID" --format json | jq -er '.apple_business_id')
OPAQUE_USER_ID=$(bird amb conversations get "$CONVERSATION_ID" --format json | jq -er '.opaque_user_id')

Nomor telepon tidak dapat menggantikan identifier pelanggan opaque untuk balasan biasa.

2. Pratinjau balasan

Contoh kode

bird amb send --from "$APPLE_BUSINESS_ID" --to "$OPAQUE_USER_ID" \
  --content '{"type":"text","body":"Your order is ready."}' --dry-run

Perintah ini mencetak permintaan tanpa mengirimnya. Periksa bisnis, penerima, dan teks pesan. Untuk memeriksa bentuk permintaan lengkap, jalankan bird amb send --example. File JSON yang diteruskan melalui --body-file dapat membawa field opsional seperti kategori, tag, atau locale.

3. Kirim pesan yang sudah ditinjau

Contoh kode

REQUEST_ID=$(uuidgen)
MESSAGE_ID=$(bird amb send --from "$APPLE_BUSINESS_ID" --to "$OPAQUE_USER_ID" \
  --content '{"type":"text","body":"Your order is ready."}' \
  --idempotency-key "$REQUEST_ID" --format json | jq -er '.id')
printf '%s\n' "$MESSAGE_ID"

Perintah ini menghasilkan identifier permintaan dan menyimpan ID respons di MESSAGE_ID. Pengiriman mengantrikan pesan berbayar untuk pemrosesan asinkron. Jika Anda mencoba lagi, gunakan kembali REQUEST_ID; jangan jalankan uuidgen lagi untuk permintaan tersebut.

4. Periksa hasilnya

Contoh kode

bird amb get "$MESSAGE_ID"
bird amb list-events "$MESSAGE_ID"

sent mencatat penerimaan oleh gateway Apple. Ini tidak memastikan pengiriman ke perangkat atau bahwa pelanggan telah membaca pesan. Pengiriman yang gagal atau tidak pasti perlu diselidiki sebelum pesan lain dikirim. Pemesanan, pesanan, atau tindakan bisnis Anda yang lain harus menunggu hasil konfirmasinya sendiri.

Untuk pembaruan asinkron, berlangganan melalui webhook ke amb.accepted, amb.sent, amb.send_failed, amb.rejected, amb.received, atau event siklus hidup percakapan. Verifikasi tanda tangan dan deduplikasi pengiriman berdasarkan ID webhook. Event dapat tiba tidak berurutan.

Gunakan MCP untuk pertukaran yang sama

MCP menyediakan tool yang sesuai: amb_businesses_list, amb_businesses_get, amb_conversations_list, amb_conversations_get, amb_send, amb_get, dan amb_list_events. Berikan amb_send objek from, to, dan content yang sama, ditambah idempotency_key saat mencoba ulang permintaan. Tinjau penerima dan konten yang tepat sebelum mengotorisasi pemanggilan tool.

Jika tool tidak tersedia, periksa versi server dan scope yang diberikan ke koneksi Anda.

Batas permintaan

Apple Messages secara default mengizinkan 10 permintaan per menit per organisasi. Balasan, indikator pengetikan, dan persiapan lampiran berbagi jatah tersebut di seluruh workspace dan kredensial Anda dalam satu region. Paket Anda atau batas pelanggan yang disetujui dapat menaikkannya; hubungi dukungan untuk peningkatan. Tanyakan administrator organisasi atau dukungan Anda untuk mengonfirmasi batas efektif Anda. Ketika permintaan mengembalikan 429, tunggu selama interval Retry-After sebelum mencoba lagi.

Pemecahan masalah

Jika channel mengembalikan respons not-found, periksa apakah resource tersebut milik workspace yang terautentikasi. Untuk penolakan izin, periksa cakupan channel pada kredensial. Bisnis harus berstatus approved dan percakapan harus open sebelum dapat menerima balasan; supresi juga dapat memblokir pengiriman.

Jika pemrosesan menolak permintaan yang sudah diterima, periksa event dan konfigurasi billing-nya. Hasil gateway pengiriman dan hasil bisnis pelanggan Anda adalah dua hal terpisah. Jangan menyimpulkan pengiriman berhasil hanya dari respons API yang sukses.

Langkah selanjutnya

Baca panduan integrasi Apple Messages untuk pertukaran native dan hasil bisnis asinkron, atau panduan pendaftaran untuk menyiapkan bisnis lain.

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Tonton panduannyaWebhooks done right: reliable delivery events Pahami konsepnyaHow do I verify a webhook signature?Jelajahi kemampuannyaApple Messages for Business Ikuti jalur pembelajaranOperate messaging reliably

Coba praktiknya dan dapatkan ringkasan implementasi