Menghubungkan API Anda

Buka di CMS

Tutorial 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:

  1. AI membaca pesan user dan memutuskan, berdasarkan deskripsi Anda, apakah perlu memanggil API untuk memberi jawaban yang akurat.
  2. qlar membuat HTTP request ke endpoint Anda, dengan mengisi parameter yang diambil dari percakapan.
  3. Server Anda merespons dengan data dalam format apa pun (JSON, plain text, dan sebagainya).
  4. 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 proyekProyek
KG-2041Surabaya warehouse expansion
KG-2052Jakarta head office fit-out
KG-2063Bekasi rooftop solar

Kode lain akan mengembalikan HTTP 404 Not Found.

FieldNilai
Nama actionget_project_status
TujuanMengembalikan status, progres, anggaran, dan tahap approval saat ini dari satu proyek
EndpointGET https://stpusakaappassetprod.blob.core.windows.net/docs-media/samples/kirana-api/projects/{projectCode}.json
ParameterprojectCode, kode proyek, misalnya KG-2041
AuthenticationNone

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.

Header drawer New API dan bagian Basics terisi untuk get_project_status: Action name, Description, HTTP method GET dan Target URI

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_case dan buat nama yang singkat tetapi spesifik. Model AI membaca nama ini, jadi get_project_status lebih jelas daripada projects atau lookup.

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?".
Grup Basics dan How the agent uses it pada drawer New API: Action name get_project_status, Description, HTTP method GET, Target URI, Loading text type Fixed dengan Loading text Checking the project status..., Rules, Response prompt, serta switch Accept extra parameters dan Send conversation details yang mati

Langkah 4: Atur HTTP Method dan Endpoint

  1. Atur HTTP Method ke GET.

  2. 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.

  1. Atur Loading text type ke Fixed.

  2. 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:

FieldNilai
NameprojectCode
TypeString
LocationPath
RequiredAktif
Allowed valuesBiarkan kosong
DescriptionKirana project code in the form KG-0000, for example KG-2041. Use upper case.
Grup Parameters dengan Parameter 1: Name projectCode, Type String, Location Path, Allowed values kosong, Description Kirana project code in the form KG-0000, for example KG-2041. Use upper case., Required aktif, dan tombol Add parameter

Tip: Description dibaca oleh AI. Deskripsi yang presisi dengan contoh nilai yang valid mengurangi kemungkinan AI mengirim nilai yang tidak diharapkan, misalnya kg 2041 alih-alih KG-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 request POST. 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.

Halaman Custom API dengan kotak Search APIs, tombol More actions dan Add API, grup Uncategorized dengan satu baris get_project_status yang menampilkan chip GET, endpoint, dan chip autentikasi None

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.

  1. Pada daftar, klik baris get_project_status untuk membuka drawer-nya kembali.
  2. 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).
  3. Di bawah Parameters, ketik KG-2041 pada Project Code.
  4. Klik Call API.
  5. 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"
}
Drawer Test API: get_project_status dengan data API (HTTP method GET, Authentication None, Endpoint, Description), Parameters dengan Project Code KG-2041, badge 200 OK dan Body berisi JSON KG-2041 dengan status Delayed, percentComplete 62, budgetUsd 2500000, spentUsd 1480000 dan approval stage Regional Director, serta tombol Back to editing dan Call API

Klik Back to editing untuk kembali ke form.

Tip: Coba juga KG-9999. Anda akan mendapat 404, 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.
Preview Atlas: user bertanya What is the status of project KG-2041? dan Atlas menjawab Status: Delayed, approval berada di tahap Regional Director, next approver CFO, diikuti poin Progress 62% complete, Budget US$1.48M spent of US$2.5M, dan Latest update steel delivery slipped two weeks dengan forecast completion 15 December 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. 404 biasanya 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 typeKapan digunakan
NoneEndpoint publik, tidak perlu credential
BearerAPI yang diamankan dengan Bearer token statis
BasicAPI yang menggunakan username dan password
CustomAPI dengan nama header kustom (misalnya X-API-Key)
OauthAPI 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.
FieldMengatur
RulesBagaimana AI memproses dan membatasi response API (logika, fallback)
Response PromptBagaimana 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

HeaderDeskripsi
X-AgentIdID agent yang menangani percakapan
X-UserIdIdentifier unik user yang sedang chatting
X-UserEmailEmail user yang sedang chatting (string kosong jika tidak tersedia)
X-InquiryMessageIdID pesan yang memicu API call
X-MediaTypeChannel tempat user berada (web, WhatsApp, dll.)
X-TargetAgentIdID target agent, jika percakapan di-handoff
X-MessengerAccount-ProductProduk messenger yang digunakan, hanya dikirim jika tersedia
X-MessengerAccount-AccountCodeKode akun messenger spesifik, hanya dikirim jika tersedia
X-User-PermissionsArray JSON berisi permission user, hanya dikirim jika tidak kosong

Juga dikirim di query string, untuk GET/DELETE

Query parameterNilai sama dengan
agentIdX-AgentId
userIdX-UserId
userEmailX-UserEmail
inquiryMessageIdX-InquiryMessageId
mediaTypeX-MediaType
targetAgentIdX-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 metadata pada body menggunakan PascalCase (misalnya AgentId, bukan agentId). MessengerAccount bernilai null jika 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:

HTTP Method
Send conversation details
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 Type hanya mengubah contoh nilai yang ditampilkan di atas. Kode server sendiri membaca X-MediaType saat runtime dan sudah menangani web maupun whatsapp, jadi tetap berfungsi apa pun channel yang benar-benar mengirim request tersebut.


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

TipePerilaku
AutoDefault. AI menulis pesan loading singkat yang sesuai dengan request saat itu.
NoneTidak ada pesan loading yang ditampilkan ke user.
FixedTeks persis yang Anda masukkan di Loading text ditampilkan setiap kali.
DynamicAI 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