Mengirim gambar dan file di Apple Messages

Gunakan template Image atau Document untuk mengirim gambar produk, instruksi, atau tanda terima dalam percakapan pelanggan yang terbuka. Bird mengambil file sumber dan menyiapkannya untuk Apple selama pemrosesan pesan.

Siapkan file yang dapat diambil

Hosting file yang dimaksud di URL HTTPS publik yang dapat diambil tanpa cookie browser atau proses masuk. Gunakan file yang sesuai kebutuhan dan aman untuk diekspos di URL tersebut. Halaman pratinjau drive pribadi bukan URL file langsung.

Referensi send-message mendefinisikan batasan media:

Pastikan URL tetap tersedia selama pemrosesan berlangsung. URL bertanda tangan yang kedaluwarsa terlalu cepat dapat menyebabkan kegagalan setelah pesan diterima. Uji URL tanpa browser yang sudah masuk akun dan pastikan URL tersebut mengembalikan file sebenarnya, bukan halaman HTML.

Konfigurasi template

1. Buka Templates dan pilih New template > Image atau Document.
2. Di Content, beri draf sebuah Template name dan masukkan Message yang menjelaskan lampiran.
3. Di Apple delivery, atur Attachment URL, File name, dan Media type. Misalnya, PDF menggunakan nama file .pdf dan application/pdf.
4. Pilih bisnis di Personalization, lalu simpan draf.
5. Siapkan dan tinjau pesan, periksa pelanggan dan file yang sebenarnya sebelum mengirim.

Artwork pratinjau bawaan bukan sumber lampiran untuk pengiriman sesungguhnya. Masukkan URL yang Anda maksud secara eksplisit.

Unggah sekali dan gunakan ulang dengan attachment_id

Alur template di atas mengirim dengan source_url setiap kali, sehingga Bird mengambil file lagi pada setiap pengiriman. Jika Anda mengirim melalui API, Anda dapat mengunggah file sekali dengan Unggah lampiran lalu menggunakannya ulang pada pengiriman berikutnya, sehingga file tidak perlu diambil lagi.

Panggil POST /v1/amb/attachments dengan kunci API workspace yang memiliki amb:write, header Idempotency-Key yang wajib disertakan, dan isi permintaan dengan from (Apple Business ID bisnis pengirim) serta salah satu dari bagian file hingga 25.000.000 byte atau source_url hingga 99.999.999 byte. Respons mengembalikan id yang dimulai dengan aat_. Setiap panggilan mengunggah lampiran baru, bahkan untuk file yang pernah Anda unggah sebelumnya. Mengulang dengan Idempotency-Key yang sama mengembalikan hasil pertama tanpa mengunggah ulang, jadi gunakan kunci baru untuk setiap file yang ingin Anda unggah. Pada pengiriman berikutnya, atur content.attachments[].attachment_id ke ID tersebut, bukan source_url. Lampiran yang diterima membawa jenis ID yang sama: baca dari data.message.content.attachments[].attachment_id pada event webhook amb.received, lalu kirimkan kembali ke pelanggan tanpa mengunduh dan mengunggah ulang file itu sendiri.

expires_at pada lampiran adalah perkiraan Bird tentang kapan Apple berhenti menyimpan file, bukan jaminan: Apple mendokumentasikan ketersediaan sekitar 30 hari, yang diperbarui setiap kali pesan berikutnya menggunakan ulang referensi tersebut. Pengiriman dengan attachment_id yang expires_at-nya kurang dari 24 jam lagi ditolak sebelum mencapai Apple; jika itu terjadi, unggah file lagi atau kirim dengan source_url. Template tidak dapat menyimpan attachment_id, karena template berumur panjang, sedangkan ID lampiran tidak.

Periksa hasilnya

Periksa pesan yang telah dikirim beserta event-nya, lalu buka lampiran di perangkat uji Apple yang diotorisasi. Periksa keterbacaan, nama file, dan apakah konten tetap dapat dipahami tanpa konteks situs web di sekitarnya.

Jika pesan gagal setelah diterima, periksa error-nya sebelum mengubah template. Penyebab umum meliputi URL yang tidak dapat diakses, tipe media yang tidak sesuai, file yang melebihi batas ukuran, atau data PNG yang tidak valid. Mengubah ekstensi file tidak mengonversi formatnya.

Untuk mengunduh lampiran masuk di dasbor, pilih nama filenya di transkrip percakapan. Anda memerlukan akses baca ke Apple Messages di workspace.

Untuk mengambil file melalui API, gunakan Mengunduh lampiran dengan attachment_id dari content.attachments[] pesan, atau Mendapatkan lampiran pesan dengan data.message.id dari event webhook amb.received dan posisi berbasis nol dari lampiran dalam array content.attachments pesan tersebut. Dengan cara mana pun, autentikasikan dengan kunci API workspace yang memiliki amb:read; respons berisi byte file yang telah didekripsi. Unduh file begitu pesan tiba dan simpan salinan Anda sendiri, karena ketersediaan setelah masa retensi Apple tidak dijamin.