Giriş Noktaları API’si #

Bir Giriş Noktası bir yönlendirme kuralıdır: “bu kanalda bu olduğunda, konuşmayı bu Temsilciye devret”. Bir kanal bağlamak mesajların hesaba ulaşmasını sağlar ve bir Temsilci oluşturmak size yanıt verebilecek birini sunar, ancak ikisi de bir yabancının ilk mesajını kimin yanıtlayacağına karar vermez. Giriş Noktaları buna karar verir. Ürünün kendisi için Giriş Noktaları kılavuzuna bakın.

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

API gezgininde. Bu sayfadaki her uç nokta, yayınlanmış OpenAPI spesifikasyonunda yer alır, böylece tam alanlarına göz atabilir ve API gezgininde canlı istekler çalıştırabilirsiniz.

Çoğu entegrasyonun ihtiyaç duyduğu tek çağrı #

Bir kanal bağlayın, bir Temsilci oluşturun, ardından kanalı Temsilciye yönlendirin:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

“Bu Temsilci WhatsApp’ı yanıtlar” için tüm kurulum budur. Bu sayfadaki diğer her şey daha dar kurallar (anahtar kelimeler, yorumlar, yeni takipçiler), bir kanaldaki birkaç numara ve yapılandırılmış olanı geri okumak içindir.

Yönlendirmeye nasıl karar verilir #

Bir mesaj geldiğinde, platform sabit bir merdivenden iner ve karar veren ilk adım kazanır:

1. Bir insan konuşmayı devralmıştır — yapay zeka yok.
2. Kişi zaten bir Temsilciye atanmıştır, manuel olarak veya o Temsilci ile bir konuşma devam ettiği için — aynı Temsilci konuşmayı sürdürür. Giriş Noktaları mevcut bir konuşmayı asla taşımaz; bir sohbeti farklı bir Temsilciye devretmek için atayın (uygulamada veya Otomasyonlar eylemi ile).
3. Kişi bir yayına yanıt veriyor — yayının Temsilcisi yanıtlar veya yayının Temsilcisi yoksa kimse yanıtlamaz.
4. Dar bir Giriş Noktası eşleşiyor. Anahtar kelime kuralları, yorum kurallarını; yorum kuralları da takipçi kurallarını yener. Aynı türden iki kural arasında, en son güncellenen kazanır.
5. Kanal varsayılanı, mesajın geldiği kanal için. Kişinin yazdığı belirli bir numaraya kapsamlı bir varsayılan, kanal genelindeki varsayılanı yener.
6. Hiçbir şey eşleşmedi — mesaj ekibiniz için gelen kutusuna düşer ve hiçbir asistan yanıt vermez.

İki şey 6. adımı yumuşatır. Tam olarak bir aktif Temsilcisi olan ve kanal için yapılandırılmış bir varsayılanı olmayan bir hesap, yine de yanıtlayıcı olarak o Temsilciyi alır, bu nedenle WhatsApp’ı bağlayan ve bir test mesajı gönderen yeni bir hesap sessizlikle karşılaşmaz. Bu taban, anahtar kelime kuralı olan bir kanala asla uygulanmaz (orada, hiçbir anahtar kelimeyle eşleşmeyen bir mesaj kasıtlı olarak bir insana bırakılır) ve kimsenin yanıtlamadığı bir kanal olarak ayarladığınız bir kanalı asla geçersiz kılmaz (bkz. Kimsenin yanıtlamadığı bir kanal bırakma).

Merdivenin bir hesap için canlı olup olmadığı GET /entry-points/routing-status tarafından bildirilir. Bugün her hesap için açıktır; çağrı, bir entegrasyonun varsaymak yerine kontrol edebilmesi için mevcuttur.

Giriş Noktası nesnesi #

