API Agen AI #

Agen AI adalah otak di balik bot Anda: instruksi, kepribadian, bahasa, pengetahuan, dan alatnya. Anda membuat Agen sekali, lalu mengarahkan lalu lintas kepadanya. Panduan ini mencakup semua yang dapat Anda lakukan dengan Agen melalui API — membuatnya, mengonfigurasinya, memberinya pengetahuan dan alat, meninjau drafnya, serta merutekan percakapan kepadanya.

• URL Dasar — https://api.youraiconnector.com/v1
• Autentikasi — kunci API Anda (lihat Autentikasi)
• Kesalahan & penomoran halaman — lihat Kesalahan & Penomoran Halaman

Semua contoh di bawah ini menunjukkan formulir kueri ?apiKey= dalam cURL dan header X-API-Key dalam JavaScript dan Python — keduanya berfungsi di setiap endpoint.

Jika Anda baru mengenal konsep Agen, baca Agen AI terlebih dahulu.

Cara kerja Agen #

Empat hal dikelola secara terpisah, dan ada baiknya mengetahui perbedaannya sebelum Anda memulai:

Agen baru tidak menjawab siapa pun sampai Anda merutekannya. Membuat Agen tidak secara otomatis menempatkannya di saluran. Itu adalah langkah yang paling sering terlewatkan oleh integrasi — lihat Merutekan percakapan ke Agen di akhir halaman ini.

Objek Agen #

Dokumen Agen lengkap berukuran besar — beberapa ratus kilobita, sebagian besar berisi daftar FAQ, sumber pengetahuannya, dan konten halaman apa pun yang dibaca dari situs web Anda. Oleh karena itu, pencantuman daftar akan mengembalikan baris ringkasan per Agen saat Anda memintanya:

{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

Dokumen lengkap menambahkan semua hal lainnya: instructions, rules, personality, availability, follow_up_config, daftar FAQ dan sumber pengetahuan yang ditautkan, blok prosa yang dihasilkan, dan status proses apa pun (tag_generation, optimize_run).

Beberapa respons juga membawa substrate_campaign_id. Ini adalah catatan internal yang disimpan pada akun lama; Anda tidak perlu menindaklanjutinya, dan pada akun yang lebih baru, nilainya adalah null atau tidak ada.

Daftar Agen #

GET /agents — setiap Agen di akun, yang terbaru ditampilkan lebih dulu.

Endpoint ini tidak dipaginasi. Secara default, setiap Agen dikembalikan dengan konfigurasi lengkapnya, yang berukuran besar: satu Agen bisa mencapai 580 KB dan akun dengan 64 Agen bisa lebih dari 3 MB. Berikan view=summary untuk mendapatkan baris singkat per Agen, lalu baca yang Anda inginkan dengan Dapatkan Agen.

Parameter kueri

cURL

curl "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents?view=summary", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agents } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"view": "summary"},
)
agents = res.json()["agents"]

Respons (200)

{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}

Membuat Agen #

POST /agents — hanya name yang benar-benar diperlukan; kirimkan konfigurasi apa pun yang sudah Anda ketahui bersamanya. Agen baru aktif secara default.

Bidang permintaan (semua opsional kecuali name)

Membangun Agen dari situs web Anda. Sertakan scrape_urls dan platform akan membaca halaman tersebut serta menulis instruksi untuk Anda. Respons akan memberi tahu Anda apakah pembuatan tersebut telah dimulai, sehingga Anda tahu apakah perlu melakukan polling pada Agen untuk melihat perkembangannya.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])

Respons (201)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}

agent_generation_queued adalah true saat platform mulai menulis instruksi dari halaman yang Anda berikan.

400 berarti body bukan merupakan objek JSON, ada bidang yang ditolak, atau Agen melebihi ukuran konfigurasi yang diizinkan oleh paket Anda. 403 berarti akun tidak diizinkan menggunakan salah satu pengaturan yang Anda kirim — misalnya tingkat AI yang belum diberikan oleh penyedia akunnya.

Dapatkan Agen #

GET /agents/{agentId}

Berikan fields dengan daftar yang dipisahkan koma untuk mendapatkan kembali hanya apa yang Anda butuhkan, contohnya fields=name,active,goal. id selalu disertakan, dan nama yang tidak ada pada Agen akan diabaikan alih-alih ditolak. Abaikan parameter ini untuk mendapatkan seluruh dokumen.

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]

Agen yang tidak ada di akun Anda akan mengembalikan 404.

