Özel Kanallar #

Özel kanalları kullanarak herhangi bir mesajlaşma platformunu veya iletişim aracını platforma bağlayın. Bu, web sitesi canlı sohbet araçları, e-posta sistemleri, CRM’ler veya diğer herhangi bir hizmet gibi platformlardan gelen mesajları gelen kutunuza getirmenize ve bunlara AI Temsilcinizle yanıt vermenize olanak tanır.

Özel Kanallar Nedir? #

Özel kanallar, platformu yerleşik mesajlaşma platformlarının (WhatsApp, SMS, Instagram, Messenger) ötesine taşır. Özel kanallar ile şunları yapabilirsiniz:

• Mesajları alın: Herhangi bir harici platformdan gelen mesajları platformun birleşik gelen kutusuna aktarın.
• Yanıt gönderin: Uygulamadan harici platformunuza otomatik olarak yanıt gönderin.
• AI Temsilcisi kullanın: Herhangi bir kaynaktan gelen mesajları yanıtlamak için bir AI Temsilcisi kullanın.
• Tüm konuşmaları takip edin: Diğer kanallarınızla birlikte tek bir gelen kutusunda tüm konuşmaları izleyin.

Bu, özel iletişim araçları kullanan, özel olarak oluşturulmuş bir platforma sahip olan veya tüm müşteri mesajlarını tek bir yerde toplamak isteyen işletmeler için idealdir.

Nasıl Çalışır #

Özel kanallar, harici platformunuz ile platform arasında web kancaları (internet üzerinden sistemler arasında gönderilen otomatik mesajlar) kullanarak mesaj alışverişi yaparak çalışır. İş akışı şu şekildedir:

Your Platform  ──(sends message to)──>  The App
                                           |
                                       AI Agent responds
                                       Contact saved
                                       Message stored
                                           |
The App  ──(sends reply to)──>  Your Platform

1. Gelen mesajlar: Harici platformunuz, bir web adresine (URL) mesaj gönderir. Bunu, platformunuzun platformun posta kutusuna bir mesaj “göndermesi” olarak düşünebilirsiniz.
2. İşleme: Platform, kişiyi oluşturur veya günceller, mesajı saklar ve (etkinse) bir AI Temsilcisinin yanıt oluşturmasını sağlar.
3. Giden mesajlar: Platform bir yanıt gönderdiğinde (AI tarafından veya sizin tarafınızdan yazılmış olsun), mesajı platformunuzdaki bir URL’ye gönderir ve sisteminiz bunu son kullanıcıya iletebilir.

Gelen Mesajları Ayarlama (Platformunuzdan Uygulamaya) #

Harici platformunuzdan uygulamaya mesaj göndermek için, platformunuzun aşağıdaki URL’ye veri göndermesi gerekir. Geliştiriciniz bunu standart bir POST isteği (bir sistemin internet üzerinden diğerine veri göndermesinin yaygın bir yolu) olarak tanıyacaktır.

Mesajlar Nereye Gönderilmeli #

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

YOUR_API_KEY kısmını API anahtarınızla (platformun, platformunuzun mesaj göndermesine izin verildiğini kanıtlayan özel bir kod) değiştirin. Bunu Ayarlar → Entegrasyonlar → API Anahtarı altında bulabilir veya oluşturabilirsiniz.

Mesaj Formatı #

Mesaj verisini aşağıdaki formatta (JSON) gönderin:

{
  "customData": {
    "messageSid": "unique-message-id-123",
    "fromId": "user-456",
    "toId": "your-business-id",
    "body": "Hello, I have a question about your service.",
    "status": "received",
    "channel": "my-live-chat",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "mediaUrl": null,
    "mediaContentType": null
  },
  "messageType": "text"
}

Her bir parçanın anlamı:

• messageSid - Bu özel mesaj için benzersiz bir kimlik (sisteminiz tarafından oluşturulur). Aynı mesajın iki kez işlenmesini önlemek için kullanılır.
• fromId - Mesajı kimin gönderdiği (sisteminizdeki bir kullanıcı kimliği, e-posta veya telefon numarası olabilir).
• toId - İşletme tanımlayıcınız (seçeceğiniz herhangi bir etiket olabilir).
• body - Mesajın gerçek metni.
• channel - Mesajın nereden geldiğini tanımlamak için seçtiğiniz bir etiket (örneğin, “website-chat”, “email”).