{
  "id": "ep3KmQ8vTzXr5nWd",
  "type": "keyword",
  "channels": ["whatsapp", "instagram"],
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "enabled": true,
  "match_config": {
    "keywords": ["pricing", "quote"]
  },
  "first_response_mode": null,
  "first_response_exact_text": null,
  "public_comment_reply_exact_text": null,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

Kural türleri #

Kanal varsayılanı olmayan bir kanaldaki anahtar kelime kuralı, bir geçit görevi de görür: hiçbir anahtar kelimeyle eşleşmeyen mesajlar otomatik yanıt almaz ve tek bir Temsilcinin bulunduğu bir hesapta bile doğrudan gelen kutunuza düşer.

Bir kanalı bir Temsilciye yönlendirme #

PUT /entry-points/channel-defaults — bir kanaldaki yeni kişiler için bir Temsilciyi yanıtlayıcı yapar. O kanalın varsayılanı olarak ayarlanmış diğer tüm Temsilciler aynı çağrıda devre dışı bırakılır, böylece bir kanalın her zaman tam olarak bir yanıtlayıcısı olur. Hali hazırda varsayılan olan Temsilciyi ayarlamak hiçbir şeyi değiştirmez.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ channel: "instagram", agent_id: "ag7HkQ2ZpLxR3mNb" }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb"},
)
data = res.json()

Yanıt

{
  "success": true,
  "entry_point_id": "ep3KmQ8vTzXr5nWd",
  "disabled_entry_point_ids": ["epPrevious1234"]
}

entry_point_id şu anda yürürlükte olan kuraldır; disabled_entry_point_ids, ona yer açmak için devre dışı bırakılan kuralları listeler (değiştirilecek bir şey olmadığında boştur). Yalnızca daha önce hiç konuşmadığınız kişiler etkilenir; bir Temsilciyle halihazırda görüşme halinde olan herkes o Temsilciyle kalmaya devam eder.

400, channel veya agent_id eksik, Temsilci başka bir hesaba ait veya phone_number bağlı numaralarınızdan biri değil anlamına gelir.

Her kanalı kimin yanıtladığını görme #

GET /entry-points/channel-defaults — hesap üzerindeki her kanal varsayılanı, en yenisi ilk sırada olacak şekilde, kullanımdan kaldırılanlar (enabled: false) ve kasıtlı olarak hiç kimse olarak ayarlanmış bir kanal (agent_id: "") dahil. Mevcut durum için enabled üzerinde kendiniz filtreleme yapın.