Memperbarui Agen #

PUT /agents/{agentId} — kirim hanya bidang yang ingin Anda ubah; yang lainnya akan dibiarkan tidak berubah.

Pengaturan bertingkat dapat diakses per bagian dengan kunci bertitik, sehingga "availability.monday" hanya mengubah hari Senin dan membiarkan sisa minggu tetap apa adanya.

Catatan

• Untuk mengubah jenis acara yang dapat dipesan oleh Agen, kirim event_id (id acara, atau null untuk mengosongkannya). Kirim event_ids dengan array untuk menautkan beberapa sekaligus — yang pertama menjadi yang utama dan [] akan membatalkan tautan semuanya. event_id dan event_ids saling eksklusif, dan kolom event itu sendiri tidak dapat ditulis secara langsung.
• enable_bookings harus berupa boolean yang valid, dan booking_provider harus salah satu dari default, zenchef, formitable.
• Kolom kepemilikan dan identitas diabaikan, begitu pula status proses internal (kemajuan pembuatan dan pengoptimalan).
• Perutean tidak diatur di sini. Gunakan PUT /entry-points/channel-defaults untuk menjadikan Agen sebagai penjawab saluran, POST /agents/{agentId}/entry-points untuk aturan kata kunci dan komentar, serta PATCH /agents/{agentId}/active untuk menjeda atau melanjutkannya.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ "availability.monday": { start_time: "09:00", end_time: "17:00" } }),
});

Python

requests.put(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)

Respons (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Body kosong akan mengembalikan 400 dengan "No fields to update".

Perbarui pengaturan bot #

PUT /agents/{agentId}/bot-config — cara ringkas untuk mengubah pengaturan percakapan saja.

Agen tidak memiliki bagian bot terpisah: pengaturannya berada langsung pada Agen, jadi nama kolom di sini sama dengan yang akan Anda kirim ke PUT /agents/{agentId}. Endpoint ini ada sebagai cara yang aman dan terfokus untuk mengubah beberapa di antaranya. Setidaknya satu kolom diperlukan.

Nama kolom harus berupa nama biasa di sini — huruf, angka, garis bawah, dan tanda hubung. Jalur bertitik tidak diterima di endpoint ini (tidak seperti PUT /agents/{agentId}), jadi bot.goal akan ditolak dengan 400.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'

Teks yang panjang akan dihitung terhadap ukuran konfigurasi yang diizinkan oleh paket Anda, sehingga kumpulan instruksi yang sangat besar dapat ditolak dengan 400.

Atur jam aktif #

PUT /agents/{agentId}/active-hours — jam di mana Agen membalas secara otomatis. Di luar jendela waktu tersebut, Agen akan tetap diam.

Kirim objek availability yang dikunci berdasarkan hari kerja (monday hingga sunday). Setiap hari memerlukan satu jendela waktu atau daftar jendela waktu, dalam format HH:MM 24 jam. Hari yang Anda lewatkan akan tetap menggunakan pengaturan sebelumnya, dan kunci apa pun yang bukan hari kerja akan ditolak — sehingga kesalahan ketik tidak akan diabaikan begitu saja.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

Respons (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Kunci hari kerja yang salah akan mengembalikan 400: "Invalid availability keys: funday. Allowed keys: monday through sunday."

Jeda atau lanjutkan Agen #

PATCH /agents/{agentId}/active — mengaktifkan atau menonaktifkan Agen. Agen yang dijeda akan menyimpan semua konfigurasinya tetapi segera berhenti membalas; melanjutkan Agen akan langsung berlaku.

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});

Respons (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }

active harus berupa boolean yang valid — nilai lainnya akan mengembalikan 400 dengan "active (boolean) is required".

Menduplikasi Agen #

POST /agents/{agentId}/duplicate — membuat salinan dengan konfigurasi yang tetap terjaga. Salinan tersebut tidak akan mengirim apa pun sampai Anda mengarahkan saluran atau Titik Masuk (Entry Point) ke sana.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/duplicate?apiKey=YOUR_API_KEY"

Respons (201)

{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }

Duplikat dihitung terhadap kuota Agen paket Anda sama seperti membuat Agen dari awal, sehingga permintaan akan ditolak dengan 403 jika akun Anda telah mencapai batas.

Menghapus Agen #

DELETE /agents/{agentId}