Tam Alan Referansı #

Emoji Tepkileri #

Platformunuz emoji tepkilerini destekliyorsa (örneğin bir mesaja başparmak yukarı işareti), bunları metin mesajı olarak değil, bir tepki olarak gönderin: messageType değerini "reaction" olarak ayarlayın ve customData.body içine yalnızca emojiyi koyun.

{
  "messageType": "reaction",
  "customData": {
    "messageSid": "reaction-123",
    "fromId": "user-42",
    "toId": "my-business",
    "body": "👍"
  }
}

Asistan bunu beklediğiniz şekilde işler:

• Asistanın sorduğu bir soruya verilen tepki (örneğin “Perşembe günü uygun mu?”) cevap olarak kabul edilir ve asistan yanıt verir.
• Kapanış mesajına verilen bir tepki (örneğin “Yakında görüşürüz!”) konuşmayı sessizce sonlandırır. Yanıt gönderilmez.

Platformunuz tepkileri “Şununla tepki verildi: 👍” gibi metinlere dönüştürüyorsa, asistan bunu normal bir metin mesajı olarak görür ve yanıt verip vermeyeceğine kendisi karar verir. Tepki türünü göndermek bu durumu önler.

Ne Alırsınız #

Başarılı bir istek şunları döndürür:

{
  "success": true,
  "messageId": "1234567890"
}

Bir şeyler ters giderse, sorunu açıklayan bir hata mesajı alırsınız:

{
  "error": "Message body cannot be empty"
}

Durum Kodları #

Eğer customData.status ayarını yaparsanız, kabul edilen tek değer "received"'dir — başka bir şey göndermek yerine varsayılanı kullanmak için bu alanı tamamen boş bırakın, aksi takdirde 400 hatası alırsınız.

Medya Ekleri Gönderme (Resimler, Videolar, Dosyalar) #

Mesajlarınıza dosya ekleri (resimler, videolar, sesler, belgeler) dahil edebilirsiniz. Bunu yapmanın iki yolu vardır:

Seçenek 1: Dosyaya Bağlantı Verme #

Dosya zaten çevrimiçi barındırılıyorsa, platformun onu indirebileceği URL’yi (web adresini) sağlayın:

{
  "customData": {
    "messageSid": "msg-789",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Here is a photo of the issue.",
    "channel": "support-portal",
    "mediaUrl": "https://example.com/uploads/photo.jpg",
    "mediaContentType": "image/jpeg"
  },
  "messageType": "text"
}

Seçenek 2: Dosyayı Doğrudan Gömme (Base64) #

Dosya çevrimiçi barındırılmıyorsa, onu doğrudan mesajın içine kodlanmış metin (base64 formatı) olarak gömebilirsiniz. Bu, sisteminizin dosyaları anlık olarak oluşturduğu teknik entegrasyonlarda yaygındır. Platform, dosyayı otomatik olarak çözecek ve saklayacaktır:

{
  "customData": {
    "messageSid": "msg-790",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Screenshot attached.",
    "channel": "support-portal",
    "mediaUrl": "data:image/png;base64,iVBORw0KGgo...",
    "mediaContentType": "image/png"
  },
  "messageType": "text"
}

Giden Mesajları Ayarlama (Platformdan Sizin Platformunuza) #

Platform özel bir kanalda bir yanıt gönderdiğinde (AI tarafından veya sizin tarafınızdan yazılmış olsun), bu yanıtı otomatik olarak platformunuzdaki bir URL’ye gönderir, böylece sisteminiz bunu son kullanıcıya iletebilir.

Önce webhook URL’sini ayarlayın. Yanıtların iletilebilmesi için özel kanal webhook URL’sini kaydetmeniz gerekir. Hiçbir URL kaydedilmezse, yanıtlar yine de oluşturulur ve saklanır ancak asla gönderilmezler ve “Başarısız” durumu göstermezler, bu nedenle gelen kutunuzda sorunu işaretleyen hiçbir şey olmaz. Yayına girmeden önce her zaman webhook URL’sini yapılandırın.

