# 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: 1. Bir API anahtarı ile kimlik doğrulaması yapar 2. Bir Yapay Zeka Temsilcisi oluşturur ve asistan davranışını yapılandırır 3. Bir mesajlaşma kanalını bağlar (örnek olarak WhatsApp Web kullanıyoruz) ve onu Temsilciye yönlendirir 4. Kişileri içe aktarır 5. Mesaj gönderir ve okur 6. Analitiği okur 7. 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 `403` döndürür. Etkinleştirildiğinden emin olmak için [API Erişimi](../integrations/api-access.md) bölümüne ve anahtarınızı iletmenin tüm yolları için [Kimlik Doğrulama](authentication.md) 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](../integrations/api-access.md) 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** ```bash curl "https://api.youraiconnector.com/v1/health?apiKey=YOUR_API_KEY" ``` **JavaScript** ```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** ```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](errors-and-pagination.md) 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ı `429` dö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** ```bash 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** ```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** ```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: ```json { "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: ```bash 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](faqs.md) bakın. > **Eski: klasik kampanyalar.** Hala bir **Kampanyalar** sayfası olan hesaplar, bunun yerine bir kampanya üzerinde aynı asistan davranışını oluşturur (`POST /campaigns`, bir `type` ve bir `bot` nesnesi ile, ardından `PUT /campaigns/{campaignId}/bot-config`). Tam kampanya alan listesi ve yaşam döngüsü kontrolleri [Kampanyalar kılavuzundadır](campaigns.md). 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: ```bash 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](channels.md) 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. ```bash 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" }' ``` ```javascript await fetch(`${BASE}/channels/whatsapp-web/connections`, { method: "POST", headers, body: JSON.stringify({ phone_number: "+15551230000" }), }); ``` ```python 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. ```bash curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY" ``` ```json { "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 `` 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. ```python 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) ``` ```javascript 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: ```bash 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](channels.md) 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** ```bash 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** ```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** ```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: ```json { "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](contacts.md) 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** ```bash 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** ```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** ```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.) ```json { "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. ```bash curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY" ``` ```python 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](messages.md); 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. ```bash curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY" ``` ```javascript 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(); ``` ```python 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](analytics.md) 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: ```bash curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY" ``` ```json { "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** ```bash 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** ```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** ```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"] ``` ```json { "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](webhooks.md) ve entegrasyon düzeyindeki [Web kancaları](../integrations/webhooks.md) 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](campaigns.md) · [Kişiler](contacts.md) · [SSS](faqs.md) · [Mesajlar](messages.md) · [Randevular](appointments.md) - [Kanallar](channels.md) · [Şablonlar](templates.md) · [Analitikler](analytics.md) · [Web kancaları](webhooks.md) · [API Anahtarları](api-keys.md) - Yeni misiniz? [Başlarken](getting-started.md) · [Kimlik Doğrulama](authentication.md) · [Hatalar & Sayfalama](errors-and-pagination.md) Stuck on something this guide does not cover? Email [hi@youraiconnector.com](mailto:hi@youraiconnector.com).