Penghapusan akan ditolak selama Agen masih terhubung ke sesuatu yang akan berhenti berfungsi tanpanya — siaran, Titik Masuk, atau (pada akun lama) kampanye. Respons akan mencantumkan apa yang menahannya sehingga Anda dapat melepasnya terlebih dahulu dan mencoba lagi.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY"

Respons (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Diblokir (409)

{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}

Draf: tinjau perubahan sebelum ditayangkan #

Hasil edit yang dibuat di editor, dan penulisan ulang apa pun yang dihasilkan oleh Optimalkan dengan AI, akan disimpan sebagai draf yang belum dipublikasikan hingga Anda memublikasikannya. Agen yang sedang aktif akan terus menjawab dengan konfigurasi saat ini hingga saat itu tiba.

Publikasikan draf #

POST /agents/{agentId}/publish-draft — memindahkan draf ke konfigurasi langsung dan menghapus draf dalam langkah yang sama.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"

Respons (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }

published_keys mencantumkan pengaturan yang dipindahkan dari draf ke Agen langsung, sehingga Anda dapat menunjukkan apa yang berubah.

Pastikan draf ada sebelum memanggil ini. Memublikasikan Agen yang tidak memiliki draf bukanlah panggilan yang didukung dan saat ini akan menghasilkan 500 dengan pesan umum, bukan pesan spesifik. Untuk membuang draf sebagai gantinya, gunakan hapus di bawah.

Buang draf #

POST /agents/{agentId}/discard-draft — membuang draf dan membiarkan konfigurasi langsung tetap apa adanya. Aman untuk dipanggil saat tidak ada draf; tidak ada yang terjadi.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"

Optimalkan Agen dengan AI #

POST /agents/{agentId}/optimize — menulis ulang konfigurasi Agen berdasarkan masukan Anda (“ia terus menawarkan diskon”, “jawabannya terlalu panjang”) dan menyimpan penulisan ulang tersebut sebagai draf alih-alih langsung menerapkannya.

Kirim user_feedback (instruksi biasa) atau, saat menanggapi balasan buruk tertentu, thumbs_down_feedback bersama dengan thumbs_down_message yang bermasalah. Setidaknya salah satu dari keduanya harus berisi teks.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'

Respons (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Pekerjaan berjalan di latar belakang dan panggilan langsung kembali seketika. Baca Agen dengan GET /agents/{agentId} dan pantau optimize_run.status; setelah kembali ke Draft, penulisan ulang tersebut menunggu sebagai draf Agen. Tinjau draf tersebut, lalu publikasikan atau buang.

Hanya satu proses yang berjalan dalam satu waktu per Agen — panggilan kedua saat satu proses sedang berlangsung akan mengembalikan 409. Ini menggunakan kredit AI.

Aturan penandaan (tagging) #

Aturan penandaan adalah tag ditambah deskripsi kapan aturan tersebut berlaku. Selama percakapan, Agen membaca deskripsi tersebut dan menandai kontak saat kondisinya sesuai, yang merupakan cara otomatisasi berbasis tag dipicu.

Objek aturan

Tambahkan aturan penandaan #

POST /agents/{agentId}/tags

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'

Respons (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }

Ganti aturan penandaan #

PUT /agents/{agentId}/tags/{tagId} — aturan ditemukan berdasarkan id tag di jalur dan diganti secara keseluruhan, bukan digabungkan, jadi kirimkan aturan lengkap alih-alih hanya bagian yang ingin Anda ubah. Tag yang ditunjuknya tetap dipertahankan meskipun Anda tidak menyertakan tag_id, sehingga pengeditan tidak dapat melepaskan aturan dari tag-nya.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'

Menghapus aturan penandaan #

DELETE /agents/{agentId}/tags/{tagId} — Agen berhenti menerapkan tag tersebut. Tag itu sendiri, dan kontak apa pun yang sudah memilikinya, tidak akan terpengaruh.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"

Kedua endpoint mengembalikan 404 saat Agen tidak ada atau saat tidak memiliki aturan untuk tag tersebut.

Membuat set tag dengan AI #

POST /agents/{agentId}/tags/generate — merancang keseluruhan set aturan (nama tag dan kata-kata “terapkan saat…” di balik setiap aturan) dengan membaca instruksi dan tujuan Agen itu sendiri.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'

Respons (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }

Pekerjaan berjalan di latar belakang. Baca Agen dan pantau tag_generation.status; aturan itu sendiri akan muncul di tags Agen. Hanya satu proses yang berjalan dalam satu waktu per Agen (409 jika tidak), dan ini menggunakan kredit AI.

Sumber pengetahuan #

Sumber pengetahuan adalah halaman dan dokumen yang telah dibaca oleh platform untuk Anda. Melampirkannya ke Agen memungkinkan Agen menjawab berdasarkan konten tersebut.

Dari mana id sumber berasal. Tambahkan konten dengan endpoint basis pengetahuan — POST /kb-sources/url untuk halaman, POST /kb-sources/file untuk dokumen, POST /kb-sources/bulk-import untuk seluruh situs. Endpoint tersebut mengembalikan source_id yang Anda polling dengan GET /kb-sources/{sourceId} hingga siap. POST /kb-sources/url juga menerima autoLinkToAgentId, yang melampirkan sumber ke Agen segera setelah impor selesai, sehingga Anda dapat melewati panggilan lampiran di bawah.

Melampirkan sumber pengetahuan #

POST /agents/{agentId}/kb-sources — kirim kb_source_ids dengan daftar untuk melampirkan seluruh set dalam satu panggilan (apa yang Anda inginkan setelah merayapi situs), atau kb_source_id untuk satu sumber saja. Kirim salah satu dari keduanya. Melampirkan sesuatu yang sudah terlampir tidak akan mengubah apa pun.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'

Respons (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}

Melepaskan sumber pengetahuan #

DELETE /agents/{agentId}/kb-sources/{kbSourceId} untuk satu, atau POST /agents/{agentId}/kb-sources/bulk-remove dengan kb_source_ids untuk beberapa. Penghapusan massal adalah POST karena daftar id dikirim di dalam body.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'

Sumber itu sendiri tidak dihapus dan tetap tersedia untuk Agen Anda yang lain. Melepaskan sesuatu yang tidak terpasang tidak mengubah apa pun.

FAQ #

FAQ dikelola pada endpoint-nya sendiri dan ditautkan ke Agen dari sana: POST /faqs/{faqId}/link dengan { "agent_id": "ag7HkQ2ZpLxR3mNb" }, dan POST /faqs/{faqId}/unlink untuk menghapusnya kembali. FAQ dapat dibagikan oleh sejumlah Agen. Lihat API FAQ.

FAQ hanya digunakan oleh Agen yang ditautkan dengannya — membuatnya saja tidak cukup.

Alat #

Fungsi kustom #

POST /agents/{agentId}/custom-functions memungkinkan Agen memanggil salah satu fungsi kustom Anda selama percakapan. Hanya fungsi yang termasuk dalam akun yang sama yang dapat dilampirkan, dan melampirkan fungsi yang sudah terlampir tidak mengubah apa pun.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'

DELETE /agents/{agentId}/custom-functions/{customFunctionId} melepaskannya. Fungsi itu sendiri tidak dihapus dan tetap tersedia untuk Agen Anda yang lain.

Kelola fungsi itu sendiri di /custom-functions — lihat Fungsi Kustom untuk mengetahui apa itu fungsi kustom.

Server MCP #

Server MCP adalah paket alat siap pakai yang dapat ditemukan dan dipanggil sendiri oleh Agen Anda — lihat Hubungkan Server MCP ke Bot Anda. Server didaftarkan sekali pada akun, kemudian dilampirkan ke Agen mana pun yang harus menggunakannya.

Server MCP memerlukan fitur fungsi kustom pada paket Anda. Tanpa fitur tersebut, endpoint /mcp-servers tingkat akun akan mengembalikan 403. Melampirkan server yang sudah terdaftar ke Agen tidak dibatasi.

Daftarkan server #

POST /mcp-servers

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'

Respons (201)

{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}

Saat disimpan, platform akan terhubung ke server dan menembolok daftar alat yang ditawarkannya. Server yang tidak dapat dijangkau tetap akan tersimpan, dengan alasan yang tercantum di last_error dan daftar alat kosong — sehingga Anda dapat mendaftar terlebih dahulu dan memperbaiki konektivitas setelahnya.

Sebuah auth_type dengan oauth2 akan menyimpan pendaftaran dengan oauth_connected: false dan tanpa alat: belum ada token. Mengotorisasi server OAuth memerlukan masuk melalui browser dan dilakukan dari dasbor, bukan melalui API.

Mencantumkan, memperbarui, dan menghapus server #

• GET /mcp-servers — setiap server yang terdaftar, yang terbaru terlebih dahulu, di bawah servers.
• PUT /mcp-servers/{serverId} — kirim hanya apa yang ingin Anda ubah. Mengubah URL atau bidang otentikasi akan menguji ulang koneksi dan menyegarkan daftar alat yang di-cache.
• DELETE /mcp-servers/{serverId} — menghapus pendaftaran dan memutuskan tautannya dari setiap Agen dan kampanye yang mengaktifkannya.

curl "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY"

Rahasia tidak akan pernah dikembalikan. Respons membawa auth_header_value_set (bendera true/false yang menyatakan bahwa nilai tersimpan) alih-alih kredensial, dan token OAuth serta rahasia klien tetap berada di sisi server. Semua hal lainnya akan dikembalikan: name, url, enabled, auth_type, auth_header_name, tools, enabled_tools, tool_policies, oauth_connected, tools_cached_at, last_connected_at, last_error, created_at, updated_at.

Menguji koneksi #

POST /mcp-servers/test-connection — terhubung ke server dan mencantumkan alat-alatnya. Ada dua cara untuk memanggilnya:

• dengan server_id — menguji konfigurasi yang disimpan dan menyegarkan daftar alat yang di-cache;
• dengan url inline (ditambah auth_header_name / auth_header_value) — pengujian sebelum penyimpanan yang tidak menyimpan apa pun.

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'

Respons (200)

{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}

Kegagalan koneksi bukan merupakan kesalahan HTTP — Anda akan mendapatkan 200 dengan success: false dan error yang menjelaskan apa yang salah, sehingga Anda dapat menampilkannya di samping kolom yang sedang diedit oleh operator.

Lampirkan server ke Agen #

Mendaftarkan server tidak memberikan akses apa pun kepada Agen. Lampirkan server tersebut:

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'

Respons (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }

DELETE /agents/{agentId}/mcp-servers/{mcpServerId} akan melepaskannya kembali. Server itu sendiri tidak dihapus dan tetap tersedia bagi Agen Anda yang lain. Melampirkan atau melepaskan sesuatu yang sudah dalam status tersebut tidak akan mengubah apa pun.

Pustaka media #

Pustaka media menyimpan file yang mungkin dikirim oleh Agen selama percakapan — menu, daftar harga, foto produk. Satu Agen dapat menampung maksimal 50 item.

Daftar media #

GET /agents/{agentId}/media-library

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY"

Respons (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}

Item yang disimpan di Agen didahulukan, kemudian item lama yang masih tersimpan di kampanye tempat Agen tersebut dibuat; media_home (agent atau campaign) menunjukkan mana yang mana. Dalam setiap grup, yang terbaru diletakkan di urutan pertama.

media_url kedaluwarsa setelah 7 hari. Ini adalah tautan unduhan yang dibuat saat file diunggah — anggap tautan lama sudah usang, bukan rusak, dan baca ulang daftar untuk mendapatkan tautan baru.

Unggah media #

POST /agents/{agentId}/media-library — file diunggah secara inline sebagai base64, hingga 10 MB. Panggilan akan kembali setelah file tersimpan, jadi berikan waktu sedikit lebih lama daripada permintaan biasa. Perhatikan bahwa body ini menggunakan nama field camelCase.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'

Dua hal terjadi secara otomatis: GIF animasi dikonversi menjadi video agar dapat diputar di semua saluran, dan platform menulis ringkasan singkat tentang isi file tersebut agar Agen mengetahui kapan file itu sesuai untuk digunakan.

400 mencakup field yang hilang, tipe file yang tidak didukung, file kosong atau terlalu besar, dan mencapai batas 50 item. 403 berarti pustaka media dinonaktifkan untuk akun tersebut.

Perbarui item media #

PATCH /agents/{agentId}/media-library/{itemId} — hanya metadata. File itu sendiri tidak dapat diganti; unggah item baru dan hapus yang lama. Body ini menggunakan snake_case: title, description, send_message, max_sends_per_conversation (bilangan bulat non-negatif, atau null untuk menghapus batas).

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'

Respons (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}

Hapus item media #

DELETE /agents/{agentId}/media-library/{itemId} — menghapus item dan file yang tersimpan. Menghapus item yang sudah tidak ada akan berhasil dan melaporkan deleted: false, sehingga panggilan ini aman untuk dicoba kembali.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"

Hasilkan pesan tindak lanjut #

POST /agents/{agentId}/template-generation — menulis pesan tindak lanjut Agen untuk Anda (pengingat yang dikirim saat percakapan menjadi senyap), berdasarkan tujuan Agen tersebut.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

Ada dua cara hal ini dikembalikan, dan bidang target memberi tahu Anda yang mana:

• target: "agent" dengan 200 — pesan ditulis selama panggilan dan hasilnya ada di data. Baca kembali dari follow_up_config Agen. Ini adalah kasus yang biasa.
• target: "campaign" dengan 202 — pekerjaan diantrekan terhadap kampanye yang disebutkan di campaign_id. Pantau template_generation_status kampanye tersebut hingga selesai.

cold_only memerlukan kampanye keluar dan ditolak dengan 409 (reason: "cold_only_requires_campaign") pada Agen yang tidak memilikinya. 403 berarti tindak lanjut otomatis tidak diaktifkan untuk akun tersebut. Ini menggunakan kredit AI, dan 400 dengan "Insufficient credits." berarti akun tersebut kehabisan kredit.

Mengarahkan percakapan ke Agen #

Agen hanya menjawab percakapan yang dikirimkan oleh Titik Masuk (Entry Point). Hingga saluran memiliki satu titik masuk, pesan pertama dari seseorang yang belum pernah Anda ajak bicara tetap disimpan, tetapi tidak ada yang mengambilnya dan tidak ada asisten yang membalas.

Mencantumkan Titik Masuk Agen #

GET /agents/{agentId}/entry-points — aturan perutean yang mengirimkan percakapan ke Agen ini, yang terbaru ditampilkan lebih dulu. Baik aturan saat ini maupun yang sudah tidak berlaku akan dikembalikan; aturan yang sudah tidak berlaku memiliki enabled: false.

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"

Untuk default saluran seluruh akun, termasuk saluran yang sengaja diatur ke tidak ada siapa pun, baca GET /entry-points/channel-defaults sebagai gantinya.

Membuat Titik Masuk #

POST /agents/{agentId}/entry-points — Agen di jalur tersebut selalu menang, jadi aturan tidak akan pernah bisa dibuat untuk Agen yang berbeda dari yang ada di URL.

channels diperlukan dan menyatakan saluran mana yang dicakup oleh aturan tersebut — misalnya whatsapp, whatsapp_web, instagram, messenger, telegram, sms, email, chat_widget atau custom_channel. Aturan baru diaktifkan kecuali Anda menyatakan sebaliknya.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'

Respons (201)

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Aturan mana yang menang jika ada beberapa yang bisa: percakapan yang sedang berlangsung atau penugasan manual akan tetap mempertahankan Agen yang sudah dimilikinya; jika tidak, aturan kata kunci mengalahkan aturan komentar, yang mengalahkan aturan pengikut, dan default saluran adalah pilihan terakhir. Apakah aturan-aturan ini sudah menentukan sesuatu pada akun dilaporkan oleh GET /entry-points/routing-status.

Ini adalah versi singkatnya. Panduan Entry Points API mencakup aturan lengkap mengenai ladder, komentar, dan pengikut, satu Agen per nomor WhatsApp, serta cara mengubah atau menghapus aturan. Lihat Entry Points untuk konsepnya, dan Channels API untuk menghubungkan salurannya sendiri.

Kesalahan API Agen AI #

Titik akhir Agen mengembalikan amplop kesalahan standar:

{
  "success": false,
  "error": "Agent not found"
}

Kode bersama yang dapat dikembalikan oleh setiap endpoint — 401, 403 (paket Anda tidak menyertakan akses API), 429 (batas kecepatan) dan 500 — tercantum beserta panduan percobaan ulang di Kesalahan & Penomoran Halaman.

Catatan tentang penjelajah. Titik akhir /agents ada dalam spesifikasi OpenAPI yang dipublikasikan, sehingga Anda dapat menelusuri bidang persisnya dan menjalankan permintaan langsung di Referensi API. Titik akhir /mcp-servers tingkat akun juga ada dalam spesifikasi, sehingga Anda dapat menjelajahinya di sana juga.

Terkait #

• Agen AI — apa itu Agen, dalam bahasa sederhana.
• Titik Masuk — bagaimana percakapan diarahkan ke Agen.
• API FAQ — membangun dan menautkan pengetahuan yang dijawab oleh Agen Anda.
• API Saluran — menghubungkan saluran tempat Agen menjawab.
• Hubungkan Server MCP ke Bot Anda · Fungsi Kustom
• Referensi API — penjelajah titik akhir interaktif lengkap.