Uygulamaya Yanıtların Nereye Gönderileceğini Söyleyin #

1. Sol kenar çubuğunda, en alttaki Ayarlar’a tıklayın.
2. Ayarlar sol panelinde, Kanallar altında Kanallar’a tıklayın.
3. Sayfanın en altında bulunan Özel kanal kartını bulun (Android SMS Ağ Geçidi, iMessage, web sitesi sohbet aracı, Twilio Hesabı ve Mevzuat uyumluluğunun ötesinde).
4. Webhook URL’sini girin — AI’nın giden mesajları göndermesi gereken platformunuzdaki URL (geliştiriciniz bunu yanıtları almak ve işlemek için ayarlar). Bu, herkese açık bir HTTPS URL olmalıdır — http:// adresleri ve herkese açık olmayan ana bilgisayarlar reddedilir.
5. Kaydet’e tıklayın.

Platform Sizin Platformunuza Ne Gönderir #

Platform bir yanıt gönderdiğinde, platformunuz aşağıdaki verileri alır:

{
  "contactId": "abc123",
  "messageId": "msg-456",
  "userId": "your-user-id",
  "body": "Thank you for your message! Here is the information you requested...",
  "toId": "user-456",
  "channel": "my-live-chat"
}

Her Alan Ne Anlama Gelir #

Platformunuz bu verileri alır ve yanıtı kendi sisteminiz aracılığıyla son kullanıcıya iletmek için kullanır.

Platform Teslimatı Nasıl İzler #

Yanıtı platformunuza gönderdikten sonra, platform mesaj durumunu günceller:

• Gönderildi - Platformunuz mesajı başarıyla aldı.
• Başarısız - Platformunuz bir hata döndürdü veya ulaşılamadı. Platform, sorun giderebilmeniz için hata ayrıntılarını mesajla birlikte saklar.

Sisteminizden Uygulamaya Mesaj Gönderme #

Mesaj almanın yanı sıra, kendi sisteminizden doğrudan özel bir kanal aracılığıyla giden mesajlar da gönderebilirsiniz. Bu, bir konuşma başlatmak veya proaktif bir mesaj göndermek istediğinizde kullanışlıdır.

Plan gereksinimi. API aracılığıyla mesaj göndermek ve senkronize etmek, API erişimi ve en az bir mesajlaşma kanalı içeren bir plan gerektirir. Eğer 403 “permission denied / feature not enabled” (izin reddedildi / özellik etkinleştirilmedi) hatası alırsanız, mevcut planınız bunu içermiyordur; planınızı yükseltin veya destek ekibiyle iletişime geçin.

Nereye Gönderilir #

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

Mesaj Formatı #

{
  "customData": {
    "fromId": "user-456",
    "customChannel": "my-live-chat",
    "body": "Hello! How can I help you today?",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com"
  }
}

Gerekli Alanlar #

İsteğe bağlı alanlar (campaignId, firstName, lastName, email) gelen mesajlardakiyle aynı şekilde çalışır; platformun kişi kaydını oluşturmasına veya güncellemesine yardımcı olurlar.

Ne Alırsınız #

{
  "success": true,
  "messageId": "generated-message-id",
  "contactId": "contact-id",
  "message": "Message sent successfully"
}

Başka Bir Sistemden Gönderilen Mesajları Kaydetme #

Bazen bir kişiye zaten farklı bir araçtan (örneğin, başka bir platformdaki bir iş akışı) bir mesaj göndermiş olabilirsiniz ve AI’nın tam bağlama sahip olması için platformun bunu bilmesini isteyebilirsiniz. Bu, göndermekten farklıdır: platform mesajı kaydeder ancak kişiye yeniden iletmez.

Nereye Gönderilir #

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

customData.fromId (kişinin platformunuzdaki kimliği) ve customData.body (zaten gönderilmiş olan mesaj metni) bilgilerini ekleyin.

Nasıl Davranır #

