Menghubungkan API Anda
Buka di CMSTutorial ini memandu Anda mendaftarkan sebuah API eksternal agar agent dapat memanggilnya secara otomatis selama percakapan. Anda memberi Atlas, asisten operasional Kirana Group, akses ke data proyek yang selalu terkini: saat seseorang bertanya "What is the status of KG-2041?", Atlas memanggil Projects API milik Kirana dan menjawab dengan status, tahap approval, progres, dan anggaran. Di akhir tutorial, Anda memiliki API action yang berfungsi, tahu cara mengetesnya tanpa keluar dari qlar, dan tahu opsi lanjutan apa saja yang tersedia saat dibutuhkan.
Sebelum memulai
- Agent Anda sudah menjawab dengan benar dari knowledge-nya sendiri. Jika belum, mulai dari Mengajari Agent Anda.
- Anda sudah tahu cara menguji dan mem-publish perubahan. Lihat Preview dan Publish Perubahan.
- Anda memiliki URL API yang ingin dipanggil, beserta credential-nya jika diperlukan. Untuk tutorial ini Anda hanya butuh akses internet: API contohnya adalah sampel publik yang hanya bisa dibaca.
- Mencari integrasi siap pakai? Periksa Using Plugins terlebih dahulu.
Bagaimana qlar Memanggil API Anda
qlar tidak mengharuskan Anda menulis kode apa pun untuk menghubungkan sebuah API. Anda cukup mendeskripsikan API dalam bahasa biasa, lalu qlar meneruskan deskripsi tersebut ke model AI sebagai function tool. Berikut yang terjadi pada setiap giliran percakapan:
- AI membaca pesan user dan memutuskan, berdasarkan deskripsi Anda, apakah perlu memanggil API untuk memberi jawaban yang akurat.
- qlar membuat HTTP request ke endpoint Anda, dengan mengisi parameter yang diambil dari percakapan.
- Server Anda merespons dengan data dalam format apa pun (JSON, plain text, dan sebagainya).
- AI membaca response dan mengubahnya menjadi balasan berbahasa natural.
Siklus ini berjalan otomatis. Anda mendaftarkan API sekali; AI yang memutuskan kapan dan bagaimana menggunakannya.
Skenario yang Digunakan dalam Tutorial Ini
Kirana menyimpan status setiap proyek di Projects API. Tutorial ini memakai sampel publik dari API tersebut yang hanya bisa dibaca, sehingga Anda bisa langsung mengikuti dan menguji hasilnya. Sampel ini mengenal tiga proyek:
| Kode proyek | Proyek |
|---|---|
KG-2041 | Surabaya warehouse expansion |
KG-2052 | Jakarta head office fit-out |
KG-2063 | Bekasi rooftop solar |
Kode lain akan mengembalikan HTTP 404 Not Found.
| Field | Nilai |
|---|---|
| Nama action | get_project_status |
| Tujuan | Mengembalikan status, progres, anggaran, dan tahap approval saat ini dari satu proyek |
| Endpoint | GET https://stpusakaappassetprod.blob.core.windows.net/docs-media/samples/kirana-api/projects/{projectCode}.json |
| Parameter | projectCode, kode proyek, misalnya KG-2041 |
| Authentication | None |
Setelah Anda terbiasa dengan langkah-langkahnya, ganti dengan endpoint Anda sendiri.
Langkah 1: Buka Custom API
Arahkan pointer ke sidebar ikon di tepi kiri CMS untuk membukanya (di layar sempit, klik tombol menu (☰) di kiri atas). Buka Tools, lalu klik Custom API.
Halaman Custom API akan dimuat. Di bagian atas ada tombol Add API dan tombol More actions (tiga titik). More actions berisi Categories, Set authentication, dan Import OpenAPI schema. Di bawahnya ada daftar API action yang sudah terdaftar untuk agent ini.
Langkah 2: Tambah API Baru
Klik Add API. Drawer New API muncul dari kanan dengan empat bagian: Basics, How the agent uses it, Authentication, dan Parameters. Screenshot berikut menunjukkan panel setelah tutorial ini selesai; langkah-langkah berikutnya mengisinya bagian demi bagian.

