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)
• Hatalar ve sayfalama — bkz. Hatalar ve Sayfalama

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

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

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

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

Sorgu parametreleri

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

Yanıt (200)

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

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

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

Yanıt (201)

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

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

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

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

Yanıt (200)

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

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.

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)

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

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

Yanıt (200)

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

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

Yanıt (201)

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

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

Yanıt (200)

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

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

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

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

Yanıt (200)

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

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.

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)

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

Etiketleme kuralı ekle #

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

Yanıt (200)

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

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.

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.

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)

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

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)

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

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.

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.

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

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)

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

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.

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)

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

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)

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

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

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

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

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

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)

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

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.

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.

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.

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.

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.

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)

{ "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 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ı bölümüne ve kanalın kendisini bağlamak için Kanallar API’si bölümüne bakın.

AI Temsilcileri API hataları #

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

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

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 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 canlı istekler çalıştırabilirsiniz. Hesap düzeyindeki /mcp-servers uç noktaları da belirtimdedir, bu nedenle onları da orada keşfedebilirsiniz.

İlgili #

• AI Temsilcileri — sade bir dille Temsilcinin ne olduğu.
• Giriş Noktaları — konuşmaların bir Temsilciye nasıl yönlendirildiği.
• SSS API’si — Temsilcinizin yanıtladığı bilgileri oluşturun ve bağlayın.
• Kanallar API’si — bir Temsilcinin yanıt verdiği kanalları bağlayın.
• MCP Sunucularını Botunuza Bağlayın · Özel İşlevler
• API Referansı — tam etkileşimli uç nokta gezgini.