API Erişimi #

Bir API (Uygulama Programlama Arayüzü), farklı yazılım sistemlerinin birbiriyle konuşmasını sağlayan bir yoldur. Your AI Connector API’si, (sizin veya geliştiricinizin) kontrol panelini kullanmadan otomatik olarak kişiler oluşturmanıza, mesaj göndermenize, listeleri yönetmenize ve özel kanallardan gelen mesajları almanıza olanak tanır.

Neden API kullanmalısınız? Uygulamayı yerleşik entegrasyonu olmayan bir araca bağlamak istiyorsanız veya tekrarlayan görevleri ölçekli bir şekilde otomatikleştirmeniz gerekiyorsa, API bunun için en doğru yoldur.

API Anahtarınızı Oluşturma #

1. Sol kenar çubuğunda Ayarlar’a (dişli simgesi) tıklayın.
2. Ayarlar kenar çubuğunda, Entegrasyonlar grubunun altında API Anahtarı’na tıklayın.

3. Henüz bir anahtarınız yoksa, API anahtarı oluştur’a tıklayın.
4. Zaten bir anahtarınız varsa, Anahtarınız altında maskelenmiş olarak gösterilir. Anahtarınız destekliyorsa, ortaya çıkarmak için Göster’e, ardından kopyalamak için Kopyala’ya tıklayın; bir onay bildirimi göreceksiniz.
5. Anahtarı güvenli bir yerde saklayın; her API isteği için ona ihtiyacınız olacak.

Ekip üyeleri: API anahtarı hesap sahibine aittir, bu nedenle davetli bir ekip üyesi (Yönetici dahil) olarak oturum açtıysanız, bölüm anahtar yerine bir not gösterir. Görüntülemek, kopyalamak veya yeniden oluşturmak için hesap sahibi olarak oturum açın; bu durum kapsamlı (scoped) anahtarlar için de geçerlidir.

Nerede bulabilirsiniz: API Anahtarı, Ayarlar → Entegrasyonlar altında, Web kancaları’ndan ayrı, kendine ait bir bölümdür. Bir kılavuz veya iş arkadaşınız anahtarı “Web kancaları” altında aramanızı söylerse, bunun yerine bir sonraki bölüme bakın.

Kapsamlı anahtarlar: tek bir iş için ekstra anahtarlar #

Ana anahtarınız her şeyi yapabilir, bu yüzden bir rapora, müşteri paneline veya ayrı bir korumalı alan (sandbox) ve geliştirme kurulumuna verilecek anahtar bu değildir. Bunun için, Anahtarınız bölümünün altındaki API Anahtarı kısmında yer alan Kapsamlı anahtarlar kartında kapsamlı anahtarlar oluşturun:

1. Yeni anahtar’a tıklayın.
2. Daha sonra tanıyabileceğiniz bir Ad verin; örneğin “Sandbox” veya “Acme müşteri paneli”.
3. Neleri görebilir altında, yalnızca ihtiyaç duyduğu alanları işaretleyin.
4. Neler yapabilir altında, araç değişiklik yapmadığı sürece Salt okunur seçeneğini işaretli bırakın. Değişiklik yapabilen bir anahtar, mesaj gönderebilir ve kurulumunuzu düzenleyebilir.
5. İsteğe bağlı olarak Dakikadaki istek sayısı (diğer entegrasyonlarınızı asla yavaşlatmaması için kendi sınırı) ve bir Son kullanma tarihi belirleyin.
6. Anahtar oluştur’a tıklayın ve hemen kopyalayın. Kapsamlı anahtarlar yalnızca bir kez gösterilir; birini kaybederseniz, iptal edin ve başka bir tane oluşturun.

İhtiyacınız olduğu kadar çok oluşturabilirsiniz. Listedeki her anahtar en son ne zaman kullanıldığını gösterir ve Anahtarı iptal et seçeneği çalışmasını anında durdurur. Kapsamlı bir anahtar oluşturmak veya iptal etmek ana anahtarınıza asla dokunmaz. Belirli alt hesaplarla sınırlı anahtarlar da dahil olmak üzere tüm seçenekler, API referansının API anahtarları sayfasında yer almaktadır.

Temel URL #

Tüm API istekleri aşağıdaki temel web adresini kullanır:

https://api.youraiconnector.com/v1/

Kimlik Doğrulama #

