Call API

Tutorial ini memandu Anda mendaftarkan sebuah API eksternal agar agent dapat memanggilnya secara otomatis selama percakapan. Di akhir tutorial, Anda akan memiliki API action yang berfungsi, tahu cara mengetesnya tanpa keluar dari qlar, dan memahami opsi lanjutan yang tersedia saat Anda membutuhkannya.

Bagaimana qlar Memanggil API Anda

qlar tidak mengharuskan Anda menulis kode apa pun untuk menghubungkan sebuah API. Sebaliknya, Anda mendeskripsikan API dalam bahasa biasa dan qlar meneruskan deskripsi tersebut ke model AI sebagai function tool. Berikut yang terjadi pada setiap giliran percakapan:

1. AI membaca pesan user dan memutuskan — berdasarkan deskripsi Anda — apakah perlu memanggil API untuk memberikan jawaban yang akurat.
2. qlar membuat HTTP request ke endpoint Anda, secara otomatis mengekstrak parameter yang diperlukan dari percakapan.
3. Server Anda merespons dengan data dalam format apa pun (JSON, plain text, dll.).
4. AI membaca response dan memadukannya ke dalam balasan berbahasa natural.

Siklus deteksi → API call → response berlangsung otomatis. Anda mendaftarkan API sekali; AI yang memutuskan kapan dan bagaimana menggunakannya.

Skenario yang Digunakan dalam Tutorial Ini

Agar konkret, tutorial ini menggunakan REST Countries — API publik gratis yang mengembalikan informasi tentang negara (ibu kota, mata uang, populasi, dan lainnya). Tidak diperlukan registrasi atau API key, sehingga Anda bisa langsung mengikuti dan menguji hasilnya.

Setelah Anda terbiasa dengan langkah-langkahnya, ganti dengan endpoint Anda sendiri.

Langkah 1 — Buka Custom API

Klik hamburger menu (☰) di pojok kiri atas untuk membuka sidebar. Buka Actions, lalu klik Custom API.

Halaman Custom API akan dimuat. Halaman ini menampilkan semua API action yang sudah terdaftar untuk agent ini.

Langkah 2 — Tambah API Baru

Klik tombol Add New API di bagian atas halaman. Sebuah sliding panel akan terbuka di sisi kanan layar dengan form konfigurasi kosong.

Langkah 3 — Isi Action Name dan Description

Bagian Basic Information adalah bagian terpenting. AI menggunakan name dan description untuk memutuskan kapan memanggil API ini, sehingga kejelasan di sini berpengaruh langsung pada kualitas integrasi.

Action Name

Ketik get_country_info pada field Action Name.

Tip: Gunakan snake_case dan buat nama yang singkat tetapi spesifik. Model AI membaca nama ini, jadi get_country_info lebih jelas daripada countries atau lookupCountry.

Description

Pada field Description, jelaskan apa yang dikembalikan API dan kapan ia harus dipanggil. Tulis seolah-olah Anda sedang memberi arahan kepada AI:

Mengambil informasi umum tentang sebuah negara berdasarkan nama, termasuk ibu kota, mata uang resmi, populasi, dan region. Panggil API ini ketika user bertanya tentang negara tertentu — misalnya "Ceritakan tentang Jepang" atau "Apa ibu kota Brasil?".

Langkah 4 — Atur HTTP Method dan Endpoint

Scroll ke bawah ke field HTTP Method dan Target URI.

1. Atur HTTP Method ke GET.
2. Pada Target URI, masukkan URL lengkap endpoint Anda: https://restcountries.com/v3.1/name/{country}

Catatan: {country} adalah path parameter — nilainya akan digantikan oleh nilai yang diekstrak AI dari percakapan. Anda akan mendefinisikannya sebagai property pada Langkah 7.

Langkah 5 — Konfigurasi Loading Text

Selama qlar menunggu API Anda merespons, ia dapat menampilkan pesan singkat kepada user.

1. Atur Loading Text Type ke Fixed.
2. Pada field Loading Text yang muncul, masukkan: Mencari informasi negara, mohon tunggu sebentar...

Tip: Buat loading text yang singkat dan berorientasi aksi. Teks ini hilang segera setelah API merespons. Lihat Tipe Loading Text untuk opsi dynamic, yang menghasilkan pesan kontekstual secara otomatis.