Langkah 3: Isi Action name dan Description
Bagian Basics adalah bagian terpenting. AI menggunakan nama dan deskripsi untuk memutuskan kapan memanggil API ini, jadi kejelasan di sini berpengaruh langsung pada kualitas integrasi.
Action name
Ketik get_project_status pada field Action name.
Tip: Gunakan
snake_casedan buat nama yang singkat tetapi spesifik. Model AI membaca nama ini, jadiget_project_statuslebih jelas daripadaprojectsataulookup.
Description
Pada field Description, jelaskan apa yang dikembalikan API dan kapan ia harus dipanggil. Tulis seolah-olah Anda sedang memberi arahan kepada AI. Untuk Atlas, deskripsinya ditulis dalam bahasa Inggris:
Returns the status, progress, budget and current approval stage of one Kirana Group project. Call it when the user asks about a project by its code, for example "What is the status of KG-2041?".

Langkah 4: Atur HTTP Method dan Endpoint
-
Atur HTTP Method ke
GET. -
Pada Target URI, masukkan URL lengkap endpoint:
https://stpusakaappassetprod.blob.core.windows.net/docs-media/samples/kirana-api/projects/{projectCode}.json
Catatan:
{projectCode}adalah path parameter. qlar menggantinya dengan nilai yang diambil AI dari percakapan, jadi "What is the status of KG-2041?" memanggil.../projects/KG-2041.json. Anda mendefinisikan parameter ini sebagai property pada Langkah 8.
Langkah 5: Konfigurasi Loading text
Selama qlar menunggu API Anda merespons, ia menampilkan pesan singkat kepada user. API baru dimulai dengan Loading text type bernilai Auto.
-
Atur Loading text type ke Fixed.
-
Pada field Loading text yang muncul, masukkan:
Checking the project status...
Tip: Buat loading text yang singkat dan berorientasi aksi. Teks ini hilang begitu jawaban datang. Lihat Tipe Loading Text untuk opsi lainnya.
Langkah 6: Tambah Rules dan Response Prompt
Kedua field ini opsional, tetapi membuat jawaban jauh lebih andal.
Rules memberi tahu AI cara menafsirkan response: apa yang dipakai, dan apa yang dilakukan jika ada yang tidak ditemukan. Masukkan:
Use only the fields in the response. If the project is not found (HTTP 404), say that the code is unknown and ask the user to check it (codes look like KG-2041).
Response Prompt memberi tahu AI cara menyajikan hasilnya. Masukkan:
Start with the status and the current approval stage, then progress, budget spent versus total, and the latest update. Keep it under six lines.
Biarkan Accept extra parameters dan Send conversation details nonaktif. Keduanya dijelaskan di Fitur Lanjutan.
Langkah 7: Lewati Authentication (Endpoint Publik)
Endpoint sampel bersifat publik. Pada bagian Authentication, biarkan Authentication type tetap None dan lanjutkan.
Jika API Anda sendiri memerlukan credential, lihat Opsi Authentication di bagian bawah halaman ini.
Langkah 8: Tambah Parameter
Parameter memberi tahu AI nilai apa yang harus diambil dari percakapan dan diteruskan ke API Anda. Pada bagian Parameters, klik Add parameter. Sebuah kartu parameter baru muncul, berjudul Parameter 1. Isi seperti berikut:
| Field | Nilai |
|---|---|
| Name | projectCode |
| Type | String |
| Location | Path |
| Required | Aktif |
| Allowed values | Biarkan kosong |
| Description | Kirana project code in the form KG-0000, for example KG-2041. Use upper case. |

Tip: Description dibaca oleh AI. Deskripsi yang presisi dengan contoh nilai yang valid mengurangi kemungkinan AI mengirim nilai yang tidak diharapkan, misalnya
kg 2041alih-alihKG-2041.
Tentang Location: Path berarti nilainya menggantikan
{projectCode}di URL. Gunakan Querystring untuk parameter yang ditambahkan sebagai?key=value, Header untuk nilai yang dikirim sebagai HTTP header, dan Body untuk payload pada requestPOST. Allowed values membatasi property pada daftar nilai tertentu: ketik sebuah nilai lalu tekan Enter untuk menambahkannya.
Langkah 9: Tambahkan API ke Daftar
Klik Add API di footer drawer. Drawer tertutup dan get_project_status muncul di daftar, lengkap dengan endpoint-nya, chip None di kolom Authentication, switch On, dan menu Row actions.