Platformun siz olduğunuzu anlaması için her istek API anahtarınızı içermelidir. En basit yol, onu web adresinin sonuna eklemektir:

https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY

Anahtarı URL içinde göndermek yerine bir istek başlığı (request header) olarak da gönderebilirsiniz (anahtarın sunucu günlüklerine düşmemesi için üretim ortamında bu yöntem önerilir):

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Tüm istekler güvenli bir bağlantı (HTTPS) kullanmalıdır. Güvensiz (HTTP) istekler reddedilir.

Geliştirici kılavuzlarının tamamını mı arıyorsunuz? Bu sayfa, en yaygın işlemleri kapsayan hızlı bir giriştir. cURL, JavaScript ve Python örnekleriyle her kaynağı içeren eksiksiz, adım adım kılavuzlar için API ile Başlarken ve API Referansı bölümlerine bakın.

Yaygın API İşlemleri #

Bir Kişi Oluşturun #

İstek:

POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}

Gerekli alanlar: Bir kişi oluşturmak için her zaman bir phoneNumber (ülke koduyla birlikte) gereklidir. Sadece e-posta adresi yeterli değildir; geçerli bir telefon numarası içermeyen istekler reddedilir. E-posta isteğe bağlıdır.

Yanıt:

{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}

data.contactId değerini kaydedin; “Bir Listeye Kişi Ekle” çağrısı için buna ihtiyacınız olacak.

Bir Listeye Kişi Ekle #

POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}

Bir listenin kimliğini uygulamada Kişiler → Listeler altında, listenin satır menüsünden (Liste kimliğini kopyala) bulabilirsiniz.

Bir Kişiyi Güncelle #

PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}

Yalnızca dahil ettiğiniz alanlar değiştirilir. Bu aynı zamanda bir içe aktarma işleminden sonra özel alan değerlerini toplu olarak yüklemenin yoludur — Özel Alanlar, Müşteri Adayı Profili ve Notlar bölümüne bakın. Tüm ayrıntılar Kişiler API’si içindedir.

Mesaj Gönder (Özel Kanal) #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}

Gelen Mesajları Al (Özel Kanal) #

Harici sistemlerden gelen mesajları özel bir kanal olarak kabul edin. GoHighLevel gibi entegrasyonlar, mesajları Your AI Connector içine bu şekilde gönderir. Tüm ayrıntılar için Özel Kanallar bölümüne bakın.

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}

Mevcut İşlemlere Genel Bakış #

Hız Sınırlaması #

API, platform kararlılığını sağlamak için hız sınırları uygular. Sınırınızı aşmanız durumunda 429 Too Many Requests döner — işlemi durdurun ve yanıt başlıklarında belirtilen süreden sonra tekrar deneyin. Yüksek hacimli kullanım durumları (toplu içe aktarmalar) için yerleşik içe aktarma özelliğini kullanın veya rehberlik için hi@youraiconnector.com adresine e-posta gönderin.

En İyi Uygulamalar #

• API anahtarınızı güvenli bir şekilde saklayın — bir parola yöneticisi veya sunucu tarafı yapılandırması kullanın, asla bir tarayıcı ziyaretçisinin okuyabileceği istemci tarafı kodlarında tutmayın.
• Telefon numaralarına her zaman ülke kodunu ekleyin (ABD için +1, Birleşik Krallık için +44, Hollanda için +31).
• Hataları düzgün bir şekilde yönetin — durum kodlarını kontrol edin ve döndürülen tüm hata mesajlarını okuyun.
• Yinelenenleri yönetin — yinelenen bir telefon numarası, yeni bir kişi yerine { "success": false, "error_code": 409 } döndürür ve mevcut kişinin kimliği contactId içinde yer alır.
• Toplu işlemleri çalıştırmadan önce küçük bir veri kümesiyle test edin.

Hata Yanıtları #

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}

Sonraki Adımlar #

• Web kancaları — uygulamadan gerçek zamanlı bildirimler alın (API anahtarınızdan ayrı bir bölüm).
• Yapay Zeka Asistanlarını Bağlayın (MCP) — Claude’un hesabınızı yönetmesini sağlamak için aynı API anahtarını kullanın.
• Facebook Müşteri Adayı Formları — müşteri adaylarını yakalamak için otomasyon platformlarıyla API’yi kullanın.
• GoHighLevel Entegrasyonu — tam bir çift yönlü API entegrasyon örneği.