Uçtan Uca Bir Entegrasyon Oluşturun
Bu kılavuz, paneli hiç açmadan kendi kodunuzdan Your AI Connector çalıştırmak için ihtiyacınız olan her şeyi adım adım anlatır. Sonunda şunları yapan minimal bir entegrasyon oluşturmuş olacaksınız:
- Bir API anahtarı ile kimlik doğrulaması yapar
- Bir Yapay Zeka Temsilcisi oluşturur ve asistan davranışını yapılandırır
- Bir mesajlaşma kanalını bağlar (örnek olarak WhatsApp Web kullanıyoruz) ve onu Temsilciye yönlendirir
- Kişileri içe aktarır
- Mesaj gönderir ve okur
- Analitiği okur
- Gerçek zamanlı olaylar için web kancalarına (webhook) abone olur
Her adım, ihtiyaç duyduğunuzda ayrıntılara inebilmeniz için tam kaynak kılavuzuna bağlantı verir. Bu sayfa haritadır; kaynak kılavuzları ise arazinin kendisidir.
Başlamadan önce. API erişimi ücretli bir özelliktir. Planınız bunu içermiyorsa, her istek
403döndürür. Etkinleştirildiğinden emin olmak için API Erişimi bölümüne ve anahtarınızı iletmenin tüm yolları için Kimlik Doğrulama bölümüne bakın.
Aşağıdaki tüm yollar temel URL’ye göredir:
https://api.youraiconnector.com/v1
1. Adım — Bir API anahtarı alın ve ilk isteğinizi yapın
API anahtarınız uygulamada Ayarlar → Entegrasyonlar → API Anahtarı altında bulunur; bu, Entegrasyonlar altında, Web kancalarından ayrı olan ve yalnızca planda API erişimi açık olduğunda görünen özel bir bölümdür. Bir tane oluşturun, kopyalayın ve güvenli bir yerde saklayın (sunucu tarafında bir gizli anahtar deposu veya ortam değişkeni; asla tarayıcı kodunda değil). Tam talimatlar API Erişimi bölümündedir.
Bir anahtarınız olduğunda, sağlık uç noktasını çağırarak çalıştığını doğrulayın. Anahtarı göndermenin birkaç yolu vardır; en basiti ?apiKey= sorgu parametresidir, ancak gerçek kod için anahtarın sunucu günlüklerine veya tarayıcı geçmişine düşmemesi adına X-API-Key başlığını tercih edin.
cURL
curl "https://api.youraiconnector.com/v1/health?apiKey=YOUR_API_KEY"
JavaScript
const BASE = "https://api.youraiconnector.com/v1";
const headers = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" };
const res = await fetch(`${BASE}/health`, { headers });
const data = await res.json();
console.log(data); // { "success": true, ... }
Python
import requests
BASE = "https://api.youraiconnector.com/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}
res = requests.get(f"{BASE}/health", headers=HEADERS)
print(res.json()) # { "success": true, ... }
Her başarılı yanıt aynı zarf içinde paketlenir — bir success: true alanı ve sonuç verisi. Hatalar, bir error mesajı ve bir error_code ile success: false döndürür. Tam liste ve liste uç noktalarının ?limit ve ?cursor ile nasıl sayfalandığı hakkında bilgi için Hatalar ve Sayfalama bölümüne bakın.
Hız sınırı. Kimliği doğrulanmış istekler dakikada 300 ile sınırlandırılmıştır (hesap başına dakikada 1.200’lük daha geniş bir üst sınırla). Bu sınırın aşılması
429döndürür; isteği durdurun ve tekrar deneyin.
Adım 2 — Bir Yapay Zeka Temsilcisi Oluşturun
Bir Yapay Zeka Temsilcisi, asistanınızın davranışını barındıran birimdir: talimatları, hedefi, aktif saatleri ve kişilerle nasıl konuştuğu. Bir konuşmayı yanıtlayan şey budur, bu yüzden oluşturulacak ilk doğal şey budur.
POST /agents ile bir tane oluşturun. name, başlangıçta gönderilmesi gereken tek alandır; diğer her şey aşağıdaki bot-config çağrısı ile ayarlanabilir.
cURL
curl -X POST "https://api.youraiconnector.com/v1/agents" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Inbound WhatsApp Leads",
"language": "en"
}'
JavaScript
const res = await fetch(`${BASE}/agents`, {
method: "POST",
headers,
body: JSON.stringify({
name: "Inbound WhatsApp Leads",
language: "en",
}),
});
const { agent_id } = await res.json();
Python
res = requests.post(
f"{BASE}/agents",
headers=HEADERS,
json={"name": "Inbound WhatsApp Leads", "language": "en"},
)
agent_id = res.json()["agent_id"]
Başarılı bir oluşturma işlemi, yeni kimlik (ID) ile birlikte 201 döndürür:
{
"success": true,
"agent_id": "abc123agent"
}
agent_id değerini kaydedin — kanalları yönlendirirken buna referans vereceksiniz.
Asistanı yapılandırın
PUT /agents/{agentId}/bot-config, asistanın davranışını ayarlar. Gönderdiğiniz alanları mevcut yapılandırmayla birleştirir, bu nedenle dışarıda bıraktığınız her şey korunur:
curl -X PUT "https://api.youraiconnector.com/v1/agents/abc123agent/bot-config" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"instructions": "Greet warmly, answer questions about our services, and offer to book a call.",
"goal": "Book a discovery call.",
"ai_speed": "balanced"
}'
Asistanın yalnızca mesai saatleri içinde yanıt vermesi için PUT /agents/{agentId}/active-hours ile aktif saatleri ayarlayın; bu pencerelerin dışında otomatik olarak yanıt vermez.
Bilgi tabanı. Asistanın kendi içeriğinizden yanıt vermesini sağlamak için SSS’leri ekleyin. SSS kılavuzuna bakın.
Eski: klasik kampanyalar. Hala bir Kampanyalar sayfası olan hesaplar, bunun yerine bir kampanya üzerinde aynı asistan davranışını oluşturur (
POST /campaigns, birtypeve birbotnesnesi ile, ardındanPUT /campaigns/{campaignId}/bot-config). Tam kampanya alan listesi ve yaşam döngüsü kontrolleri Kampanyalar kılavuzundadır. Yeni bir şey oluşturuyorsanız, bir Temsilci oluşturun.
Adım 3 — Bir kanal bağlayın
Bir Temsilcinin mesaj gönderip alabilmesi için bir yola ihtiyacı vardır. API üzerinden yedi bağlantı akışı yönetilebilir: WhatsApp Business, WhatsApp Web, Instagram ve Messenger birlikte (bir paylaşılan Meta akışı), Instagram kişisel hesapları, Telegram, LINE ve Viber. Kalan kanallar (SMS, e-posta, sohbet penceresi ve özel kanallar dahil) REST üzerinden değil, kontrol panelinden ayarlanır ve bağlandıklarında mesajlaşma, kişi ve yönlendirme uç noktaları bunlar üzerinde tamamen aynı şekilde çalışır. GET /channels, belirli bir hesabın aslında neye bağlı olduğunun canlı doğruluk kaynağıdır:
curl "https://api.youraiconnector.com/v1/channels?apiKey=YOUR_API_KEY"
Her kanal için tam bağlanma/bağlantıyı kesme akışları Kanallar kılavuzunda belgelenmiştir. Aşağıda WhatsApp Web sürecini uçtan uca inceliyoruz, çünkü en ilginç modeli gösteriyor: sarmalayıcınızın (wrapper) oluşturması ve sorgulaması gereken bir QR kod eşleştirme akışı.
Uygulamalı örnek: QR kod ile WhatsApp Web eşleştirme
WhatsApp Web eşleştirmesi üç aşamalı bir danstır — başlat, QR’ı getir, bağlanana kadar sorgula.
1. Eşleştirme oturumunu başlatın. Bağlamak istediğiniz numarayı E.164 formatında iletin.
curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "phone_number": "+15551230000" }'
await fetch(`${BASE}/channels/whatsapp-web/connections`, {
method: "POST",
headers,
body: JSON.stringify({ phone_number: "+15551230000" }),
});
requests.post(
f"{BASE}/channels/whatsapp-web/connections",
headers=HEADERS,
json={"phone_number": "+15551230000"},
)
2. QR kodunu getirin ve kullanıcıya gösterin. Bunu her 10-15 saniyede bir sorgulayın. Yanıt, ham qr_code yükünü (bunu kendiniz bir QR görseli olarak oluşturun) ve görüntülenmeye hazır bir qr_data_url içerir.
curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY"
{
"success": true,
"phone_number": "+15551230000",
"status": "qr_pending",
"qr_code": "2@abc...",
"qr_data_url": "data:image/png;base64,iVBORw0KGgo..."
}
Sarmalayıcınızın kullanıcı arayüzünde, qr_data_url öğesini doğrudan bir <img src="..."> içine yerleştirin ve kullanıcıdan telefonundaki WhatsApp → Bağlı Cihazlar kısmından taramasını isteyin. QR’ın süresi dolarsa (bir 410 yanıtı), yeni bir tane almak için 1. adımdan yeniden başlayın.
3. Bağlanana kadar durumu sorgulayın. Kullanıcı tarama yaptıktan sonra, durum uç noktasını connected bildirene kadar sorgulamaya devam edin (hizmet open da bildirebilir). disconnected ve not_initialized durumlarını terminal hatalar olarak değerlendirin.
import time
PHONE = "+15551230000"
while True:
res = requests.get(
f"{BASE}/channels/whatsapp-web/connections/{PHONE}/status",
headers=HEADERS,
)
status = res.json()["status"]
if status in ("connected", "open"):
print("Connected!")
break
if status in ("disconnected", "not_initialized"):
raise RuntimeError(f"Pairing failed: {status}")
time.sleep(5)
async function waitForConnection(phone) {
while (true) {
const res = await fetch(
`${BASE}/channels/whatsapp-web/connections/${encodeURIComponent(phone)}/status`,
{ headers }
);
const { status } = await res.json();
if (status === "connected" || status === "open") return;
if (status === "disconnected" || status === "not_initialized") {
throw new Error(`Pairing failed: ${status}`);
}
await new Promise((r) => setTimeout(r, 5000));
}
}
Dikkat. Bağlı her WhatsApp Web numarası, bağlantısını kesene kadar yinelenen aylık bir bakım ücretine tabidir (
DELETE /channels/whatsapp-web/connections/{phoneNumber}).
Kanalı Temsilcinize yönlendirin
Bir kanalı bağlamak onun çalışmasını sağlar; onu yönlendirmek ise platforma, yeni gelen gelen konuşmaları hangi Yapay Zeka Temsilcisinin yanıtlaması gerektiğini söyler. Kanal için kanal varsayılanı Giriş Noktasını ayarlayın ve 2. Adımda oluşturduğunuz Temsilciyi adlandırın:
curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "channel": "whatsapp_web", "agent_id": "abc123agent" }'
Çağrıyı kanal başına bir kez tekrarlayın — kanal başına bir kanal varsayılanı. Bir kanalı hiçbir Temsilci yanıtlamayacak şekilde bırakmak için DELETE /entry-points/channel-defaults?channel=whatsapp_web çağrısını yapın; Giriş Noktaları kademesinin hesap için canlı olup olmadığını kontrol etmek için GET /entry-points/routing-status çağrısını yapın. Eski POST /channels/campaign haritası yalnızca geri alma için tutulur ve artık gelen yönlendirme için kullanılmaz. Diğer kanal türleri ve WhatsApp Business OAuth akışı için Kanallar kılavuzuna bakın.
4. Adım — Kişilerinizi içe aktarın
Kanal canlıya alındığında, ulaşmak istediğiniz kişileri yükleyin. İçe aktarma uç noktası çağrı başına 500’e kadar kayıt alır. Her kaydın uluslararası formatta bir phone_number değerine ihtiyacı vardır; diğer her şey isteğe bağlıdır. Hatalı numaralara, desteklenmeyen kanallara veya zaten mevcut olan numaralara sahip kayıtlar atlanır; her atlama işlemi, dizini ve nedeni ile birlikte raporlanır, böylece yalnızca başarısız olanları tekrar deneyebilirsiniz.
cURL
curl -X POST "https://api.youraiconnector.com/v1/contacts/import" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contacts": [
{ "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee" },
{ "phone_number": "+12025551235", "first_name": "Bob" }
],
"defaultChannel": "whatsapp_web"
}'
JavaScript
const res = await fetch(`${BASE}/contacts/import`, {
method: "POST",
headers,
body: JSON.stringify({
contacts: [
{ phone_number: "+12025551234", first_name: "Ann", last_name: "Lee" },
{ phone_number: "+12025551235", first_name: "Bob" },
],
defaultChannel: "whatsapp_web",
}),
});
const result = await res.json();
console.log(`${result.imported} imported, ${result.skipped.length} skipped`);
Python
res = requests.post(
f"{BASE}/contacts/import",
headers=HEADERS,
json={
"contacts": [
{"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee"},
{"phone_number": "+12025551235", "first_name": "Bob"},
],
"defaultChannel": "whatsapp_web",
},
)
result = res.json()
print(f"{result['imported']} imported, {len(result['skipped'])} skipped")
Yanıt size tam olarak ne olduğunu söyler:
{
"success": true,
"imported": 2,
"contact_ids": ["contactId1", "contactId2"],
"skipped": []
}
Tek tek oluşturma, listeleme/arama, listeler, etiketler ve özel alanlar için Kişiler kılavuzuna bakın.
5. Adım — Mesaj gönderin ve okuyun
Mesaj gönderin
En basit gönderim kanaldan bağımsızdır: kişinin kimliğini ve mesaj gövdesini verin, platform bunu kişinin bulunduğu kanalda iletir. contact_id ile veya channel artı eşleşen kimlik alanı (WhatsApp/WhatsApp Web/SMS için phone_number, Instagram için instagram_id vb.) ile hedefleme yapabilirsiniz.
cURL
curl -X POST "https://api.youraiconnector.com/v1/contacts/send" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel": "whatsapp_web",
"phone_number": "+12025551234",
"body": "Hi Ann! Thanks for reaching out."
}'
JavaScript
const res = await fetch(`${BASE}/contacts/send`, {
method: "POST",
headers,
body: JSON.stringify({
channel: "whatsapp_web",
phone_number: "+12025551234",
body: "Hi Ann! Thanks for reaching out.",
}),
});
const { message_id } = await res.json();
Python
res = requests.post(
f"{BASE}/contacts/send",
headers=HEADERS,
json={
"channel": "whatsapp_web",
"phone_number": "+12025551234",
"body": "Hi Ann! Thanks for reaching out.",
},
)
message_id = res.json()["message_id"]
Teslimat eşzamansızdır — bir 201, mesajın kabul edildiği ve sıraya alındığı, henüz teslim edilmediği anlamına gelir. (Rahatsız etmeyin veya özel mod açık olan kişiler 422 ile reddedilir.)
{
"success": true,
"message_id": "aB3dE5fG7hI9jK1lM2nO",
"contact_id": "contact123",
"channel": "whatsapp_web"
}
Bir konuşmayı okuyun
Mesajları geriye dönük okumak için, imleç sayfalama (cursor pagination) ile kişiye göre, en yeniden eskiye doğru listeleyin. Geçmişte geriye doğru gitmek için bir yanıttan aldığınız next_cursor değerini bir sonrakinin cursor değeri olarak iletin.
curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY"
res = requests.get(
f"{BASE}/contacts/contact123/messages",
headers=HEADERS,
params={"limit": 50},
)
page = res.json()
for msg in page["messages"]:
print(msg)
next_cursor = page["next_cursor"] # pass back as ?cursor= for the next page
Ayrıca içerik türüne (?filter=text|media|tool_use) veya yöne (?direction=inbound|outbound) göre filtreleme yapabilirsiniz. Mesajlar kılavuzu; medya eklerini, mesajları okundu olarak işaretlemeyi ve oturum başına mesaj görünümlerini kapsar.
Yanıtlar için yoklama (poll) yapmayın. Mesajları bir zamanlayıcı ile listelemek işe yarar ancak istekleri boşa harcar ve gecikmeye neden olur. Gelen mesajlar için bunun yerine web kancalarını (webhook) kullanın; bu 7. Adımdır.
6. Adım — Analitikleri okuma
Mesajlar akmaya başladığında, analiz özeti size bir tarih aralığındaki toplu sayıları verir: gönderilen, iletilen, okunan, yanıtlanan, rezerve edilen, oluşturulan kişiler ve harcanan/yüklenen krediler. Hem aralık toplamlarını hem de sıfır dolgulu günlük serileri alırsınız; bu, bir kontrol paneli grafiği için mükemmeldir. İsteğe bağlı olarak bunu campaign_id ile tek bir kampanyaya göre kapsamlandırabilirsiniz (aşağıdaki örnekler bir yer tutucu kampanya kimliği olan abc123campaign kullanır); hesap genelindeki toplamlar için parametreyi boş bırakın.
curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY"
const params = new URLSearchParams({
from: "2026-05-01",
to: "2026-05-31",
campaign_id: "abc123campaign",
});
const res = await fetch(`${BASE}/analytics/summary?${params}`, { headers });
const { totals, by_date } = await res.json();
res = requests.get(
f"{BASE}/analytics/summary",
headers=HEADERS,
params={"from": "2026-05-01", "to": "2026-05-31", "campaign_id": "abc123campaign"},
)
data = res.json()
totals = data["totals"]
by_date = data["by_date"]
Aralık varsayılan olarak son 30 gündür ve 366 gün ile sınırlandırılmıştır. Kredi bazlı kullanım kayıtları ve yapay zeka maliyet dökümleri için Analitik kılavuzuna bakın.
7. Adım — Gerçek zamanlı olaylar için web kancalarına (webhook) abone olma
Yoklama (polling) hızlı bir betik için iyidir, ancak gerçek bir entegrasyon push tabanlı olmalıdır. Web kancaları, platformun bir şey olduğu anda sizin sunucunuzu çağırmasını sağlar; yeni bir kişi, bir yanıt, alınan bir randevu, tamamlanan bir sohbet gibi.
Öncelikle, abone olabileceğiniz tam olay adlarını keşfedin:
curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY"
{
"success": true,
"events": [
"Contact Created",
"Human Alerted",
"Appointment Booked",
"Replies",
"New Message",
"Chat Concluded",
"Task Created",
"Daily Summary Created"
]
}
Ardından, sunucunuzdaki bir HTTPS URL’sini işaret eden bir abonelik oluşturun. Yukarıdaki çağrıdan elde ettiğiniz tam olay dizelerini kullanın.
cURL
curl -X POST "https://api.youraiconnector.com/v1/webhooks" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example.com/incoming",
"subscribed_to": ["Contact Created", "Replies"],
"name": "Lead updates hook"
}'
JavaScript
const res = await fetch(`${BASE}/webhooks`, {
method: "POST",
headers,
body: JSON.stringify({
url: "https://hooks.example.com/incoming",
subscribed_to: ["Contact Created", "Replies"],
name: "Lead updates hook",
}),
});
const { webhook_id } = await res.json();
Python
res = requests.post(
f"{BASE}/webhooks",
headers=HEADERS,
json={
"url": "https://hooks.example.com/incoming",
"subscribed_to": ["Contact Created", "Replies"],
"name": "Lead updates hook",
},
)
webhook_id = res.json()["webhook_id"]
{
"success": true,
"webhook_id": "1",
"webhook": {
"id": "1",
"name": "Lead updates hook",
"url": "https://hooks.example.com/incoming",
"subscribed_to": ["Contact Created", "Replies"],
"subscribed_to_tags": [],
"created_at": "2026-06-09T12:00:00.000Z"
}
}
URL HTTPS kullanmalı ve herkese açık olarak erişilebilir olmalıdır. Bundan sonra sunucunuz, abone olunan her olay için bir POST isteği alır. Test gönderimi yapabilir, bir aboneliğin durumunu kontrol edebilir ve tekrarlanan hatalardan sonra otomatik olarak devre dışı bırakılan bir aboneliği yeniden etkinleştirebilirsiniz; yük şekilleri ve doğrulama için Web kancaları kılavuzuna ve entegrasyon düzeyindeki Web kancaları sayfasına bakın.
Hepsini bir araya getirme
İşte bir bakışta tüm akış:
| Adım | Hedef | Ana çağrı |
|---|---|---|
| 1 | Kimlik doğrulama | GET /health |
| 2 | Asistanı oluştur + ayarla | POST /agents, PUT /agents/{id}/bot-config, PUT /agents/{id}/active-hours |
| 3 | Bir kanal bağla ve yönlendir | POST /channels/whatsapp-web/connections → QR’yi tara + durum → PUT /entry-points/channel-defaults |
| 4 | Kişileri yükle | POST /contacts/import |
| 5 | Gönder & oku | POST /contacts/send, GET /contacts/{id}/messages |
| 6 | Ölçümle | GET /analytics/summary |
| 7 | Gerçek zamanlı tepki ver | POST /webhooks |
Minimal bir sarmalayıcı, kendi kullanıcı arayüzünüze bağlanmış bu yedi çağrıdan ibarettir. Buradan itibaren, daha fazlasına ihtiyaç duydukça kaynak bazlı kılavuzları ekleyebilirsiniz:
- Kampanyalar · Kişiler · SSS · Mesajlar · Randevular
- Kanallar · Şablonlar · Analitikler · Web kancaları · API Anahtarları
- Yeni misiniz? Başlarken · Kimlik Doğrulama · Hatalar & Sayfalama
Stuck on something this guide does not cover? Email hi@youraiconnector.com.