Lampiran & tag

Melampirkan file

Unggah setiap file terlebih dahulu, lalu kirim id-nya bersama pesan.

POST /attachments
x-lex-client: aplikasi-saya
Content-Type: application/json

{ "name": "laporan-q3.pdf", "mediaType": "application/pdf", "data": "<base64>" }

{ "id": "att_1", "name": "laporan-q3.pdf", "mediaType": "application/pdf", "size": 182044, "createdAt": "…" }

POST /agent-runs
{ "botId": "bot_123", "message": "Apa tiga risiko terbesar di laporan ini?", "attachmentIds": ["att_1"] }

Jenis	Gambar (image/png, image/jpeg, image/gif, image/webp), PDF (application/pdf), dan teks (text/*, JSON, YAML, XML, SQL, kode)
Ukuran	Maksimal 10 MB per file
Per pesan	Maksimal 5 file

Model membaca gambar dan PDF secara langsung, dan file teks sebagai teks. Setiap file hanya bisa dikirim bersama satu pesan; memakainya lagi gagal dengan VALIDATION_FAILED.

• GET /attachments/{id}/content mengunduh file. Hanya pemiliknya yang bisa. Gambar ditampilkan inline; file lain selalu diunduh, sehingga tidak pernah tampil sebagai halaman web.
• DELETE /attachments/{id} menghapus file yang belum dikirim.
• Pesan yang terkirim mencantumkan file-nya: GET /conversations/{id}/messages menyertakan attachments: [{ id, name, mediaType, size }].

Men-tag connector, plugin, dan Mini Program

Arahkan bot ke kapabilitas tertentu dengan mentions:

POST /agent-runs
{
  "botId": "bot_123",
  "message": "Rangkum email saya yang belum dibaca",
  "mentions": [{ "type": "connector", "ref": "gmail", "name": "Gmail" }]
}

type	ref
connector	Slug connector, misalnya gmail (dari GET /catalog/connectors)
plugin	Id plugin (dari GET /catalog/plugins)
mini_program	Slug Mini Program (dari GET /catalog/mini-programs)

Maksimal 10 tag per pesan. Tool dari connector yang di-tag selalu ditawarkan ke bot untuk pesan itu, lebih dulu dari yang lain.

Ketika ada yang belum disiapkan

Kalau connector yang di-tag belum terhubung, atau plugin yang di-tag belum terpasang, bot tidak langsung bekerja. Bot langsung membalas tanpa memakai kuota model, dan meminta Anda menyiapkannya dulu. Run selesai dengan stopReason: "needs_setup", dan pesan balasannya membawa actions:

{
  "role": "assistant",
  "content": "Before I start, I need you to connect Gmail. Shall we do that now? …",
  "actions": [{ "kind": "connect", "type": "connector", "ref": "gmail", "name": "Gmail" }]
}

Tampilkan tombol untuk setiap aksi:

• connect: jalankan alur connect untuk ref. Sertakan returnTo agar setelah login pengguna kembali ke chat Anda.
• install: pasang plugin dengan POST /plugin-installations (owner dan admin workspace).

Setelah semuanya siap, kirim pesan lanjutan seperti "Gmail sudah siap. Silakan lanjutkan." dengan mentions yang sama; bot akan melanjutkan permintaan awal dari chat. Untuk lanjut tanpa salah satunya, kirim pesan tanpa tag tersebut.

Mini Program tidak pernah perlu disiapkan.