# AI Temsilcileri API'si

Bir **AI Temsilcisi**, botunuzun arkasındaki beyindir: talimatları, kişiliği, dili, bilgisi ve araçları. Bir Temsilciyi bir kez oluşturur ve ardından trafiği ona yönlendirirsiniz. Bu kılavuz, API üzerinden bir Temsilci ile yapabileceğiniz her şeyi kapsar: oluşturma, yapılandırma, bilgi ve araçlar ekleme, taslakları gözden geçirme ve konuşmaları ona yönlendirme.

- **Temel URL** — `https://api.youraiconnector.com/v1`
- **Kimlik Doğrulama** — API anahtarınız (bkz. [Kimlik Doğrulama](authentication.md))
- **Hatalar ve sayfalama** — bkz. [Hatalar ve Sayfalama](errors-and-pagination.md)

Aşağıdaki tüm örnekler cURL'de `?apiKey=` sorgu biçimini ve JavaScript ile Python'da `X-API-Key` başlığını göstermektedir; her ikisi de her uç noktada çalışır.

Temsilciler kavramına yeniyseniz, önce [AI Temsilcileri](../ai-agents/ai-agents.md) bölümünü okuyun.


---

## Bir Temsilci nasıl bir araya gelir

Dört şey ayrı ayrı yönetilir ve başlamadan önce hangisinin ne olduğunu bilmek faydalıdır:

| Parça | Nedir | Nerede ayarlanır |
|---|---|---|
| **Yapılandırma** | Talimatlar, kurallar, hedef, kişilik, dil, AI katmanı, randevu ve takip davranışı | `PUT /agents/{agentId}` veya daha dar kapsamlı `PUT /agents/{agentId}/bot-config` |
| **Bilgi** | SSS'ler ve bilgi kaynakları (platformun sizin için okuduğu sayfalar ve belgeler) | [SSS API'si](faqs.md) ve `POST /agents/{agentId}/kb-sources` |
| **Araçlar** | Temsilcinin konuşma sırasında çağırabileceği özel işlevler ve MCP sunucuları | `POST /agents/{agentId}/custom-functions` ve `POST /agents/{agentId}/mcp-servers` |
| **Yönlendirme** | Hangi kanalların ve konuşmaların bu Temsilciye ulaşacağı | Giriş Noktaları — `PUT /entry-points/channel-defaults` ve `POST /agents/{agentId}/entry-points` |