• Mesaj kaydedilir, yeniden gönderilmez. Platform bunu yalnızca bağlam için konuşmada saklar.
• AI, varsayılan olarak o kişide duraklatılır. Bu, botun bir insanın zaten ilgilendiği bir mesajın üzerine yanıt vermesini önler. Botu aktif tutmak için customData.pauseAi: false değerini iletin.
• Yeni kişiler otomatik olarak oluşturulabilir. customData.customChannel değerini dahil edin; kişi henüz mevcut değilse oluşturulacaktır.
• Yinelenenler yoksayılır. Aynı messageSid değerini tekrar kullanırsanız, platform mesajın zaten kaydedildiğini tanır ve hiçbir değişiklik yapmaz.

Plan gereksinimi. Mesaj göndermek gibi, API üzerinden mesaj kaydetmek de API erişimini ve en az bir mesajlaşma kanalını içeren bir plan gerektirir. 403 “permission denied / feature not enabled” (izin reddedildi / özellik etkinleştirilmedi) hatası, mevcut planınızın bunu içermediği anlamına gelir.

Gerçek Dünya Örnekleri #

Web Sitesi Canlı Sohbeti #

Web sitenizdeki bir canlı sohbet aracını platforma bağlayın, böylece AI Temsilciniz ziyaretçi sorularını yanıtlayabilir:

1. Bir ziyaretçi web sitenizin sohbet penceresine bir mesaj yazar.
2. Sohbet pencereniz mesajı platforma gönderir.
3. Yapay Zeka Temsilcisi bir yanıt oluşturur.
4. Yanıt, ziyaretçiye göstermek üzere sohbet pencerenize geri gönderilir.

Neden faydalıdır: Web sitesi ziyaretçileriniz, sizin çevrimiçi olmanıza gerek kalmadan sorularına anında, yapay zeka destekli yanıtlar alırlar.

E-posta #

E-posta görüşmelerini platform üzerinden yönlendirin, böylece Yapay Zeka Temsilciniz e-postalara yanıt verebilir:

1. Gelen e-postaları platforma ileten bir sistem kurun (e-posta göndericisinin adresini fromId, e-posta konusunu ve içeriğini body ve "email" değerini channel olarak kullanarak).
2. Yapay Zeka Temsilcisi e-postayı okur ve bir yanıt oluşturur.
3. Yanıt, e-posta sisteminize geri gönderilir ve normal bir e-posta yanıtı olarak iletilir.

Neden faydalıdır: Yaygın e-posta soruları (fiyatlandırma, çalışma saatleri, uygunluk durumu) Yapay Zeka Temsilciniz tarafından anında yanıtlanır.

E-posta sisteminiz IMAP/SMTP veya OAuth destekliyorsa, yerleşik E-posta kanalı özel bir entegrasyondan daha basit olabilir.

CRM Entegrasyonu #

Mevcut CRM (müşteri ilişkileri yönetimi) sisteminizi platforma bağlayın:

1. Bir potansiyel müşteri CRM’iniz üzerinden mesaj gönderdiğinde, bunu platforma iletin.
2. Yapay Zeka Temsilcisi yanıt verir ve görüşmeyi takip eder.
3. Yapay Zeka yanıtı, iletilmek üzere CRM’inize geri gönderilir.
4. Tüm görüşme geçmişi hem platformda hem de CRM’inizde mevcuttur.

Neden faydalıdır: Satış ekibiniz, CRM’lerinden ayrılmadan potansiyel müşterilere yapay zeka destekli yanıtlar verebilir.

Destek Talebi Sistemi #

Platformu müşteri desteği için yapay zeka destekli bir ilk müdahale ekibi olarak kullanın:

1. Destek bilet sisteminiz yeni destek taleplerini platforma iletir.
2. Yapay Zeka Temsilcisi ilk yanıtı gönderir (örneğin, talebi aldığını onaylar ve açıklayıcı sorular sorar).
3. Yanıt, destek sisteminizdeki ilgili bilete eklenir.
4. Destek ekibiniz, Yapay Zeka’nın ne söylediğini inceleyebilir ve gerektiğinde kontrolü devralabilir.

Neden faydalıdır: Müşteriler, mesai saatleri dışında bile anında onay ve ilk yardımı alırlar.

