# 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](authentication.md))
- **Kesalahan & penomoran halaman** — lihat [Kesalahan & Penomoran Halaman](errors-and-pagination.md)

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](../ai-agents/ai-agents.md) terlebih dahulu.


---

## Cara kerja Agen

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

| Bagian | Apa itu | Di mana Anda mengaturnya |
|---|---|---|
| **Konfigurasi** | Instruksi, aturan, tujuan, kepribadian, bahasa, tingkat AI, perilaku pemesanan dan tindak lanjut | `PUT /agents/{agentId}` atau `PUT /agents/{agentId}/bot-config` yang lebih spesifik |
| **Pengetahuan** | FAQ dan sumber pengetahuan (halaman dan dokumen yang telah dibaca platform untuk Anda) | [API FAQ](faqs.md) dan `POST /agents/{agentId}/kb-sources` |
| **Alat** | Fungsi kustom dan server MCP yang mungkin dipanggil Agen di tengah percakapan | `POST /agents/{agentId}/custom-functions` dan `POST /agents/{agentId}/mcp-servers` |
| **Perutean** | Saluran dan percakapan mana yang benar-benar menjangkau Agen ini | Titik Masuk — `PUT /entry-points/channel-defaults` dan `POST /agents/{agentId}/entry-points` |

> **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](#routing-conversations-to-an-agent) 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:

```json
{
  "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
}
```

| Bidang | Tipe | Deskripsi |
|---|---|---|
| `id` | string | Pengidentifikasi unik Agen. |
| `name` | string \| null | Nama agen, seperti yang ditampilkan di dasbor. |
| `active` | boolean \| null | Apakah Agen saat ini diizinkan untuk membalas. |
| `language` | string \| null | Bahasa yang digunakan Agen untuk membalas. |
| `goal` | string \| null | Apa yang dikerjakan Agen, disingkat menjadi 200 karakter pertama (elipsis di akhir berarti teks telah disingkat). |
| `tags` | array \| null | Aturan penandaan Agen. |
| `anthropic_model` | string \| null | Tingkat kualitas AI: `standard`, `economy`, `max` atau `mini`. |
| `ai_speed` | string \| null | Seberapa banyak penalaran yang diterapkan Agen sebelum membalas: `fast`, `fast_thinker`, `balanced` atau `thorough`. |
| `enable_bookings` | boolean \| null | Apakah Agen boleh membuat janji temu. |
| `enable_follow_ups` | boolean \| null | Apakah Agen mengirim pesan tindak lanjut. |
| `faq_refs_count` | integer | Berapa banyak FAQ yang ada di basis pengetahuan Agen ini. |
| `kb_source_refs_count` | integer | Berapa banyak sumber pengetahuan yang ditautkan ke Agen ini. |
| `created_at` | integer \| null | Waktu pembuatan, milidetik epoch. |
| `last_modified_at` | integer \| null | Perubahan terakhir, milidetik epoch. |

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](#get-an-agent).

**Parameter kueri**

| Parameter | Deskripsi |
|---|---|
| `view` | Atur ke `summary` untuk baris singkat. Nilai lainnya akan mengembalikan `400`. Abaikan untuk dokumen lengkap. |
| `fields` | Hanya berlaku bersama dengan `view=summary`. Kunci ringkasan yang dipisahkan koma untuk disimpan, contohnya `id,name,active`. `id` selalu disertakan; nama yang tidak dikenal akan diabaikan. |

**cURL**

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

**JavaScript**

```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**

```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`)

```json
{
  "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`)

| Bidang | Tipe | Deskripsi |
|---|---|---|
| `name` | string | Nama agen. |
| `active` | boolean | Apakah agen boleh langsung membalas. Default-nya adalah `true`. |
| `language` | string | Bahasa yang digunakan Agen untuk membalas. |
| `instructions` | string | Instruksi utama yang mengarahkan cara Agen berbicara dengan kontak. |
| `rules` | string | Aturan ketat yang harus selalu diikuti. |
| `goal` | string | Hasil akhir yang harus diupayakan. |
| `personality` | string | Nada bicara dan kepribadian. |
| `availability` | object | Jam aktif per hari kerja — lihat [Atur jam aktif](#set-active-hours). |
| `ai_speed` | string | `fast`, `fast_thinker`, `balanced` atau `thorough`. |
| `anthropic_model` | string | `standard`, `economy`, `max` atau `mini`. |
| `scrape_urls` | string[] | Halaman untuk dibaca dan digunakan dalam menyusun instruksi Agen. |

**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**

```bash
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**

```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**

```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`)

```json
{
  "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**

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

**JavaScript**

```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**

```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**

```bash
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**

```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**

```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`)

```json
{ "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.

| Kolom | Deskripsi |
|---|---|
| `instructions` | Instruksi utama yang mengarahkan cara Agen berbicara dengan kontak. |
| `rules` | Aturan ketat yang harus selalu diikuti. |
| `goal` | Hasil yang harus diupayakan dalam setiap percakapan. |
| `personality` | Deskripsi nada suara dan kepribadian. |
| `language` | Bahasa yang digunakan Agen untuk membalas. |
| `ai_speed` | `fast`, `fast_thinker`, `balanced` atau `thorough`. |
| `anthropic_model` | `standard`, `economy`, `max` atau `mini`. |
| `max_messages` | Jumlah maksimum pesan Agen per percakapan. |
| `alert_human_when` | Kapan Agen harus memberi tahu rekan tim manusia. |
| `ai_transparency` | Apakah Agen mengungkapkan bahwa dirinya adalah AI. |

> **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`.

```bash
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.

```bash
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`)

```json
{ "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.

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

```javascript
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`)

```json
{ "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.

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

**Respons** (`201`)

```json
{ "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.

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

**Respons** (`200`)

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

**Diblokir** (`409`)

```json
{
  "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](#optimize-an-agent-with-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.

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

**Respons** (`200`)

```json
{ "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.

```bash
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.

```bash
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`)

```json
{ "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**

| Bidang | Wajib | Deskripsi |
|---|---|---|
| `name` | Ya | Tag yang akan diterapkan, contohnya `hot-lead`. |
| `description` | Tidak | Kapan Agen harus menerapkannya, ditulis sebagai instruksi yang harus diikuti. |
| `webhook` | Tidak | URL yang dipanggil saat Agen menerapkan tag ini. |
| `ai_can_remove` | Tidak | Apakah Agen juga boleh menghapus tag tersebut kembali. Standarnya adalah `false`. |
| `tag_id` | Tidak | Id tag yang ada di akun Anda untuk menautkan aturan tersebut. Tanpanya, aturan akan tertaut ke tag dengan nama yang sama, dan membuatnya jika belum ada — sehingga setiap aturan dapat diakses berdasarkan id tag setelahnya. |

### Tambahkan aturan penandaan

`POST /agents/{agentId}/tags`

```bash
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`)

```json
{ "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.

```bash
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.

```bash
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.

| Bidang | Deskripsi |
|---|---|
| `mode` | `merge` (default) mempertahankan aturan yang sudah ada pada Agen dan menambahkannya. `replace` merancang set tersebut dari awal. |

```bash
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`)

```json
{ "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.

```bash
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`)

```json
{
  "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.

```bash
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](faqs.md).

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

```bash
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](../ai-automation/custom-functions.md) 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](../ai-automation/mcp-servers.md). 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`

| Bidang | Wajib | Deskripsi |
|---|---|---|
| `name` | Ya | Label untuk server. |
| `url` | Ya | Alamat server. Harus dapat dijangkau melalui internet publik. |
| `auth_type` | Tidak | `header` (default) untuk header otentikasi statis, atau `oauth2`. |
| `auth_header_name` | Tidak | Header untuk mengirim kredensial. Default-nya adalah `Authorization`. |
| `auth_header_value` | Tidak | Kredensial itu sendiri. Tidak akan pernah dikembalikan dalam respons apa pun. |
| `enabled` | Tidak | Apakah server tersedia untuk Agen. Default-nya adalah `true`. |
| `enabled_tools` | Tidak | Daftar izin nama alat. `null` berarti setiap alat yang ditawarkan server diaktifkan. |
| `tool_policies` | Tidak | Batasan per alat, dikunci berdasarkan nama alat — seberapa sering alat dapat dijalankan, penembolokan hasil, dan penggantian baca-saja. Berikan `null` untuk menghapus semuanya. |

```bash
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`)

```json
{
  "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.

```bash
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.

```bash
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`)

```json
{
  "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:

```bash
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`)

```json
{ "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`

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

**Respons** (`200`)

```json
{
  "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.

| Field | Wajib | Deskripsi |
|---|---|---|
| `base64Data` | Ya | Isi file, dikodekan base64, tanpa awalan data-URL. |
| `mimeType` | Ya | Tipe MIME file. |
| `fileName` | Ya | Nama file asli, digunakan untuk menamai file yang disimpan. |
| `title` | Tidak | Label singkat yang ditampilkan di pustaka. |
| `description` | Tidak | Instruksi "kapan Agen harus mengirim ini". |
| `sendMessage` | Tidak | Kata-kata pilihan yang diucapkan Agen saat mengirim item. Dipotong hingga 500 karakter. |
| `maxSendsPerConversation` | Tidak | Berapa kali item tersebut dapat dikirim ke kontak yang sama dalam satu percakapan. Default-nya adalah `1`. |
| `sendAsVoiceNote` | Tidak | Hanya unggahan audio — simpan file sebagai pesan suara WhatsApp. Diabaikan untuk tipe file lainnya. |

```bash
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).

```bash
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`)

```json
{
  "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.

```bash
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.

| Bidang | Deskripsi |
|---|---|
| `type` | `all` (default) menulis seluruh set. `cold_only` hanya menulis pesan untuk kontak yang tidak pernah membalas. |

```bash
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.

| Apa yang ingin Anda lakukan | Panggilan |
|---|---|
| Menjadikan Agen sebagai penjawab untuk seluruh saluran | `PUT /entry-points/channel-defaults` dengan `{ "channel": "instagram", "agent_id": "AGENT_ID" }` |
| Menambahkan aturan yang lebih spesifik (kata kunci, komentar, pengikut baru) | `POST /agents/{agentId}/entry-points` |
| Melihat aturan yang mengarah ke satu Agen | `GET /agents/{agentId}/entry-points` |
| Membiarkan saluran tanpa ada yang menjawab | `DELETE /entry-points/channel-defaults?channel=instagram` |

### 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`.

```bash
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.

| `type` | Apa fungsinya |
|---|---|
| `channel_default` | Agen menjawab setiap kontak baru di saluran yang terdaftar. Gunakan `PUT /entry-points/channel-defaults` untuk ini — ini akan menonaktifkan penjawab sebelumnya untuk Anda, yang tidak dilakukan jika Anda membuat default kedua di sini. |
| `keyword` | Agen mengambil alih ketika pesan pertama berisi salah satu dari `match_config.keywords`. Setidaknya satu kata kunci diperlukan. |
| `instagram_comment` / `facebook_comment` | Agen membalas komentar pada kiriman Anda. Saluran yang cocok harus terdaftar di `channels`. |
| `instagram_follower` | Agen menyapa pengikut baru. |

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

```bash
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`)

```json
{ "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](entry-points.md) mencakup aturan lengkap mengenai ladder, komentar, dan pengikut, satu Agen per nomor WhatsApp, serta cara mengubah atau menghapus aturan. Lihat [Entry Points](../ai-agents/entry-points.md) untuk konsepnya, dan [Channels API](channels.md) untuk menghubungkan salurannya sendiri.

---

## Kesalahan API Agen AI

Titik akhir Agen mengembalikan amplop kesalahan standar:

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

| Status | Kapan ini terjadi pada titik akhir Agen |
|---|---|
| `400` | Bidang yang diperlukan hilang atau tidak valid — isi pembaruan kosong, nilai di luar daftar yang diizinkan (`ai_speed`, `anthropic_model`, `booking_provider`, `mode`, `type`), kunci bukan hari kerja di `availability`, nama bidang bertitik pada `bot-config`, atau id yang salah format di jalur. |
| `403` | Akun tidak diizinkan menggunakan pengaturan yang Anda kirim, Anda berada di batas Agen paket Anda, atau fitur yang dibutuhkan titik akhir ini (pustaka media, tindak lanjut, fungsi kustom untuk server MCP) tidak aktif. Perubahan yang melebihi ukuran konfigurasi yang diizinkan paket Anda ditolak dengan `400`. |
| `404` | Agen, aturan tag, item media, atau server MCP tidak ditemukan — entah karena tidak ada atau milik akun lain. |
| `409` | Sesuatu sudah berjalan atau menghalangi: pengoptimalan atau pembuatan tag sedang berjalan, Agen masih terlampir pada siaran, Titik Masuk, atau kampanye, atau `cold_only` diminta tanpa kampanye keluar. |

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](errors-and-pagination.md).

> **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](reference.md). Titik akhir `/mcp-servers` tingkat akun juga ada dalam spesifikasi, sehingga Anda dapat menjelajahinya di sana juga.


---

## Terkait

- [Agen AI](../ai-agents/ai-agents.md) — apa itu Agen, dalam bahasa sederhana.
- [Titik Masuk](../ai-agents/entry-points.md) — bagaimana percakapan diarahkan ke Agen.
- [API FAQ](faqs.md) — membangun dan menautkan pengetahuan yang dijawab oleh Agen Anda.
- [API Saluran](channels.md) — menghubungkan saluran tempat Agen menjawab.
- [Hubungkan Server MCP ke Bot Anda](../ai-automation/mcp-servers.md) · [Fungsi Kustom](../ai-automation/custom-functions.md)
- [Referensi API](reference.md) — penjelajah titik akhir interaktif lengkap.