CHAINHULK Developers
Website Workspace
Dokumentasi/Lampiran dan berkas

Lampiran dan berkas

Unggah lampiran privat, masukkan ke antrean pesan, lalu baca dengan izin workspace.

Unggah berkas ke percakapan

POST /api/v1/workspaces/{workspace_id}/conversations/{conversation_id}/files menerima multipart dengan tepat satu field file dan header Idempotency-Key sepanjang 8–128 karakter. Scope messages:send diperlukan. Permintaan baru mengembalikan 201; unggahan identik dengan key dan metadata yang sama mengembalikan 200. Isi atau metadata berbeda dengan key yang sama menghasilkan 409.

curl -X POST \
  https://app.chainhulk.com/api/v1/workspaces/WORKSPACE_ID/conversations/CONVERSATION_ID/files \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 686c86ab-9d6c-4da2-9ecd-7365bbab16ad" \
  -F "file=@dokumen.pdf"

Respons berisi file.id, filename, mime_type, kind, byte_size, sha256, dan status. Berkas hanya siap dikirim setelah status ready. Unggahan belum mengirim pesan messenger. Draf yang belum terikat pada pesan hanya dapat dibaca oleh pembuatnya.

Kirim dengan caption opsional

{
  "file_id": "FILE_ID",
  "content": "Dokumen yang Anda minta."
}

Gunakan body tersebut pada POST /conversations/{conversation_id}/messages dengan Idempotency-Key baru. Satu pesan menerima paling banyak satu file_id dari percakapan dan pembuat unggahan yang sama. Caption dibatasi 1.024 karakter. Tanpa lampiran, content wajib diisi. Setelah terikat pada pesan, berkas tidak dapat dipindahkan atau dipakai ulang dalam pesan lain. Respons 202 mengonfirmasi penerimaan antrean, bukan keberhasilan pengiriman provider.

Baca dan unduh secara privat

  • GET /files/{file_id} mengembalikan metadata dan memerlukan chats:read.
  • GET atau HEAD /files/{file_id}/content membaca berkas. Scope chats:read, keanggotaan aktif, atau persetujuan dukungan yang berlaku tetap diperiksa sebelum respons 200, 206, atau 304.
  • Range menerima satu rentang byte. Rentang ganda atau tidak tersedia menghasilkan 416. If-None-Match dan If-Range mendukung ETag SHA-256 berkas.
  • Tambahkan ?download=1 untuk mengunduh media. Dokumen selalu dikirim sebagai unduhan dengan sandbox dan nosniff. Tidak ada URL bucket publik atau kredensial penyimpanan dalam respons.

Penerimaan dan pemulihan media

Descriptor media provider disimpan terenkripsi sebelum webhook dikonfirmasi. Pengunduhan berjalan di latar belakang. Pesan dapat terlihat saat lampiran masih pending. Jika transfer gagal karena source_unavailable, storage_unavailable, atau storage_limit, POST /files/{file_id}/retry dengan messages:send memasukkannya kembali ke antrean unduhan. Tindakan tersebut tidak mengirim ulang pesan messenger.

  • Batas unggahan CHAINHULK adalah 64 MiB; Telegram Bot API menerima unggahan hingga 50 MiB. Unduhan masuk melalui Telegram Bot API dibatasi 20 MiB.
  • Gambar raster yang dapat dikenali dapat ditampilkan sebagai gambar. Format lain tetap menjadi dokumen unduhan. Pengiriman sebagai dokumen mempertahankan isi dan caption bila format tidak mendukung media native.
  • Media sekali lihat dan media pesan sementara WhatsApp tidak diunduh. Status rejected menjelaskan keterbatasannya.
  • DELETE /files/{file_id} membuang draf yang belum terikat pada pesan dan dimiliki pembuatnya. Draf kedaluwarsa setelah 24 jam; berkas draf yang dihapus dijadwalkan untuk pembersihan fisik setelah tujuh hari. Salinan backup mengikuti retensi backup.
  • Pengaturan penyimpanan baru berlaku bagi berkas baru. Berkas lama tetap menggunakan lokasi yang dicatat saat disimpan.