# 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](/docs/api/reference/create-amb-message) 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

```sh
bird amb businesses list
bird amb conversations list
```

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

```sh
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:

```sh
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

```sh
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

```sh
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

```sh
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](/docs/guides/webhooks) 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](/docs/guides/apple-messages/api) untuk pertukaran native dan hasil bisnis asinkron, atau [panduan pendaftaran](/docs/guides/apple-messages/registration) untuk menyiapkan bisnis lain.

## Related resources

- [Webhooks done right: reliable delivery events](/learn/basics/webhooks-done-right-reliable-delivery-events) (video)
- [How do I verify a webhook signature?](/explained/platform/how-do-i-verify-a-webhook-signature) (answer)
- [Apple Messages for Business](/apple-messages-api) (product)
- [Operate messaging reliably](/learn/paths/reliability) (course)

[Get an implementation brief](/learn/workspace?topic=webhooks)