Langkah 6 — Lewati Authentication (Endpoint Publik)

Untuk skenario ini, endpoint bersifat publik. Biarkan Auth Type tetap none dan lanjutkan.

Jika API Anda memerlukan credential, lihat Opsi Authentication di bagian bawah halaman ini.

Langkah 7 — Tambah Parameter

Parameter memberi tahu AI nilai apa yang harus diekstrak dari percakapan dan diteruskan ke API Anda. Bahkan ketika sebuah parameter bersifat opsional di sisi API, mendeklarasikannya di sini memungkinkan AI meneruskan konteks dari user secara lebih akurat.

Klik Add New Property di bagian bawah section Properties. Sebuah baris property baru akan muncul.

Isi field-nya:

Tip: Property Description dibaca oleh AI. Deskripsi yang presisi — termasuk contoh nilai yang valid — mengurangi kemungkinan AI mengirim nilai yang tidak diharapkan (mis. kode negara alih-alih nama lengkap).

Tentang Location: path berarti nilainya disisipkan langsung ke dalam URL menggantikan {country}. Gunakan query untuk parameter yang ditambahkan sebagai ?key=value, dan body untuk payload pada POST request.

Langkah 8 — Tambah Rules (Opsional)

Field Rules memberi AI instruksi tentang cara menangani response API: apa yang harus dilakukan ketika data tidak ada, bagaimana menyusun output, atau batasan apa yang harus diterapkan.

Contoh rules untuk API ini:

Dari response API, ekstrak dan tampilkan hanya field berikut: common name, ibu kota, nama dan simbol mata uang resmi, populasi (diformat dengan pemisah ribuan), dan region. Jika negara tidak ditemukan, beri tahu user dengan sopan dan minta mereka memeriksa kembali ejaannya.

Biarkan field ini kosong untuk sementara jika Anda ingin tetap sederhana dan menambahkan rules nanti.

Langkah 9 — Simpan API ke Form

Klik tombol Add New API di bagian bawah sliding panel. API ditambahkan ke daftar pada halaman utama dan panel tertutup.

Catatan: API hanya disimpan ke form lokal. API belum aktif pada agent Anda.

Langkah 10 — Publikasikan Semua Perubahan

Klik Save all changes di bagian bawah halaman Custom API. Dialog konfirmasi akan muncul — klik Confirm untuk mempublikasikan.

Agent Anda kini memiliki akses ke get_country_info pada semua percakapan baru.

Langkah 11 — Tes API

Sebelum aktif, verifikasi bahwa qlar dapat menjangkau endpoint Anda dan response-nya terlihat benar.

1. Pada daftar API, temukan get_country_info dan klik ikon edit (pensil) untuk membuka kembali panel konfigurasinya.
2. Di pojok kiri bawah panel, klik Test API. Panel beralih ke Test Mode.
3. Pada field parameter country, ketik indonesia.
4. Klik Send Request.
5. Panel menampilkan HTTP response — status code dan body.

Response yang berhasil terlihat seperti ini (disingkat):

[
  {
    "name": { "common": "Indonesia", "official": "Republic of Indonesia" },
    "capital": ["Jakarta"],
    "currencies": { "IDR": { "name": "Indonesian rupiah", "symbol": "Rp" } },
    "population": 273523615,
    "region": "Asia"
  }
]

Jika response menampilkan data yang benar, API siap digunakan. Klik Back to Configuration untuk kembali ke form.

Tip: Coba beberapa negara berbeda (mis. japan, brazil, nonexistentcountry) untuk memastikan field Rules Anda menangani response yang valid maupun yang tidak ditemukan dengan benar.

Verifikasi dalam Percakapan

Buka panel live preview di sisi kanan halaman config mana pun dan kirim pesan yang seharusnya memicu API:

"Ceritakan tentang Indonesia."

atau

"Apa ibu kota Jepang?"

Loading text (Mencari informasi negara, mohon tunggu sebentar...) akan muncul sebentar, diikuti oleh response yang memadukan data negara tersebut.

Fitur Lanjutan

Langkah-langkah di atas mencakup setup yang paling umum. Section di bawah menjelaskan fitur yang mungkin Anda butuhkan seiring integrasi Anda berkembang.

Import API dari Schema OpenAPI

