# Alat API dalam aliran

Alat API membolehkan langkah aliran bertanya kepada sistem anda sendiri (stok, harga, pesanan, invois) dan menjawab pelanggan dengan nilai sebenar. Anda tambah alat sekali, kemudian guna pada mana-mana langkah mesej, soalan atau syarat. Halaman ini menunjukkan cara menambah alat, menggunakannya pada langkah, dan menghantar dokumen yang dipulangkan sebagai fail.

## Menambah alat API

1. Buka **AI Knowledge Hub**, kemudian jubin **API tools**, dan pilih **Add API tool**.
2. Beri **Name** dan nyatakan dalam **What it looks up** apa yang dijawabnya.
3. Di bawah **Request**, masukkan alamat https. Letak pemboleh ubah seperti `{{order_no}}` dalam laluan atau query supaya diisi daripada apa yang dikumpul oleh aliran.
4. Tambah **Headers** yang diperlukan sistem anda, seperti kunci API. Nilainya disimpan secara tersulit.
5. Di bawah **Save to variables**, pilih nilai yang diperlukan langkah seterusnya, contohnya `invoice_no` ← `invoice_id`.
6. Jalankan **Test request** dengan nilai contoh, kemudian **Save**.

![Mengedit alat API: nama, permintaan, pemboleh ubah disimpan dan ujian](../../.gitbook/assets/guides/api-tool-editor.jpg){ width="460" }

## Menggunakan alat pada langkah

1. Dalam pereka bentuk aliran, buka langkah itu. Di bawah **Tool**, tetapkan **Tool type** kepada **API tool** dan pilih alat dalam **Select API tool**.
2. Panel menyenaraikan apa yang ia **Needs from earlier steps** dan apa yang ia **Saves for later steps**. Kumpul pemboleh ubah yang diperlukan sebelum langkah ini.
3. Tulis mesej langkah mengikut cara anda mahu jawapan dibaca; langkah itu mengisi nilai sebenar.

Setiap alat juga menyimpan `<tool>_status` (`ok`, `error` atau `missing_input`) dan `<tool>_http_code`, supaya syarat seterusnya boleh bercabang berdasarkannya.

| **If the request fails** | Apa yang pelanggan lihat |
| --- | --- |
| **Reply honestly and continue** | Bot memberitahu ia tidak dapat menyemak sekarang, tidak mereka nilai, dan aliran diteruskan |
| **Hand off to a human** | Bot memberitahu ia tidak dapat menyemak sekarang dan menyerahkan perbualan kepada pasukan anda |

![Bahagian Tool pada langkah mesej dengan alat API](../../.gitbook/assets/guides/api-tool-step-send-file.jpg){ width="315" }

## Menghantar dokumen sebagai fail

Apabila alat memulangkan pautan kepada dokumen, seperti invois atau resit, langkah **Send message** boleh menghantar dokumen itu sendiri dan bukan pautannya.

1. Di bawah alat API, tetapkan **Send a saved value as a file** kepada pautan yang disimpan, contohnya `invoice_url`.
2. Taip **File name**. Anda boleh guna nilai yang disimpan, seperti `Invoice {invoice_no}.pdf`. Nama kosong menghantar **Document.pdf**; nama tanpa sambungan diberi **.pdf**.

Pelanggan menerima mesej langkah, kemudian fail itu. Mesej tidak pernah menunjukkan pautan. Jika alat tidak memulangkan pautan, tiada fail dihantar dan bot memberitahu dokumen belum sedia. Kami menyimpan salinan (sehingga 10 MB), jadi pasukan anda masih boleh membukanya selepas pautan daripada sistem anda tamat tempoh.

WhatsApp, Messenger, Instagram, Telegram dan sembang web menerima fail. E-mel, SMS, TikTok, Line dan peti masuk API menerima pautan sebagai gantinya.

![Balasan Playground: mesej, kemudian invois sebagai fail PDF](../../.gitbook/assets/guides/api-tool-file-in-playground.jpg){ width="514" }

## Berkaitan

* [Membina aliran perbualan](/flow-agents/building-the-conversation-flow)
* [Rujukan pereka bentuk flow: setiap butang dan tetapan](/flow-agents/designer-reference)
* [Pesanan kedai dalam aliran](/flow-agents/store-orders-in-a-flow)
* [Menguji dan menyambungkan ejen](/flow-agents/testing-and-connecting-an-agent)

---
Source: https://help.mampuai.com/ms/flow-agents/api-tools-in-a-flow