cURL

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

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Yanıt

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": {},
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    },
    {
      "id": "epAEnhHoozpoGVze",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "agRotterdamBranch",
      "enabled": true,
      "match_config": { "phone_numbers": ["+31685101091"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

Bu, hesap genelindeki okumadır. Bir Temsilcinin kurallarını GET /agents/{agentId}/entry-points ile listelemek, hiç kimse olarak ayarlanmış bir kanalı gösteremez, çünkü bu kural hiçbir Temsilciye ait değildir.

Kimsenin yanıtlamadığı bir kanaldan ayrılma #

DELETE /entry-points/channel-defaults?channel=instagram — bir kanal için kanal genelindeki varsayılanı kullanımdan kaldırır. Kanal, gövdede değil, bir sorgu parametresi olarak adlandırılır. Yalnızca o numaranın varsayılanını temizlemek ve numaranın kanalı kim yanıtlıyorsa ona geri dönmesini sağlamak için &phone_number=%2B31685101091 ekleyin.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    params={"channel": "instagram"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Yanıt

{ "success": true, "disabled_entry_point_ids": ["ep3KmQ8vTzXr5nWd"] }

Tekrarlanması güvenlidir: varsayılanı olmayan bir kanalı temizlemek, boş bir listeyle 200 sonucunu verir. Temizlemek ayarı kaldırmak demektir, sessize almak değil — tam olarak bir aktif Temsilcinin bulunduğu bir hesapta, yapılandırılmamış bir kanal yine de o Temsilciye geri döner. Yapay zekayı bir kanaldan tamamen uzak tutmak için, uygulamanın Yeni Konuşmaları Kim Yanıtlar panelinde o kanal için Kimse yanıtlamıyor seçeneğini belirleyin (bu, geri dönüşün asla geçersiz kılmayacağı açık bir “hiç kimse” varsayılanı yazar) veya PATCH /agents/{agentId}/active ile Temsilciyi duraklatın.

WhatsApp numarası başına bir Temsilci #

Yönlendirme varsayılan olarak kanal başınadır: tüm WhatsApp numaralarınız bir yanıtlayıcıyı paylaşır. WhatsApp Business veya WhatsApp Web’de bağlı iki veya daha fazla numara ile, bir varsayılan tek bir numarayla sınırlandırılabilir; böylece şube veya marka başına bir numarası olan bir işletme, tek bir hesap içinde her birine kendi Temsilcisini atayabilir.

Set çağrısı ile phone_number gönderin:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "agent_id": "agRotterdamBranch",
    "phone_number": "+31685101091"
  }'

• Numara, bağlı numaralar altında göründüğü şekilde (E.164 ve + ile) yazılmış, o kanaldaki bağlı numaralarınızdan biri olmalıdır; bunun dışındaki her şey 400 hatasına yol açar.
• Kural, match_config.phone_numbers: ["+31685101091"] ile kanal varsayılanı olarak kaydedilir. O numaraya gelen bir mesaj kendi Temsilcisine gider; diğer tüm numaralar kanal genelindeki varsayılanı izlemeye devam eder.
• Kanal genelindeki varsayılanı ayarlamak veya temizlemek, numaraya özel kuralları etkilemez; aynı durum tersi için de geçerlidir. Bir numaranın kendi kuralını DELETE /entry-points/channel-defaults?channel=whatsapp_web&phone_number=%2B31685101091 ile temizleyin.
• Yanıtlar her zaman kişinin yazdığı numaradan gönderilir, böylece kişi aynı numara ve aynı Temsilci ile görüşmeye devam eder.

Daha dar kapsamlı bir kural ekleyin #

POST /agents/{agentId}/entry-points — bir anahtar kelime, yorum veya takipçi kuralı (veya bir kanal varsayılanı) oluşturur (ancak bunun için PUT /entry-points/channel-defaults daha iyi bir seçenektir çünkü önceki yanıtlayıcıyı sizin yerinize devre dışı bırakır). Yoldaki Temsilci her zaman önceliklidir: bir kural, hiçbir zaman URL’dekinden farklı bir Temsilci için oluşturulamaz.

cURL

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

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "keyword",
      channels: ["whatsapp", "instagram"],
      match_config: { keywords: ["pricing", "quote"] },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "type": "keyword",
        "channels": ["whatsapp", "instagram"],
        "match_config": {"keywords": ["pricing", "quote"]},
    },
)
data = res.json()

Yanıt (201)

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

Yalnızca iki belirli gönderide “LINK” diyen yorumlara tepki veren, iki dakika bekleyen ve sabit bir ilk mesaj gönderen bir yorumdan DM’e kuralı:

{
  "type": "instagram_comment",
  "channels": ["instagram"],
  "match_config": {
    "keywords": ["LINK"],
    "post_ids": ["17895695668004550", "17841400008460056"],
    "delay_minutes": 2
  },
  "first_response_mode": "exact_text",
  "first_response_exact_text": "Hi {{first_name}}, here is the link you asked for: https://example.com/guide",
  "public_comment_reply_exact_text": "Sent you a DM!"
}

İzlenen gönderilere yorum yapan herkese DM göndermek için keywords alanını, her gönderiyi izlemek için post_ids alanını boş bırakın. Bir 400, neyin yanlış olduğunu belirtir: bilinmeyen bir type, boş bir channels, anahtar kelimeleri olmayan bir anahtar kelime kuralı veya kendi kanalını listelemeyen bir yorum kuralı.

Bir Temsilcinin kurallarını listeleyin #

GET /agents/{agentId}/entry-points — konuşmaları bu Temsilciye gönderen kurallar, en yeniden eskiye doğru: kanal varsayılanları, anahtar kelime kuralları, yorum kuralları ve takipçi kuralları. Devre dışı bırakılan kurallar da enabled: false ile geri gelir.

cURL

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

JavaScript

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

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Yanıt

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "keyword",
      "channels": ["whatsapp", "instagram"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": { "keywords": ["pricing", "quote"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

Bir kuralı değiştirin #

PUT /entry-points/{entryPointId} — bir kuralı değiştirir. Yalnızca değiştirdiğiniz alanları gönderin; iç içe geçmiş ayarlar, "match_config.keywords" gibi noktalı bir anahtarla tek tek ele alınabilir. Değişiklik type, channels veya match_config alanlarına dokunduğunda, kuralın tamamı yeniden kontrol edilir; bu nedenle kısmi bir düzenleme asla kullanılamaz bir kural bırakamaz (anahtar kelimeler sağlanmadan type değerini keyword değerine değiştirmek reddedilir). agent_id göndermek, kuralı diğer Temsilcilerinizden birine devreder; boş bir değer reddedilir. Sahiplik ve kimlik alanları göz ardı edilir.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "match_config": { "keywords": ["pricing", "quote", "demo"] } }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ match_config: { keywords: ["pricing", "quote", "demo"] } }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"match_config": {"keywords": ["pricing", "quote", "demo"]}},
)
data = res.json()