Catatan: Sejauh ini API baru ada di form. API belum tersimpan.
Langkah 10: Simpan Semua Perubahan
Klik Save all changes di bagian bawah halaman Custom API. CMS bertanya Are you sure to save your changes? Klik Yes. Sebuah pesan mengonfirmasi Custom APIs saved.
Perubahan disimpan sebagai draft. Anda bisa langsung mencoba get_project_status di preview, dan pengguna sungguhan baru mendapatkannya setelah Anda mengklik Publish di bar atas.
Langkah 11: Tes API
Sebelum mencobanya dalam percakapan, pastikan qlar bisa menjangkau endpoint dan response-nya terlihat benar.
- Pada daftar, klik baris
get_project_statusuntuk membuka drawer-nya kembali. - Di footer drawer, klik Test API. Jika ada perubahan yang belum diterapkan, Test API nonaktif; terapkan dulu perubahannya. Drawer berubah menjadi Test API: get_project_status dan menampilkan bagian API (HTTP method, authentication, endpoint, dan description).
- Di bawah Parameters, ketik
KG-2041pada Project Code. - Klik Call API.
- Di bawah Response, muncul badge
200 OK, diikuti Body. Buka Response headers untuk melihat header-nya.
Response body untuk KG-2041 terlihat seperti ini:
{
"projectCode": "KG-2041",
"name": "Surabaya warehouse expansion",
"site": "Surabaya",
"projectManager": "Dewi Lestari",
"status": "Delayed",
"percentComplete": 62,
"budgetUsd": 2500000,
"spentUsd": 1480000,
"approval": {
"stage": "Regional Director",
"waitingSince": "2026-09-29",
"nextApprover": "CFO"
},
"latestUpdate": "Steel delivery slipped two weeks; new completion date 15 December 2026.",
"plannedCompletion": "2026-11-30",
"forecastCompletion": "2026-12-15"
}

Klik Back to editing untuk kembali ke form.
Tip: Coba juga
KG-9999. Anda akan mendapat404, yaitu kasus yang ditangani Rules Anda: Atlas harus mengatakan bahwa kode tersebut tidak dikenal dan meminta user memeriksanya.
Periksa hasilnya
Pada panel preview di kanan, klik tombol reload untuk memulai percakapan baru, lalu tanyakan:
What is the status of project KG-2041?
Loading text Checking the project status... muncul sebentar. Lalu Atlas menjawab sesuai susunan Response Prompt Anda:
- Status: Delayed, approval berada di tahap Regional Director; approver berikutnya: CFO.
- Progress: 62% selesai.
- Budget: US$1.48M terpakai dari US$2.5M.
- Latest update: pengiriman baja mundur dua minggu; perkiraan selesai 15 Desember 2026.