> **Yeni bir Temsilci, siz ona yönlendirme yapana kadar kimseye yanıt vermez.** Bir Temsilci oluşturmak onu bir kanala yerleştirmez. Bu, çoğu entegrasyonun gözden kaçırdığı adımdır — bu sayfanın sonundaki [Konuşmaları bir Temsilciye yönlendirme](#routing-conversations-to-an-agent) bölümüne bakın.

---

## Temsilci nesnesi

Tam bir Temsilci belgesi büyüktür; birkaç yüz kilobayt, çoğunlukla SSS listesi, bilgi kaynakları ve web sitenizden okunan sayfa içerikleri. Bu nedenle, listeleme işlemi istediğinizde Temsilci başına kısa bir **özet satırı** döndürür:

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

| Alan | Tür | Açıklama |
|---|---|---|
| `id` | string | Temsilcinin benzersiz tanımlayıcısı. |
| `name` | string \| null | Kontrol panelinde gösterildiği şekliyle Temsilci adı. |
| `active` | boolean \| null | Temsilcinin şu anda yanıt vermesine izin verilip verilmediği. |
| `language` | string \| null | Temsilcinin yanıt verdiği dil. |
| `goal` | string \| null | Temsilcinin neye yönelik çalıştığı, ilk 200 karakterle kısaltılmıştır (sondaki üç nokta kısaltıldığını gösterir). |
| `tags` | array \| null | Temsilcinin etiketleme kuralları. |
| `anthropic_model` | string \| null | AI kalite katmanı: `standard`, `economy`, `max` veya `mini`. |
| `ai_speed` | string \| null | Temsilcinin yanıt vermeden önce ne kadar akıl yürütme uyguladığı: `fast`, `fast_thinker`, `balanced` veya `thorough`. |
| `enable_bookings` | boolean \| null | Temsilcinin randevu alıp alamayacağı. |
| `enable_follow_ups` | boolean \| null | Temsilcinin takip mesajları gönderip göndermeyeceği. |
| `faq_refs_count` | integer | Bu Temsilcinin bilgi tabanında kaç SSS olduğu. |
| `kb_source_refs_count` | integer | Ona kaç bilgi kaynağının bağlı olduğu. |
| `created_at` | integer \| null | Oluşturulma zamanı, epoch milisaniye cinsinden. |
| `last_modified_at` | integer \| null | Son değişiklik, epoch milisaniye cinsinden. |

Tam belge diğer her şeyi ekler: `instructions`, `rules`, `personality`, `availability`, `follow_up_config`, bağlantılı SSS ve bilgi kaynağı listeleri, oluşturulan metin blokları ve herhangi bir çalışma durumu (`tag_generation`, `optimize_run`).

> Bazı yanıtlar `substrate_campaign_id` da taşır. Bu, eski hesaplarda tutulan dahili bir kayıttır; üzerinde hiçbir zaman işlem yapmanız gerekmez ve yeni hesaplarda `null` değerindedir veya hiç yoktur.

---

## Temsilcileri Listele

`GET /agents` — hesaptaki her Temsilci, en yenisi ilk sırada olacak şekilde.

Bu uç nokta **sayfalandırılmamıştır**. Varsayılan olarak her Temsilci, tam yapılandırmasıyla birlikte gelir; bu oldukça ağırdır: tek bir Temsilci 580 KB'a ulaşabilir ve 64 Temsilcili bir hesap 3 MB'ı geçebilir. Bunun yerine Temsilci başına kısa bir satır almak için `view=summary` değerini iletin, ardından istediğiniz Temsilciyi [Temsilciyi Al](#get-an-agent) ile okuyun.

**Sorgu parametreleri**

| Parametre | Açıklama |
|---|---|
| `view` | Kısa satırlar için `summary` olarak ayarlayın. Başka herhangi bir değer `400` döndürür. Tam belgeler için boş bırakın. |
| `fields` | Yalnızca `view=summary` ile birlikte kullanıldığında geçerlidir. Tutulacak virgülle ayrılmış özet anahtarları, örneğin `id,name,active`. `id` her zaman dahil edilir; bilinmeyen adlar yoksayılır. |

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

**Yanıt** (`200`)

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

---

## Temsilci Oluştur

`POST /agents` — yalnızca `name` gerçekten gereklidir; bildiğiniz tüm yapılandırmaları onunla birlikte gönderin. Yeni bir Temsilci varsayılan olarak etkindir.

**İstek alanları** (`name` hariç tümü isteğe bağlıdır)

| Alan | Tür | Açıklama |
|---|---|---|
| `name` | string | Temsilci adı. |
| `active` | boolean | Hemen yanıt verip veremeyeceği. Varsayılan değer `true`'dir. |
| `language` | string | Temsilcinin yanıt verdiği dil. |
| `instructions` | string | Kişilerle nasıl konuşacağını yönlendiren temel talimatlar. |
| `rules` | string | Her zaman uyması gereken katı kurallar. |
| `goal` | string | Ulaşması gereken sonuç. |
| `personality` | string | Ses tonu ve kişilik. |
| `availability` | object | Hafta içi günlük aktif saatler — bkz. [Aktif saatleri ayarla](#set-active-hours). |
| `ai_speed` | string | `fast`, `fast_thinker`, `balanced` veya `thorough`. |
| `anthropic_model` | string | `standard`, `economy`, `max` veya `mini`. |
| `scrape_urls` | string[] | Temsilcinin talimatlarını oluşturmak için okunacak sayfalar. |

**Web sitenizden bir Temsilci oluşturma.** `scrape_urls` dahil edildiğinde platform bu sayfaları okur ve talimatları sizin yerinize yazar. Yanıt, bu oluşturma işleminin başlayıp başlamadığını size bildirir, böylece Temsilcinin ilerlemesini sorgulayıp sorgulamayacağınızı bilirsiniz.

**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"])
```

**Yanıt** (`201`)

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

`agent_generation_queued`, platform sağladığınız sayfalardan talimatları yazmaya başladığında `true` durumundadır.

`400`, gövdenin bir JSON nesnesi olmadığı, bir alanın reddedildiği veya Temsilcinin planınızın izin verdiği yapılandırma boyutunu aştığı anlamına gelir. `403`, hesabın gönderdiğiniz ayarlardan birini kullanmasına izin verilmediği anlamına gelir — örneğin, hesap sağlayıcısının vermediği bir yapay zeka katmanı gibi.

---

## Bir Temsilci Alın

`GET /agents/{agentId}`

Yalnızca ihtiyacınız olanı geri almak için virgülle ayrılmış bir liste ile `fields` değerini iletin, örneğin `fields=name,active,goal`. `id` her zaman dahil edilir ve Temsilcide bulunmayan isimler reddedilmek yerine göz ardı edilir. Belgenin tamamını almak için bunu atlayın.

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

Hesabınızda bulunmayan bir Temsilci `404` döndürür.

---

## Bir Temsilciyi Güncelleyin

`PUT /agents/{agentId}` — yalnızca değiştirmek istediğiniz alanları gönderin; diğer her şey olduğu gibi bırakılır.

İç içe geçmiş ayarlar, noktalı bir anahtar ile yaprak yaprak ele alınabilir; böylece `"availability.monday"` sadece Pazartesi gününü değiştirir ve haftanın geri kalanına dokunmaz.

**Notlar**

- Temsilcinin hangi rezerve edilebilir etkinlik türüne rezervasyon yapacağını değiştirmek için `event_id` (etkinliğin kimliği veya temizlemek için `null`) gönderin. Bir kerede birkaçını bağlamak için bir dizi ile `event_ids` gönderin; ilki birincil olur ve `[]` her şeyin bağlantısını keser. `event_id` ve `event_ids` birbirini dışlar ve `event` alanının kendisine doğrudan yazılamaz.
- `enable_bookings` gerçek bir boolean olmalıdır ve `booking_provider`; `default`, `zenchef`, `formitable` değerlerinden biri olmalıdır.
- Sahiplik ve kimlik alanları, dahili çalışma durumu (oluşturma ve optimizasyon ilerlemesi) gibi yoksayılır.
- **Yönlendirme burada ayarlanmaz.** Bir kanal için Temsilciyi yanıtlayıcı yapmak için `PUT /entry-points/channel-defaults`, anahtar kelime ve yorum kuralları için `POST /agents/{agentId}/entry-points` ve duraklatmak veya devam ettirmek için `PATCH /agents/{agentId}/active` kullanın.

**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"},
)
```

**Yanıt** (`200`)

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

Boş bir gövde, `"No fields to update"` ile birlikte `400` döndürür.

---

## Bot ayarlarını güncelle

`PUT /agents/{agentId}/bot-config` — yalnızca konuşma ayarlarını değiştirmenin dar yolu.

Bir Temsilcinin ayrı bir bot bölümü yoktur: ayarları doğrudan Temsilci üzerinde bulunur, bu nedenle buradaki alan adları `PUT /agents/{agentId}` adresine göndereceğiniz alan adlarıyla aynıdır. Bu uç nokta, bunlardan birkaçını değiştirmenin güvenli ve odaklanmış yolu olarak mevcuttur. En az bir alan gereklidir.

| Alan | Açıklama |
|---|---|
| `instructions` | Temsilcinin kişilerle nasıl konuşacağını yönlendiren temel talimatlar. |
| `rules` | Her zaman uyması gereken katı kurallar. |
| `goal` | Her konuşmada ulaşması gereken sonuç. |
| `personality` | Ses tonu ve kişilik açıklaması. |
| `language` | Temsilcinin yanıt verdiği dil. |
| `ai_speed` | `fast`, `fast_thinker`, `balanced` veya `thorough`. |
| `anthropic_model` | `standard`, `economy`, `max` veya `mini`. |
| `max_messages` | Konuşma başına maksimum Temsilci mesajı sayısı. |
| `alert_human_when` | Temsilcinin ne zaman bir insan ekip üyesini uyarması gerektiği. |
| `ai_transparency` | Temsilcinin bir yapay zeka olduğunu açıklayıp açıklamadığı. |

> **Alan adları burada düz isimler olmalıdır** — harfler, sayılar, alt çizgiler ve kısa çizgiler. Noktalı yollar bu uç noktada kabul edilmez ( `PUT /agents/{agentId}` aksine), bu nedenle `bot.goal` bir `400` ile reddedilir.

```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" }'
```

Uzun metin, planınızın izin verdiği yapılandırma boyutuna karşı sayılır, bu nedenle çok büyük bir talimat seti `400` ile reddedilebilir.

---

## Aktif saatleri ayarla

`PUT /agents/{agentId}/active-hours` — Temsilcinin otomatik olarak yanıt verdiği saatler. Bu pencerelerin dışında sessiz kalır.

Haftanın gününe göre (`monday` ile `sunday` arası) anahtarlanmış bir `availability` nesnesi gönderin. Her gün tek bir zaman penceresi veya 24 saatlik `HH:MM` biçiminde bir pencere listesi alır. Dışarıda bıraktığınız günler sahip olduklarını korur ve hafta içi olmayan herhangi bir anahtar reddedilir; böylece bir yazım hatası sessizce hiçbir şey yapmadan geçemez.

```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" }
      ]
    }
  }'
```

**Yanıt** (`200`)

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

Hatalı bir hafta içi anahtarı `400` döndürür: `"Invalid availability keys: funday. Allowed keys: monday through sunday."`

---

## Bir Temsilciyi duraklat veya devam ettir

`PATCH /agents/{agentId}/active` — Temsilciyi açar veya kapatır. Duraklatılmış bir Temsilci tüm yapılandırmasını korur ancak yanıt vermeyi anında durdurur; devam ettirme işlemi hemen etkili olur.

```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 }),
});
```

**Yanıt** (`200`)

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

`active` gerçek bir boole değeri olmalıdır — başka herhangi bir değer `"active (boolean) is required"` ile `400` döndürür.

---

## Bir Temsilciyi Çoğaltma

`POST /agents/{agentId}/duplicate` — yapılandırması korunmuş bir kopya oluşturur. Kopya, ona bir kanal veya Giriş Noktası atayana kadar hiçbir şey göndermez.

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

**Yanıt** (`201`)

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

Bir kopya, planınızın Temsilci kotasından tıpkı sıfırdan bir tane oluşturuyormuşsunuz gibi düşülür, bu nedenle hesap limitine ulaşıldığında `403` ile reddedilir.

---

## Bir Temsilciyi Silme

`DELETE /agents/{agentId}`

Silme işlemi, Temsilci hala onsuz çalışmayacak bir şeye (bir yayın, bir Giriş Noktası veya eski hesaplarda bir kampanya) bağlıyken reddedilir. Yanıt, nelerin onu tuttuğunu listeler, böylece önce onları ayırıp tekrar deneyebilirsiniz.

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

**Yanıt** (`200`)

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

**Engellendi** (`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": []
}
```

---

## Taslaklar: değişiklikleri yayına almadan önce gözden geçirin

Düzenleyicide yapılan değişiklikler ve [Yapay Zeka ile Optimize Et](#optimize-an-agent-with-ai) tarafından üretilen her türlü yeniden yazım, siz yayınlayana kadar **yayınlanmamış taslak** olarak tutulur. Canlı Temsilci, o zamana kadar mevcut yapılandırmasıyla yanıt vermeye devam eder.

### Taslağı yayınla

`POST /agents/{agentId}/publish-draft` — taslağı canlı yapılandırmaya taşır ve aynı adımda taslağı temizler.

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

**Yanıt** (`200`)

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

`published_keys`, taslaktan canlı Temsilciye taşınan ayarları listeler, böylece nelerin değiştiğini gösterebilirsiniz.

> **Bunu çağırmadan önce bir taslağın var olduğunu kontrol edin.** Taslağı olmayan bir Temsilciyi yayınlamak desteklenen bir çağrı değildir ve şu anda belirli bir mesaj yerine genel bir mesajla `500` olarak döner. Bunun yerine bir taslağı atmak için aşağıdaki atma (discard) işlemini kullanın.

### Taslağı at

`POST /agents/{agentId}/discard-draft` — taslağı atar ve canlı yapılandırmayı olduğu gibi bırakır. Taslak olmadığında çağrılması güvenlidir; hiçbir şey olmaz.

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

---

## Bir Temsilciyi Yapay Zeka ile optimize et

`POST /agents/{agentId}/optimize` — Temsilcinin yapılandırmasını geri bildirimlerinize göre ("sürekli indirim teklif ediyor", "cevaplar çok uzun") yeniden yazar ve yeniden yazılanı canlıya almak yerine **taslak olarak** kaydeder.

Ya `user_feedback` (yalın bir talimat) ya da belirli bir hatalı yanıta tepki verirken, hatalı `thumbs_down_message` ile birlikte `thumbs_down_feedback` gönderin. İkisinden en az biri metin içermelidir.

```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." }'
```

**Yanıt** (`202`)

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

İş arka planda çalışır ve çağrı hemen döner. Temsilciyi `GET /agents/{agentId}` ile okuyun ve `optimize_run.status` kısmını izleyin; `Draft` durumuna döndüğünde, yeniden yazılan metin Temsilcinin taslağı olarak bekliyor olacaktır. Gözden geçirin, ardından yayınlayın veya atın.

Temsilci başına aynı anda yalnızca bir çalışma yapılabilir; biri devam ederken yapılan ikinci bir çağrı `409` döndürür. Bu işlem yapay zeka kredilerini kullanır.

---

## Etiketleme kuralları

Etiketleme kuralı, bir etiket ve bunun ne zaman uygulanacağına dair bir açıklamadan oluşur. Bir görüşme sırasında Temsilci bu açıklamayı okur ve uygun olduğunda kişiyi etiketler; etiket tabanlı otomasyonlar bu şekilde tetiklenir.

**Kural nesnesi**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `name` | Evet | Uygulanacak etiket, örneğin `hot-lead`. |
| `description` | Hayır | Temsilcinin bunu ne zaman uygulaması gerektiği, izleyeceği bir talimat olarak yazılır. |
| `webhook` | Hayır | Temsilci bu etiketi uyguladığında çağrılan URL. |
| `ai_can_remove` | Hayır | Temsilcinin etiketi tekrar kaldırıp kaldıramayacağı. Varsayılan değer `false`. |
| `tag_id` | Hayır | Kuralı ilişkilendirmek için hesabınızdaki mevcut bir etiketin kimliği. Bu olmadan kural, aynı ada sahip etiketle ilişkilendirilir ve eğer yoksa oluşturulur; böylece her kural daha sonra etiket kimliği ile ele alınabilir. |

### Etiketleme kuralı ekle

`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
    }
  }'
```

**Yanıt** (`200`)

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

### Etiketleme kuralını değiştir

`PUT /agents/{agentId}/tags/{tagId}` — kural, yoldaki etiket kimliği ile bulunur ve **bütünüyle değiştirilir**, birleştirilmez; bu nedenle yalnızca değiştirdiğiniz kısmı değil, kuralın tamamını gönderin. İşaret ettiği etiket, `tag_id` öğesini dışarıda bıraksanız bile korunur, bu yüzden bir düzenleme kuralı etiketinden ayıramaz.

```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." } }'
```

### Bir etiketleme kuralını kaldırın

`DELETE /agents/{agentId}/tags/{tagId}` — Temsilci bu etiketi uygulamayı durdurur. Etiketin kendisi ve halihazırda bu etikete sahip olan kişiler etkilenmez.

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

Temsilci mevcut olmadığında **veya** o etiket için herhangi bir kuralı bulunmadığında her iki uç nokta da `404` döndürür.

### Yapay zeka ile etiket kümesi oluşturun

`POST /agents/{agentId}/tags/generate` — Temsilcinin kendi talimatlarını ve hedefini okuyarak bir dizi kuralın tamamını (etiket adları ve her birinin arkasındaki "... olduğunda uygula" ifadesi) tasarlar.

| Alan | Açıklama |
|---|---|
| `mode` | `merge` (varsayılan), Temsilci üzerindeki mevcut kuralları korur ve bunlara ekleme yapar. `replace` ise kümeyi sıfırdan tasarlar. |

```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" }'
```

**Yanıt** (`202`)

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

İşlem arka planda yürütülür. Temsilciyi okuyun ve `tag_generation.status` değerini izleyin; kuralların kendisi Temsilcinin `tags` kısmına yerleşir. Temsilci başına aynı anda yalnızca bir işlem çalışabilir (aksi takdirde `409` hatası alınır) ve bu işlem yapay zeka kredisi kullanır.

---

## Bilgi kaynakları

Bilgi kaynakları, platformun sizin için okuduğu sayfa ve belgelerdir. Bir Temsilciye bir kaynak eklemek, onun bu içerikten yanıt vermesini sağlar.

**Kaynak kimlikleri nereden gelir.** Bilgi tabanı uç noktalarıyla içerik ekleyin — sayfa için `POST /kb-sources/url`, belge için `POST /kb-sources/file`, tüm site için `POST /kb-sources/bulk-import`. Bunlar, hazır olana kadar `GET /kb-sources/{sourceId}` ile sorgulayacağınız bir `source_id` döndürür. `POST /kb-sources/url` ayrıca, içe aktarma biter bitmez kaynağı bir Temsilciye bağlayan `autoLinkToAgentId` parametresini de alır, böylece aşağıdaki bağlama çağrısını atlayabilirsiniz.

### Bilgi kaynaklarını bağlayın

`POST /agents/{agentId}/kb-sources` — tek bir çağrıda bir kümenin tamamını bağlamak için (bir siteyi taradıktan sonra isteyeceğiniz şey) `kb_source_ids` ile bir liste gönderin veya tek bir kaynak için `kb_source_id` kullanın. Birini veya diğerini gönderin. Halihazırda bağlı olan bir şeyi bağlamak hiçbir şeyi değiştirmez.

```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"] }'
```

**Yanıt** (`200`)

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

### Bilgi kaynaklarının bağlantısını kesin

Bir tanesi için `DELETE /agents/{agentId}/kb-sources/{kbSourceId}`, birkaçı için `POST /agents/{agentId}/kb-sources/bulk-remove` ile `kb_source_ids` kullanın. Kimlik listesi gövdede taşındığı için toplu silme işlemi bir `POST`'tür.

```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"] }'
```

Kaynakların kendileri silinmez ve diğer Temsilcileriniz için kullanılabilir durumda kalır. Bağlı olmayan bir şeyi ayırmak hiçbir şeyi değiştirmez.

### SSS

SSS'ler kendi uç noktalarında yönetilir ve oradan bir Temsilciye bağlanır: `{ "agent_id": "ag7HkQ2ZpLxR3mNb" }` ile `POST /faqs/{faqId}/link` ve tekrar kaldırmak için `POST /faqs/{faqId}/unlink`. Bir SSS, herhangi bir sayıda Temsilci tarafından paylaşılabilir. Bkz. [SSS API](faqs.md).

> Bir SSS yalnızca kendisine bağlı Temsilciler tarafından kullanılır; bir tane oluşturmak tek başına yeterli değildir.

---

## Araçlar

### Özel işlevler

`POST /agents/{agentId}/custom-functions`, Temsilcinin konuşmalar sırasında özel işlevlerinizden birini çağırmasına olanak tanır. Yalnızca aynı hesaba ait işlevler eklenebilir ve zaten ekli olan bir işlevi eklemek hiçbir şeyi değiştirmez.

```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}` onu ayırır. İşlevin kendisi silinmez ve diğer Temsilcileriniz için kullanılabilir durumda kalır.

İşlevlerin kendilerini `/custom-functions` üzerinden yönetin — ne oldukları hakkında bilgi için [Özel İşlevler](../ai-automation/custom-functions.md) bölümüne bakın.

### MCP sunucuları

Bir MCP sunucusu, Temsilcinizin kendi başına keşfedip çağırabileceği hazır bir araç paketidir — bkz. [MCP Sunucularını Botunuza Bağlayın](../ai-automation/mcp-servers.md). Sunucular hesapta bir kez kaydedilir, ardından kullanması gereken Temsilcilere eklenir.

> MCP sunucuları, planınızda **özel işlevler** özelliğine ihtiyaç duyar. Bu özellik olmadan, hesap düzeyindeki `/mcp-servers` uç noktaları `403` döndürür. Zaten kayıtlı bir sunucuyu bir Temsilciye eklemek kısıtlanmamıştır.

#### Bir sunucu kaydedin

`POST /mcp-servers`

| Alan | Gerekli | Açıklama |
|---|---|---|
| `name` | Evet | Sunucu için bir etiket. |
| `url` | Evet | Sunucunun adresi. Genel internet üzerinden erişilebilir olmalıdır. |
| `auth_type` | Hayır | Statik bir kimlik doğrulama başlığı için `header` (varsayılan) veya `oauth2`. |
| `auth_header_name` | Hayır | Kimlik bilgisinin gönderileceği başlık. Varsayılan değer `Authorization`. |
| `auth_header_value` | Hayır | Kimlik bilgisinin kendisi. Hiçbir yanıtta geri döndürülmez. |
| `enabled` | Hayır | Sunucunun Temsilciler (Agents) için kullanılabilir olup olmadığı. Varsayılan değer `true`. |
| `enabled_tools` | Hayır | Araç isimleri için izin listesi. `null`, sunucunun sunduğu her aracın açık olduğu anlamına gelir. |
| `tool_policies` | Hayır | Araç ismine göre anahtarlanmış araç bazlı limitler — bir aracın ne sıklıkla çalışabileceği, sonuç önbellekleme ve salt okunur geçersiz kılma. Hepsini temizlemek için `null` gönderin. |

```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"
  }'
```

**Yanıt** (`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", "...": "..." }
}
```

Kaydetme sırasında platform sunucuya bağlanır ve sunduğu araçların listesini önbelleğe alır. **Erişilemeyen bir sunucu yine de kaydedilir**, nedeni `last_error` içinde belirtilir ve araç listesi boş bırakılır; böylece önce kaydı yapıp bağlantı sorununu daha sonra düzeltebilirsiniz.

`oauth2` değerine sahip bir `auth_type`, kaydı `oauth_connected: false` ile ve araçsız olarak kaydeder: henüz bir belirteç (token) yoktur. Bir OAuth sunucusunu yetkilendirmek tarayıcı üzerinden oturum açmayı gerektirir ve bu işlem API üzerinden değil, kontrol panelinden yapılır.

#### Sunucuları listeleme, güncelleme ve silme

- `GET /mcp-servers` — kayıtlı tüm sunucular, en yeniden eskiye doğru, `servers` altında.
- `PUT /mcp-servers/{serverId}` — yalnızca değiştirmek istediklerinizi gönderin. URL'yi veya kimlik doğrulama alanlarını değiştirmek bağlantıyı yeniden test eder ve önbelleğe alınan araç listesini yeniler.
- `DELETE /mcp-servers/{serverId}` — kaydı kaldırır ve etkinleştirilmiş olduğu her Temsilci (Agent) ve kampanyadan bağlantısını keser.

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

**Gizli bilgiler asla geri dönmez.** Yanıtlar, kimlik bilgisi yerine `auth_header_value_set` (bir değerin saklandığını belirten bir `true`/`false` bayrağı) taşır; OAuth belirteçleri ve istemci gizli anahtarları sunucu tarafında kalır. Diğer her şey geri döndürülür: `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`.

#### Bağlantıyı test etme

`POST /mcp-servers/test-connection` — bir sunucuya bağlanır ve araçlarını listeler. Çağırmanın iki yolu vardır:

- `server_id` ile — **kayıtlı** yapılandırmayı test eder ve önbelleğe alınan araç listesini yeniler;
- satır içi `url` (artı `auth_header_name` / `auth_header_value`) ile — hiçbir şeyi saklamayan, kaydetme öncesi bir test.

```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" }'
```

**Yanıt** (`200`)

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

Bağlantı hatası bir HTTP hatası **değildir**; operatörün düzenlediği alanın yanında gösterebilmeniz için neyin yanlış gittiğini açıklayan bir `error` ve `success: false` içeren bir `200` alırsınız.

#### Bir sunucuyu Temsilciye (Agent) bağlama

Bir sunucuyu kaydetmek, herhangi bir Temsilciye (Agent) ona erişim hakkı vermez. Bağlamak için:

```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" }'
```

**Yanıt** (`200`)

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

`DELETE /agents/{agentId}/mcp-servers/{mcpServerId}` bağlantıyı tekrar keser. Sunucunun kendisi silinmez ve diğer Temsilcileriniz için kullanılabilir kalır. Zaten o durumda olan bir şeyi bağlamak veya bağlantısını kesmek hiçbir şeyi değiştirmez.

---

## Medya kütüphanesi

Medya kütüphanesi, bir Temsilcinin (Agent) görüşme sırasında gönderebileceği dosyaları — bir menü, fiyat listesi, ürün fotoğrafı — tutar. Bir Temsilci en fazla **50 öğe** barındırabilir.

### Medyayı listele

`GET /agents/{agentId}/media-library`

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

**Yanıt** (`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
    }
  ]
}
```

Önce Temsilci üzerinde depolanan öğeler, ardından Temsilcinin oluşturulduğu kampanyada hala depolanan eski öğeler gelir; `media_home` (`agent` veya `campaign`) hangisinin hangisi olduğunu belirtir. Her grup içinde en yeni olan önce gelir.

> **`media_url` 7 gün sonra sona erer.** Bu, dosya yüklendiğinde oluşturulan indirme bağlantısıdır; eski bir bağlantıyı bozuk değil, güncelliğini yitirmiş olarak değerlendirin ve yeni bir bağlantı almak için listeyi yeniden okuyun.

### Medya yükle

`POST /agents/{agentId}/media-library` — dosya, **10 MB**'a kadar base64 olarak satır içi yüklenir. Çağrı, dosya depolandığında döner, bu nedenle normal bir isteğe göre biraz daha uzun süre tanıyın. Bu gövdenin camelCase alan adları kullandığını unutmayın.

| Alan | Gerekli | Açıklama |
|---|---|---|
| `base64Data` | Evet | Base64 kodlu, veri-URL öneki olmayan dosya içeriği. |
| `mimeType` | Evet | Dosyanın MIME türü. |
| `fileName` | Evet | Depolanan dosyayı adlandırmak için kullanılan orijinal dosya adı. |
| `title` | Hayır | Kitaplıkta gösterilen kısa etiket. |
| `description` | Hayır | "Temsilci bunu ne zaman göndermeli" talimatı. |
| `sendMessage` | Hayır | Temsilcinin öğeyi gönderirken kullandığı tercih edilen ifade. 500 karakterle sınırlandırılmıştır. |
| `maxSendsPerConversation` | Hayır | Aynı görüşmede aynı kişiye kaç kez gönderilebileceği. Varsayılan değer `1`'dir. |
| `sendAsVoiceNote` | Hayır | Yalnızca ses yüklemeleri — dosyayı WhatsApp sesli notu olarak depolayın. Diğer dosya türleri için yoksayılır. |

```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
  }'
```

İki şey otomatik olarak gerçekleşir: hareketli bir GIF, her kanalda oynatılabilmesi için videoya dönüştürülür ve platform, Temsilcinin ne zaman uygun olduğunu bilmesi için dosyanın içinde gerçekte ne olduğuna dair kısa bir özet yazar.

Bir `400` eksik alanları, desteklenmeyen bir dosya türünü, boş veya aşırı büyük bir dosyayı ve 50 öğelik sınıra ulaşılmasını kapsar. Bir `403`, medya kitaplığının hesap için kapalı olduğu anlamına gelir.

### Bir medya öğesini güncelle

`PATCH /agents/{agentId}/media-library/{itemId}` — yalnızca meta veriler. Dosyanın kendisi değiştirilemez; yeni bir öğe yükleyin ve eskisini silin. Bu gövde snake_case kullanır: `title`, `description`, `send_message`, `max_sends_per_conversation` (negatif olmayan bir tam sayı veya sınırı temizlemek için `null`).

```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 }'
```

**Yanıt** (`200`)

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

### Bir medya öğesini sil

`DELETE /agents/{agentId}/media-library/{itemId}` — öğeyi ve depolanan dosyasını kaldırır. Zaten silinmiş bir öğeyi silmek başarılı olur ve `deleted: false` bildirir, bu nedenle çağrıyı yeniden denemek güvenlidir.

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

---

## Takip mesajları oluştur

`POST /agents/{agentId}/template-generation` — Temsilcinin amacına bağlı olarak, Temsilcinin takip mesajlarını (bir görüşme sessizleştiğinde gönderdiği dürtmeleri) sizin için yazar.

| Alan | Açıklama |
|---|---|
| `type` | `all` (varsayılan) tüm kümeyi yazar. `cold_only` yalnızca hiç yanıt vermeyen kişilere yönelik mesajları yazar. |

```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" }'
```

Bunun geri dönüşünün iki yolu vardır ve `target` alanı size hangisinin olduğunu söyler:

- **`target: "agent"` ve `200`** — mesajlar arama sırasında yazılmıştır ve sonuç `data` içindedir. Bunları Temsilcinin `follow_up_config` kısmından okuyun. Bu olağan durumdur.
- **`target: "campaign"` ve `202`** — iş, `campaign_id` içinde adlandırılan kampanyaya karşı kuyruğa alınmıştır. Bitene kadar o kampanyanın `template_generation_status` kısmını izleyin.

`cold_only` giden bir kampanya gerektirir ve hiçbir kampanyası olmayan bir Temsilcide `409` (`reason: "cold_only_requires_campaign"`) ile reddedilir. `403`, hesap için otomatik takip mesajlarının açık olmadığı anlamına gelir. Bu, yapay zeka kredilerini kullanır ve `"Insufficient credits."` içeren bir `400`, hesabın kredisinin bittiği anlamına gelir.

---

## Görüşmeleri bir Temsilciye yönlendirme

Bir Temsilci yalnızca bir **Giriş Noktasının** kendisine gönderdiği görüşmeleri yanıtlar. Bir kanalın bir giriş noktası olana kadar, daha önce hiç konuşmadığınız birinden gelen ilk mesaj yine de saklanır, ancak hiçbir şey onu almaz ve hiçbir asistan yanıt vermez.

| Ne yapmak istiyorsunuz | Çağrı |
|---|---|
| Bir Temsilciyi tüm kanalın yanıtlayıcısı yapın | `{ "channel": "instagram", "agent_id": "AGENT_ID" }` ile `PUT /entry-points/channel-defaults` |
| Daha dar bir kural ekleyin (anahtar kelimeler, yorumlar, yeni takipçiler) | `POST /agents/{agentId}/entry-points` |
| Bir Temsilciye işaret eden kuralları görün | `GET /agents/{agentId}/entry-points` |
| Bir kanalı kimse yanıtlamayacak şekilde bırakın | `DELETE /entry-points/channel-defaults?channel=instagram` |

### Bir Temsilcinin Giriş Noktalarını listeleme

`GET /agents/{agentId}/entry-points` — görüşmeleri bu Temsilciye gönderen yönlendirme kuralları, en yenisi ilk sırada olacak şekilde. Hem mevcut hem de kullanımdan kaldırılmış kurallar geri döner; kullanımdan kaldırılmış bir kural `enabled: false` değerine sahiptir.

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

Kasıtlı olarak kimsenin yanıtlamayacağı şekilde ayarlanmış bir kanal da dahil olmak üzere tüm hesabın kanal varsayılanları için bunun yerine `GET /entry-points/channel-defaults` okuyun.

### Bir Giriş Noktası oluşturma

`POST /agents/{agentId}/entry-points` — yoldaki Temsilci her zaman kazanır, bu nedenle URL'dekinden farklı bir Temsilci için asla kural oluşturulamaz.

| `type` | Ne işe yarar |
|---|---|
| `channel_default` | Temsilci, listelenen kanallardaki her yeni kişiyi yanıtlar. Bunun için `PUT /entry-points/channel-defaults` tercih edin; bu, önceki yanıtlayıcıyı sizin yerinize devre dışı bırakır, oysa burada ikinci bir varsayılan oluşturmak bunu yapmaz. |
| `keyword` | Temsilci, ilk mesaj `match_config.keywords` öğelerinden birini içerdiğinde devreye girer. En az bir anahtar kelime gereklidir. |
| `instagram_comment` / `facebook_comment` | Temsilci, gönderilerinizdeki yorumları yanıtlar. Eşleşen kanal `channels` içinde listelenmelidir. |
| `instagram_follower` | Temsilci, yeni takipçileri karşılar. |

`channels` gereklidir ve kuralın hangi kanalları kapsadığını belirtir — örneğin `whatsapp`, `whatsapp_web`, `instagram`, `messenger`, `telegram`, `sms`, `email`, `chat_widget` veya `custom_channel`. Aksi belirtilmedikçe yeni kurallar etkindir.

```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"] }
  }'
```

**Yanıt** (`201`)

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

**Birden fazla kuralın mümkün olduğu durumlarda hangisi kazanır:** devam eden bir görüşme veya manuel atama, Temsilciyi zaten sahip olduğu şekilde tutar; aksi takdirde anahtar kelime kuralları yorum kurallarını, yorum kuralları da takipçi kurallarını yener ve kanal varsayılanı son çaredir. Bu kuralların bir hesapta herhangi bir şeye karar verip vermediği `GET /entry-points/routing-status` tarafından rapor edilir.

Bu kısa versiyondur. [Giriş Noktaları API'si](entry-points.md) kılavuzu; tam kademe, yorum ve takipçi kurallarını, WhatsApp numarası başına bir Temsilciyi ve bir kuralı değiştirmeyi veya silmeyi kapsar. Kavram için [Giriş Noktaları](../ai-agents/entry-points.md) bölümüne ve kanalın kendisini bağlamak için [Kanallar API'si](channels.md) bölümüne bakın.

---

## AI Temsilcileri API hataları

Temsilci uç noktaları standart hata zarfını döndürür:

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

| Durum | Bir Temsilci uç noktasında ne zaman gerçekleşir |
|---|---|
| `400` | Gerekli bir alan eksik veya geçersiz — boş bir güncelleme gövdesi, izin verilen bir listenin dışında bir değer (`ai_speed`, `anthropic_model`, `booking_provider`, `mode`, `type`), `availability` içinde hafta içi olmayan bir anahtar, `bot-config` üzerinde noktalı bir alan adı veya yolda hatalı biçimlendirilmiş bir kimlik. |
| `403` | Hesap, gönderdiğiniz bir ayarı kullanmaya izinli değil, planınızın Temsilci sınırındasınız veya bu uç noktanın ihtiyaç duyduğu bir özellik (medya kütüphanesi, takipler, MCP sunucuları için özel işlevler) kapalı. Planınızın izin verdiği yapılandırma boyutunu aşan bir değişiklik `400` ile reddedilir. |
| `404` | Temsilci, etiket kuralı, medya öğesi veya MCP sunucusu bulunamadı — ya mevcut değil ya da başka bir hesaba ait. |
| `409` | Bir şey zaten devam ediyor veya engelliyor: bir optimizasyon veya etiket oluşturma çalışıyor, Temsilci hala bir yayına, Giriş Noktasına veya kampanyaya bağlı veya giden bir kampanya olmadan `cold_only` istendi. |

Her uç noktanın döndürebileceği ortak kodlar — `401`, `403` (planınız API erişimini içermiyor), `429` (hız sınırı) ve `500` — yeniden deneme rehberliği ile birlikte [Hatalar ve Sayfalandırma](errors-and-pagination.md) bölümünde listelenmiştir.

> **Gezgin hakkında bir not.** `/agents` uç noktaları yayınlanmış OpenAPI belirtimindedir, bu nedenle tam alanlarına göz atabilir ve [API Referansında](reference.md) canlı istekler çalıştırabilirsiniz. Hesap düzeyindeki `/mcp-servers` uç noktaları da belirtimdedir, bu nedenle onları da orada keşfedebilirsiniz.


---

## İlgili

- [AI Temsilcileri](../ai-agents/ai-agents.md) — sade bir dille Temsilcinin ne olduğu.
- [Giriş Noktaları](../ai-agents/entry-points.md) — konuşmaların bir Temsilciye nasıl yönlendirildiği.
- [SSS API'si](faqs.md) — Temsilcinizin yanıtladığı bilgileri oluşturun ve bağlayın.
- [Kanallar API'si](channels.md) — bir Temsilcinin yanıt verdiği kanalları bağlayın.
- [MCP Sunucularını Botunuza Bağlayın](../ai-automation/mcp-servers.md) · [Özel İşlevler](../ai-automation/custom-functions.md)
- [API Referansı](reference.md) — tam etkileşimli uç nokta gezgini.