Yanıt

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

Diğer yaygın düzenlemeler: { "enabled": false } bir kuralı silmeden devre dışı bırakır ve { "agent_id": "agOtherAgent" } onu farklı bir Temsilciye taşır. Boş bir gövde, "No fields to update" ile 400 döndürür.

Bir kuralı silin #

DELETE /entry-points/{entryPointId} — kuralı kalıcı olarak kaldırır. Başka hiçbir şey bir Giriş Noktasına referans vermez, bu nedenle önce ayrıştırılması gereken bir şey yoktur.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Yanıt

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

Bir kuralın çalışmasını durdurmak ancak tutmak istiyorsanız, enabled değerini false olarak ayarlayın. Özellikle kanal varsayılanları genellikle silinmek yerine devre dışı bırakılır; DELETE /entry-points/channel-defaults bunu yapar.

Yönlendirmenin canlı olduğunu kontrol edin #

GET /entry-points/routing-status — Giriş Noktaları (Entry Points) kademesinin bu hesapta kimin yanıt vereceğine karar verip vermediğini döndürür. Görüntüleme erişimiyle okunabilir, böylece bir ekip arkadaşı da sahibinin gördüğü yanıtı görür.

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

{ "success": true, "cutover_enabled": true }

Bugün her hesapta true durumundadır. Çağrı tutulur, böylece bir entegrasyon, yönlendirme değişikliğinin canlı olduğunu varsaymak yerine, bildirmeden önce doğrulayabilir.

Daha eski, kampanya şeklindeki çağrılar #

Temsilcilerden (Agents) önceki dönemden kalan iki uç nokta, kampanya etrafında düzenlenmiş hesaplar için hala çalışmaktadır. Yeni entegrasyonlar yukarıdaki kanal varsayılanları çağrılarını kullanmalıdır.

• PUT /channel-routing/{channel} ve { "campaignId": "cp5NbV8xQrT2wYzA" } ile — bir kampanya adlandırır ve o kampanyanın Temsilcisi kanalın yanıtlayıcısı olur. { "campaignId": null } kanalı temizler. Yalnızca giden aramalara yönelik bir kampanya, sunabileceği herhangi bir gelen arama davranışı olmadığından reddedilir.
• POST /channel-routing/clear ve { "channels": ["whatsapp", "instagram"] } ile — genellikle başka bir yere yönlendirmeden önce, birden fazla kanalı onları yanıtlayan Temsilciden tek bir çağrıda serbest bırakır. Yanıt, aslında bir yanıtlayıcısı olanları, yani released_channels listeler.

Her ikisi de sessize almak yerine ayarı kaldırır: tam olarak bir aktif Temsilcisi olan bir hesapta, serbest bırakılan bir kanal yine de o Temsilciye geri döner.

Giriş Noktaları API hataları #

Giriş Noktası uç noktaları standart hata zarfını döndürür:

{
  "success": false,
  "error": "Entry point 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.

Sonraki adımlar #

• Giriş Noktaları — kavram, kural türleri ve uygulamadaki Yeni Konuşmaları Kim Yanıtlar paneli.
• Yapay Zeka Temsilcileri API’si — bu kuralların yönlendirdiği Temsilcileri oluşturun ve yapılandırın.
• Kanallar API’si — kanalların kendisini bağlayın.
• Yorumdan DM’ye Otomasyon — yorum kuralları tetiklendiğinde ne yapar.