Lalu tanyakan kode yang tidak ada, misalnya "And KG-9999?". Atlas harus mengatakan bahwa kode tersebut tidak dikenal dan meminta Anda memeriksanya, bukan mengarang sebuah proyek.
Jika jawabannya belum sesuai:
- Atlas menjawab tanpa memanggil API. Buat Description lebih spesifik tentang kapan API harus dipanggil, dan pastikan switch On API di daftar aktif.
- Atlas mengatakan proyek tidak ditemukan untuk kode yang valid. Buka Test API dan panggil dengan kode yang sama.
404biasanya berarti kode sampai ke API dalam bentuk yang salah; perjelas Description.
Jika jawabannya sudah sesuai, klik Publish agar pengguna sungguhan mendapatkan API baru ini. Lihat Preview dan Publish Perubahan.
Fitur Lanjutan
Langkah-langkah di atas mencakup setup yang paling umum. Bagian di bawah ini 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. Buka More actions, lalu klik Import OpenAPI schema dan ikuti empat langkah wizard-nya (Upload, Edit, Review, Done). Lihat Import OpenAPI schema untuk panduan lengkap dengan schema sampel Kirana.
Set authentication untuk Beberapa API Sekaligus
Ketika beberapa API berbagi credential yang sama, misalnya semua action hasil import dari satu schema, buka More actions lalu klik Set authentication untuk mengonfigurasi authentication sekali. Centang API yang Anda inginkan (atau satu grup), lalu klik Apply to N APIs. Lihat Mengatur Autentikasi.
Opsi Authentication
Pilih Authentication type pada bagian Authentication dan field yang diperlukan akan muncul.
| Authentication type | Kapan digunakan |
|---|---|
| None | Endpoint publik, tidak perlu credential |
| Bearer | API yang diamankan dengan Bearer token statis |
| Basic | API yang menggunakan username dan password |
| Custom | API dengan nama header kustom (misalnya X-API-Key) |
| Oauth | API yang diamankan dengan OAuth 2.0 (Client Credentials atau Google Service Account) |
Untuk Bearer, masukkan token pada field Token.
Untuk Basic, masukkan Username dan Password.
Untuk Custom, masukkan Header name (misalnya 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 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 Atlas:
Start with the status and the current approval stage, then progress, budget spent versus total, and the latest update. Keep it under six lines.
| Field | Mengatur |
|---|---|
| Rules | Bagaimana AI memproses dan membatasi response API (logika, fallback) |
| Response Prompt | Bagaimana AI memformat dan menyampaikan hasil ke user (tone, struktur) |
Send conversation details
Ketika Send conversation details aktif, qlar melampirkan konteks percakapan dan identitas ke setiap request yang dikirim ke API Anda. Gunakan ini ketika API Anda perlu mempersonalisasi response berdasarkan identitas user, channel, atau permission.
Metadata selalu dikirim sebagai HTTP header, dan juga disertakan di query string (untuk GET/DELETE) atau di JSON request body (untuk POST/PUT/PATCH), tergantung HTTP Method action tersebut.
Selalu dikirim sebagai header
| Header | Deskripsi |
|---|---|
X-AgentId | ID agent yang menangani percakapan |
X-UserId | Identifier unik user yang sedang chatting |
X-UserEmail | Email user yang sedang chatting (string kosong jika tidak tersedia) |
X-InquiryMessageId | ID pesan yang memicu API call |
X-MediaType | Channel tempat user berada (web, WhatsApp, dll.) |
X-TargetAgentId | ID target agent, jika percakapan di-handoff |
X-MessengerAccount-Product | Produk messenger yang digunakan, hanya dikirim jika tersedia |
X-MessengerAccount-AccountCode | Kode akun messenger spesifik, hanya dikirim jika tersedia |
X-User-Permissions | Array JSON berisi permission user, hanya dikirim jika tidak kosong |
Juga dikirim di query string, untuk GET/DELETE
| Query parameter | Nilai sama dengan |
|---|---|
agentId | X-AgentId |
userId | X-UserId |
userEmail | X-UserEmail |
inquiryMessageId | X-InquiryMessageId |
mediaType | X-MediaType |
targetAgentId | X-TargetAgentId |
Catatan: field messenger account dan user permissions hanya tersedia lewat header di atas untuk request
GET/DELETE. Keduanya tidak ditambahkan ke query string.
Juga dikirim di JSON body, untuk POST/PUT/PATCH
Sebuah object metadata ditambahkan bersama body parameter yang Anda definisikan:
{
"metadata": {
"AgentId": "...",
"UserId": "...",
"UserEmail": "...",
"InquiryMessageId": "...",
"MediaType": "...",
"TargetAgentId": "...",
"MessengerAccount": { "Product": "...", "AccountCode": "..." },
"UserPermissions": ["..."]
}
}
Catatan: berbeda dari header dan query string di atas, field di dalam object
metadatapada body menggunakan PascalCase (misalnyaAgentId, bukanagentId).MessengerAccountbernilainulljika user tidak berada di channel messenger.
Contoh Implementasi Server
Contoh di bawah ini menunjukkan server yang Anda buat sendiri untuk menerima panggilan dari qlar. Projects API sampel yang dipakai sebelumnya hanyalah kumpulan file statis dan tidak memerlukan kode server sama sekali. Skenario di sini adalah action order_status sederhana: diberikan sebuah orderId, server mencari dan mengembalikan status pengiriman order tersebut. Authentication menggunakan Authentication type: Custom, dengan header bernama X-Api-Key.
Gunakan kontrol di bawah untuk melihat bagaimana request dan kode server berubah berdasarkan HTTP Method, Send conversation details, dan Media Type:
Sample request qlar sends
POST /api/order-status HTTP/1.1
Content-Type: application/json
X-Api-Key: sk_live_abc123
X-AgentId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
X-UserId: user_8231
X-UserEmail:
X-InquiryMessageId: msg_9f21
X-MediaType: web
X-TargetAgentId:
X-User-Permissions: []
{
"orderId": "ORD-1001",
"metadata": {
"AgentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"UserId": "user_8231",
"UserEmail": "",
"InquiryMessageId": "msg_9f21",
"MediaType": "web",
"TargetAgentId": "",
"MessengerAccount": null,
"UserPermissions": []
}
}Server implementation
const express = require("express");
const app = express();
app.use(express.json());
const API_KEY_HEADER = "x-api-key";
const API_KEY = process.env.CUSTOM_API_KEY; // must match the "Key" set in CMS Auth Type: custom
const ORDERS = {
"ORD-1001": { status: "shipped", carrier: "JNE", eta: "2026-08-02" },
};
app.post("/api/order-status", (req, res) => {
// 1. Verify the custom auth header configured in CMS (Auth Type: custom)
if (req.get(API_KEY_HEADER) !== API_KEY) {
return res.status(401).json({ error: "Invalid or missing API key" });
}
// 2. Read the declared parameter
const { orderId } = req.body;
if (!orderId) return res.status(400).json({ error: "orderId is required" });
// Metadata is always sent as headers (also duplicated in the query string for
// GET/DELETE, or under "metadata" in the JSON body for POST/PUT/PATCH)
const agentId = req.get("X-AgentId");
const userId = req.get("X-UserId");
const inquiryMessageId = req.get("X-InquiryMessageId");
const mediaType = req.get("X-MediaType"); // "web" | "whatsapp" | ...
const userPermissions = JSON.parse(req.get("X-User-Permissions") || "[]");
console.log("Call from agent " + agentId + ", user " + userId + ", channel " + mediaType);
// 3. Look up the order
const order = ORDERS[orderId];
if (!order) return res.status(404).json({ error: "Order " + orderId + " not found" });
// Personalise the response by channel when metadata is available
if (mediaType === "whatsapp") {
// Keep WhatsApp replies short; no rich formatting
return res
.status(200)
.send("Order " + orderId + " is " + order.status + " via " + order.carrier + ", arriving " + order.eta + ".");
}
return res.status(200).json({ orderId, ...order });
});
app.listen(3000, () => console.log("Listening on :3000"));
Catatan:
Media Typehanya mengubah contoh nilai yang ditampilkan di atas. Kode server sendiri membacaX-MediaTypesaat runtime dan sudah menanganiwebmaupun
Accept extra parameters
Secara default, AI dibatasi pada parameter yang Anda definisikan di bagian Parameters. Mengaktifkan Accept extra parameters memungkinkan AI meneruskan pasangan key-value tambahan di luar yang tercantum secara eksplisit. Ini berguna untuk kontrak API yang fleksibel atau dinamis.
Category dan Switch Aktif/Nonaktif
Buka More actions, klik Categories, lalu Add category untuk mengelompokkan API yang saling berkaitan di daftar, misalnya Projects dan Procurement. API tanpa category ditampilkan di bawah Uncategorized. Seret baris lewat handle-nya untuk mengubah urutan.
Setiap baris punya switch On. Nonaktifkan untuk menghentikan agent memakai API tersebut tanpa menghapus konfigurasinya. Seperti semua perubahan di halaman ini, perubahan berlaku setelah Save all changes (dan Publish untuk pengguna sungguhan).
Tipe Loading Text
| Tipe | Perilaku |
|---|---|
| Auto | Default. AI menulis pesan loading singkat yang sesuai dengan request saat itu. |
| None | Tidak ada pesan loading yang ditampilkan ke user. |
| Fixed | Teks persis yang Anda masukkan di Loading text ditampilkan setiap kali. |
| Dynamic | AI menulis pesan loading, dipandu instruksi yang Anda masukkan di Loading text prompt. |
Fixed memberi Anda kendali penuh atas kalimatnya. Dynamic berguna ketika satu API action dipakai dalam konteks berbeda dan satu teks tetap akan terasa kurang pas.
Langkah berikutnya
- Berikutnya dalam alur: Import OpenAPI schema, untuk mendaftarkan banyak API action sekaligus dari spec yang sudah ada.
- Mengatur Autentikasi: terapkan credential yang sama ke banyak API dalam satu langkah.
- Menghubungkan MCP Server: hubungkan server yang menyediakan banyak tool lewat satu koneksi.
- Analytics and Logs: pantau API call dan debug response di production.