Sorun Giderme #

Platform Tarafından Alınmayan Mesajlar #

• API anahtarınızın doğru ve etkin olduğunu doğrulayın (Ayarlar → Entegrasyonlar → API Anahtarı bölümünü kontrol edin).
• GET değil, POST isteği gönderdiğinizden emin olun. Yazılımcınız aradaki farkı bilecektir.
• customData.body alanının boş veya sadece boşluk karakterlerinden oluşmadığını kontrol edin.
• customData.fromId alanının dahil edildiğini doğrulayın.
• Belirli hata ayrıntıları için yanıt mesajını okuyun.

Platformunuza Ulaşmayan Yanıtlar #

• Platformunuzun URL’sini Kanallar sayfasındaki Özel kanal kartına girdiğinizden emin olun. Hiçbir URL kaydedilmezse, yanıtlar oluşturulur ve saklanır ancak asla gönderilmez; ayrıca bunlar “Başarısız” olarak işaretlenmeyecektir, bu yüzden önce bunu kontrol edin.
• URL’nin herkese açık erişilebilir olduğunu (bir giriş ekranı veya güvenlik duvarı arkasında olmadığını) ve başarılı bir yanıt döndürdüğünü doğrulayın.
• URL’nize yalnızca yanıtlar (giden mesajlar) gönderilir; gelen mesajlar bunu tetiklemez.
• Gelen kutunuzdaki mesajda hata ayrıntılarını kontrol edin.

Oluşturulmayan Kişiler #

• fromId değerinin, aynı kullanıcı için tüm mesajlarında tutarlı olduğundan emin olun. Platform, kişileri tanımlamak için bu değeri kullanır; mesajlar arasında değişirse, platform her seferinde yeni bir kişi oluşturur.
• Eksiksiz bir kişi kaydı oluşturmak için yeni bir kişiden gelen ilk mesaja firstName, lastName ve email değerlerini ekleyin.

Çalışmayan Medya Ekleri #

• Dosya bağlantıları (URL’ler) için dosyanın herkese açık olarak erişilebilir olduğundan emin olun (erişmek için oturum açma gerekmemelidir).
• mediaUrl dahil ettiğinizde her zaman mediaContentType bilgisini de ekleyin.
• Gömülü dosyalar (base64) için formatın data:MIME_TYPE;base64,ENCODED_DATA olduğunu doğrulayın.
• Belirttiğiniz dosya türünün gerçek dosya içeriğiyle eşleştiğinden emin olun.

En İyi Uygulamalar #

• Tutarlı fromId değerleri kullanın. Platformunuzdaki her kullanıcının her zaman aynı fromId değerine sahip olması gerekir. Bu, platformun tüm mesajlarını mükerrer kişiler oluşturmak yerine tek bir görüşmede gruplandırmasını sağlar.
• Net bir channel adı seçin. Gelen kutunuzu görüntülerken mesajların nereden geldiğini kolayca anlayabilmek için "website-chat", "email" veya "zendesk" gibi açıklayıcı bir isim seçin.
• İletişim bilgilerini (firstName, lastName, email) yeni bir kişiden gelen ilk mesaja dahil edin. Bu, hemen eksiksiz ve kullanışlı bir kişi kaydı oluşturur.
• Yeniden deneme mantığı oluşturun. Platformunuz ilk denemede yanıt vermezse, platformunuzun mesaj göndermeyi tekrar denemesini sağlayın (ağ kesintileri olabilir).
• Her mesaj için benzersiz messageSid değerleri kullanın. Bu, sisteminiz aynı mesajı birden fazla kez gönderirse, aynı mesajın iki kez işlenmesini önler.
• Birden fazla kullanım durumunuz olduğunda (örneğin, satış soruları ile destek soruları gibi) mesajları farklı Yapay Zeka Temsilcilerine yönlendirmek için campaignId kullanın.
• Canlıya geçmeden önce test edin. Gerçek kullanıcılara sunmadan önce her iki yönde de test mesajları gönderin ve kişilerin, görüşmelerin ve Yapay Zeka yanıtlarının doğru çalıştığını doğrulayın.