Alih-alih menambahkan action satu per satu, Anda dapat mendaftarkan beberapa sekaligus dari definisi OpenAPI (Swagger) yang sudah ada.

1. Pada halaman Custom API, klik Import OpenAPI Schema. Sebuah modal akan terbuka.
2. Atur Schema Format ke JSON atau YAML.
3. Sediakan schema dengan salah satu dari dua cara:
   • Tempel (paste) langsung ke editor Paste your OpenAPI schema here, atau
   • Klik Choose File untuk mengunggah file .json, .yaml, atau .yml. Isi file otomatis mengisi editor, dan Schema Format dideteksi dari ekstensi file.
4. Klik Convert Schema, lalu konfirmasi. qlar mem-parsing schema dan menambahkan satu API action per operation ke daftar Anda.

Catatan: API hasil import ditambahkan tanpa authentication. Setelah import, konfigurasikan credential — baik per API (lihat Opsi Authentication) maupun untuk banyak API sekaligus (lihat Set Authentication untuk Beberapa API Sekaligus). Import hanya memperbarui form lokal; klik Save all changes untuk mempublikasikan.

Set Authentication untuk Beberapa API Sekaligus

Ketika beberapa API berbagi credential yang sama — misalnya semua action yang baru saja Anda import dari satu schema OpenAPI mengarah ke backend yang sama — Anda dapat mengonfigurasi authentication sekali dan menerapkannya ke semuanya dalam satu langkah.

1. Pada halaman Custom API, klik Set Authentication. Sebuah sliding panel akan terbuka.
2. Konfigurasikan authentication persis seperti yang Anda lakukan untuk satu API — pilih Auth Type (none, bearer, basic, custom, atau oauth) dan isi field yang diperlukan. Lihat Opsi Authentication.
3. Di bawah Select APIs to update, centang API yang akan menerima authentication ini. API dikelompokkan berdasarkan category, jadi Anda dapat menggunakan Select All, Clear All, atau kontrol per-grup Select group / Clear group. Header menampilkan berapa banyak API yang sedang dipilih.
4. Klik OK. Dialog konfirmasi memberi tahu berapa banyak API yang akan berubah dan memperingatkan bahwa authentication mereka saat ini akan ditimpa. Klik Confirm untuk menerapkan.
5. Klik Save all changes pada halaman Custom API untuk mempublikasikan.

Catatan: Tindakan ini menimpa authentication yang ada pada setiap API yang dipilih. API yang tidak Anda pilih tidak akan diubah.

Opsi Authentication

qlar mendukung lima metode authentication. Pilih Auth Type pada section Authentication dan field yang diperlukan akan muncul.

Untuk bearer, masukkan token pada field Key. Untuk basic, masukkan Username dan Password. Untuk custom, masukkan Header Name (mis. X-API-Key) dan nilai Key. Untuk oauth, pilih tipe provider, masukkan Token URL, dan sediakan credential untuk grant type Anda.

Response Prompt

Field Response Prompt menjelaskan secara persis bagaimana AI harus menyajikan hasil API kepada user — tone, format, dan tingkat detail. Ini terpisah dari Rules, yang mengatur bagaimana AI menafsirkan data mentah.

Contoh untuk Brew:

Sajikan menu spesial dengan tone yang ramah dan percakapan. Format setiap item sebagai bullet point dengan nama dan harga. Akhiri dengan ajakan untuk menanyakan detail lebih lanjut tentang item mana pun.

Send Metadata

Ketika Send Metadata diaktifkan, qlar menambahkan konteks percakapan ke setiap request. Gunakan ini ketika API Anda perlu mempersonalisasi response berdasarkan identitas atau channel user.

Additional Properties

Secara default, AI dibatasi pada parameter yang Anda definisikan di section Properties. Mengaktifkan Additional Properties memungkinkan AI meneruskan pasangan key-value tambahan di luar yang tercantum secara eksplisit — berguna untuk kontrak API yang fleksibel atau dinamis.

Tipe Loading Text

dynamic berguna ketika satu API action digunakan dalam konteks berbeda dan teks fixed yang generik akan terasa kurang pas.

Halaman Terkait

• Automate with Custom API — rangkai beberapa API call dan bangun workflow otomatis
• Automate with Plugins — gunakan integrasi plugin siap pakai alih-alih mengonfigurasi API mentah
• Observe Feedback and Logs — pantau API call dan debug response di production