QSoft.CxPerium .NET SDK ile özel WhatsApp chatbot'ları geliştirin — kurulum ve diyaloglardan NLP, mesajlaşma, WhatsApp Flows ve platform modüllerine kadar.
CxPerium tabanlı bir chatbot'u sıfırdan kurun: hesabınızı oluşturun, örnek projeyi indirin, bir ters proxy arkasında çalıştırın ve platforma bağlayın.
app.cxperium.com adresini ziyaret edin. Ad soyad, e-posta adresi ve şifrenizle kaydolun, ardından etkinleştirme e-postasını doğrulayın — zaten bir hesabınız varsa Sign In (Oturum Aç) seçeneğini kullanın.
CxPerium.BotTemplate deposuna gidin ve proje açıklamasını inceleyin. Code (Kod) düğmesine tıklayın, ardından ZIP olarak indirin veya HTTPS ile klonlayın.
CxPerium özel NuGet paketi QSoft.CxPerium'u projeye ekleyin.
Proje varsayılan olarak http://localhost:3978/ adresinde çalışır. Bağlantı noktasını değiştirmeniz gerekiyorsa launchSettings.json dosyasını düzenleyin.
WhatsApp mesajlarını yerel makinenize yönlendirmek için bir ters proxy (ngrok) gereklidir. Oluşturulan genel URL'yi not edin (örn. https://xxxxx.ngrok.io/).
appsettings.json dosyasını bulun ve BotUrl ile HookUrl alanlarını güncelleyin. Ardından CxPerium'da Settings > API Integration (Ayarlar > API Entegrasyonu) bölümüne gidin, Regenerate (Yeniden Oluştur) düğmesine tıklayarak bir API anahtarı oluşturun ve dosyaya ekleyin.
WhatsApp sandbox numarası +90 850 309 45 52'ye "Hello" gönderin — bot "Hello World" yanıtını verir. https://web.whatsapp.com/send/?phone=908503094552&text=hi doğrudan bağlantısını da kullanabilirsiniz. CxPerium tabanlı chatbot'unuz artık başarıyla çalışıyor.
# Örnek projeyi klonlayın
git clone https://github.com/cxperium/CxPerium.BotTemplate.git
# WhatsApp mesajlarını yerel makinenize yönlendirin
ngrok http 3978 --host-header="localhost:3978"{
"BotUrl": "https://xxxxx.ngrok.io",
"HookUrl": "https://hook.example.com",
"ApiKey": "your_generated_api_key_here"
}Asistan örnek projesi net bir yapıyla gelir: bir Channels dizini, bir Dialogs dizini, appsettings.json yapılandırma dosyası ve Program.cs giriş noktası.
CxPerium.BotTemplate/
├── Channels/
│ ├── CxPerium.cs
│ └── Whatsapp.cs
├── Dialogs/
│ └── MainDialog.cs
├── appsettings.json
└── Program.csCxPerium.cs sınıfı, CxPerium platformundan gelen olayları yakalar:
Whatsapp.cs sınıfı, gelen mesajları ve olayları işler:
Bu dosya gerekmedikçe değiştirilmemelidir; özel gereksinimler için metotları geçersiz kılınabilir (override).
Dialogs klasörü MainDialog.cs dosyasını içerir. Daha iyi kod organizasyonu ve ölçeklenebilirlik için tüm diyaloglarınızı burada oluşturun.
appsettings.json dosyası, CxPerium'dan alınan API anahtarlarını ve webhook bilgilerini saklar.
Diyaloglar, kullanıcı ile bot arasındaki etkileşimlerin akışını yönetir ve kullanıcı deneyiminin temelini oluşturur. Bu bölüm, QSoft.CxPerium .NET SDK kullanarak bir chatbot için diyalog oluşturma adımlarını ayrıntılarıyla anlatır.
Diyalog, bir chatbot'un kullanıcı sorgularına nasıl yanıt vereceğini veya bir iş akışını nasıl yürüteceğini tanımlayan mantıksal bir yapıdır. QSoft.CxPerium SDK'sında diyaloglar, istenen sonuçlara ulaşmak için tanımlı bir mantık çerçevesi içinde programlanır.
Kullanıcı "who are you" mesajını gönderdiğinde botun "I am a special assistant" yanıtını verdiği bir diyalog oluşturacağız. Projenizde Dialogs adında bir klasör oluşturun ve WhoAreYouDialog adında yeni bir C# sınıf dosyası ekleyin. Sınıf, BaseWhatsAppDialog sınıfından türemeli, IWhatsAppDialog arayüzünü uygulamalı ve arayüzün gerektirdiği RunDialog metodunu içermelidir.
using QSoft.CxPerium.Dialogs.WhatsApp;
namespace QSoft.CxPerium.Assistant.Dialogs
{
public class WhoAreYouDialog : BaseWhatsAppDialog, IWhatsAppDialog
{
public void RunDialog()
{
this.Messages.SendMessage("I am a special assistant");
}
}
}Platformu açın ve Assistant > Dialog sayfasına gidin.
New Dialog (Yeni Diyalog) düğmesine tıklayın.
Dialog Name: tam ad alanı (örn. QSoft.CxPerium.Assistant.Dialogs.WhoAreYouDialog). Report Name: raporlama için açıklayıcı bir ad. Language: tanıma dili. Regex Value: tetikleyici kalıp ("who are you").
Diyaloğu kaydetmek için Save (Kaydet) düğmesine tıklayın.
WhoAreYouDialog adında bir sınıf oluşturun.BaseWhatsAppDialog sınıfını genişletin.IWhatsAppDialog arayüzünü uygulayın.RunDialog metodunun içinde.Messages.SendMessage kullanarak.CxPerium, kullanıcı mesajlarını anlamak ve uygun diyaloglara yönlendirmek için üç farklı yaklaşım kullanır.
Regex ifadelerine uyan mesajlar ilgili diyaloglara yönlendirilir ve önceden tanımlanmış kurallara göre ilerler. En sık gönderilen kullanıcı mesajlarıyla eşleşen Regex kuralları tanımlamanız önerilir.
Bir mesajın Regex eşleşmesi yoksa sistem, Assistant > Configuration ekranındaki DialogFlowConfig ayarlarını denetler. IsEnabled: true yapılandırıldığında mesaj Google Dialogflow'a iletilir; Dialogflow mesajın anlamını analiz ederek bir yanıt üretir veya önerilen bir eylem döndürür. Bu entegrasyon, Dialogflow API anahtarlarını ve proje bilgilerini gerektirir.
Regex eşleştirmesi başarısız olur ve Dialogflow uygun bir yanıt veremezse CxPerium, ChatGPTConfig ayarlarına başvurur. IsEnabled: true olduğunda mesaj ChatGPT'ye yönlendirilir; ChatGPT mesajı yapay zekâ destekli bir doğal dil işleme modeliyle doğrudan analiz eder. Bu entegrasyon API anahtarları, model seçimi ve parametre tanımları gerektirir.
Bu kademeli yapı, mesajların birden çok denetim mekanizmasından geçmesini ve en uygun yöntemle işlenmesini sağlar.
Eşleşmeyen mesajların anlamsal olarak analiz edilip doğru diyaloglara yönlendirilmesi için Google Dialogflow'u asistanınıza bağlayın.
Dialogflow Console'a erişin ve bir agent oluşturun (örneğin Türkçe "DemoAgent"). Agent ayarlarını açın ve Project ID bağlantısı üzerinden Google Cloud proje ayarlarına gidin.
Google Cloud'da Service Accounts (Servis Hesapları) menüsünü açın, Owner (Sahip) rolüne sahip yeni bir servis hesabı oluşturun ve bir JSON anahtar dosyası üretin. Dosyayı güvenli bir şekilde saklayın.
CxPerium'da Assistant > Configuration bölümüne gidin ve DialogFlowConfig alanını düzenleyin. JSON anahtar dosyasını proje kök dizinine yerleştirin ve derlemeler sırasında kopyalanacak şekilde yapılandırın.
Dialogflow'da metin yanıtı olan bir intent oluşturun, ardından ilişkili eğitim ifadesini WhatsApp üzerinden göndererek yapılandırmanın çalıştığını doğrulayın.
DialogFlowConfig alanı şunları gerektirir:
demoagent-xxxxx.json).project_id değeri.True olarak ayarlanır.Bir Dialogflow intent'ini bir diyalog sınıfıyla eşlemek için intent'e özel bir payload ekleyin:
{
"intent": "QSoft.CxPerium.Assistant.Dialogs.DialogFlowDemoDialog"
}using QSoft.CxPerium.Dialogs.WhatsApp;
namespace QSoft.CxPerium.Assistant.Dialogs
{
public class DialogFlowDemoDialog : BaseWhatsAppDialog, IWhatsAppDialog
{
public void RunDialog()
{
this.Messages.SendMessage("This dialog is mapped from DialogFlow");
}
}
}Dialogflow tarafından yakalanan parametreler diyalog içinde okunabilir:
public void RunDialog()
{
var country = this.Parameters["country"];
this.Messages.SendMessage($"Country parameter: {country}");
}Regex ve Dialogflow'un ele alamadığı mesajların bir OpenAI asistanı tarafından yanıtlanması için ChatGPT entegrasyonunu yapılandırın.
Tarayıcınızı açın ve https://platform.openai.com/ adresine gidin. Zaten bir OpenAI hesabınız varsa Log In (Giriş Yap) düğmesine tıklayın; aksi halde Sign Up (Kayıt Ol) ile yeni bir hesap oluşturun.
Giriş yaptıktan sonra Assistants (Asistanlar) menüsüne gidin, Create New Assistant (Yeni Asistan Oluştur) düğmesine tıklayın ve asistanı gereksinimlerinize göre yapılandırın.
Oluşturduğunuz asistanın ayrıntılar sayfasını açın ve Assistant ID değerini kopyalayın. Ardından API Keys (API Anahtarları) bölümüne gidin, Create New API Key (Yeni API Anahtarı Oluştur) düğmesine tıklayın ve oluşturulan anahtarı güvenli bir şekilde saklayın — CxPerium entegrasyonu sırasında kullanılacaktır.
CxPerium platformunda Assistant bölümüne gidin ve Configuration (Yapılandırma) ekranını açın. ChatGPTConfig ayarlarını yapılandırın: OpenAI platformundan aldığınız ApiKey ve AssistantId değerlerini girin ve IsEnabled alanını True olarak ayarlayın.
Bu adımları tamamladıktan sonra CxPerium ile ChatGPT entegrasyonunuz hazır olacaktır.
Yerelleştirme modülü, chatbot üzerinden gönderilen mesajların asistan tarafından farklı dillerde görüntülenmesini sağlayan ayarları içerir.
Yerelleştirme menüsüne Assistant > Localization yolu üzerinden erişilir. Bu menü, yerelleştirme anahtarlarını ve bunların farklı dillerdeki karşılıklarını tanımlamanıza olanak tanır. Projenizde Localization sınıfı bu anahtarların değerlerini getirir.
using QSoft.CxPerium.Dialogs.WhatsApp;
using QSoft.CxPerium.Models;
using QSoft.CxPerium.WhatsApp;
namespace QSoft.CxPerium.Assistant.Dialogs
{
public class MainDialog : WelcomeDialog
{
public override void RunDialog()
{
string message = this.Localization.GetLocalizationText("SessionTimeoutMessage");
}
}
}GetLocalizationTextByLanguage metodu, metni belirli bir dile çevirir:
string message = Localization.GetLocalizationTextByLanguage("SessionTimeoutMessage", LanguagesEnum.Turkish);NotImplementedException hatası oluşturur.WhatsApp iletişimi için CxPerium .NET SDK'nın mesajlaşma metotları. Tüm metotlara, BaseWhatsAppDialog sınıfından türeyen sınıflarda kullanılabilen Messages nesnesi üzerinden erişilir.
Metin tabanlı mesajlar gönderir; isteğe bağlı URL önizlemesi desteklenir.
this.Messages.SendMessage("Hello World");
this.Messages.SendMessage("Hello CXPerium https://www.cxperium.com", true);Etkileşimli düğmeler içeren bir mesaj iletir (en fazla üç düğmeye izin verilir).
public class DemoDialog : BaseWhatsAppDialog, IWhatsAppDialog
{
public void RunDialog()
{
List<Button> buttons = new List<Button>();
buttons.Add(new Button() { IsVisible = true, Reply = new Reply() { Title = "Yes Button", Id = "#yes_button" } });
buttons.Add(new Button() { IsVisible = true, Reply = new Reply() { Title = "No Button", Id = "#no_button" } });
this.Messages.SendButtonMessage("Hello World", "Header Text", "Footer Text", buttons);
}
}Görsel göndermek için üç varyant: yerel dosya, medya kimliği veya URL.
FileInfo file = new FileInfo("C:\\images\\example.jpg");
this.Messages.SendImageMessageByFile(file, "Here is an image");
string mediaId = "123456789";
this.Messages.SendImageMessageById(mediaId, "Here is an image");
Uri url = new Uri("https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png");
this.Messages.SendImageMessageByUrl(url, "Here is an image");Konum ayrıntılarıyla birlikte coğrafi koordinatları iletir.
this.Messages.SendLocationMessage(40.712776, -74.005974, "New York", "New York, NY, USA");Belge göndermek için üç varyant: dosya, medya kimliği veya URL.
FileInfo file = new FileInfo("C:\\documents\\example.pdf");
this.Messages.SendDocumentMessageByFile(file, "Here is a document", "example.pdf");
string mediaId = "987654321";
this.Messages.SendDocumentMessageById(mediaId, "Here is a document", "example.pdf");
Uri link = new Uri("https://example.com/documents/example.pdf");
this.Messages.SendDocumentMessageByUrl(link, "Here is a document", "example.pdf");Video göndermek için üç varyant: dosya, medya kimliği veya URL.
FileInfo file = new FileInfo("C:\\videos\\example.mp4");
this.Messages.SendVideoMessageByFile(file, "Here is a video");
string mediaId = "654321987";
this.Messages.SendVideoMessageById(mediaId, "Here is a video");
Uri url = new Uri("https://example.com/videos/example.mp4");
this.Messages.SendVideoMessageByUrl(url, "Here is a video");Satırlar ve/veya bölümler içeren etkileşimli liste mesajları iletir.
List<Row> rows = new List<Row>
{
new Row() { Id = "1", Title = "Option 1", Description = "Description for option 1" },
new Row() { Id = "2", Title = "Option 2", Description = "Description for option 2" }
};
this.Messages.SendListMessage("Choose an option", "Header Text", "Footer Text", "View Options", rows);
List<Section> sections = new List<Section>
{
new Section()
{
Title = "Section 1",
Rows = new List<Row>
{
new Row() { Id = "1", Title = "Option 1", Description = "Description for option 1" },
new Row() { Id = "2", Title = "Option 2", Description = "Description for option 2" }
}
}
};
this.Messages.SendListMessage("Choose an option", "Header Text", "Footer Text", "View Options", sections);Ek mesajlaşma metotları: konum istekleri, kişi kartları, çıkartmalar, emoji tepkileri ve katalog / ürün mesajları.
Koordinatlar ve adres bilgileriyle kullanıcıya belirli bir konumu paylaşır. Parametreler: lat (double), lon (double), name (string, örn. "Office") ve address (string).
SendLocationMessage(double lat, double lon, string name, string address);
SendLocationMessage(40.987654, 29.123456, "QSoft Office", "Istanbul, Turkey");WhatsApp üzerinden kullanıcının mevcut konumunu ister. Parametre, istek mesajı metnidir.
this.Messages.SendLocationRequest("Please share your location.");Telefon, ad, e-posta ve meslek bilgilerini içeren bir kişi kartı iletir.
SendContact(string phoneNumber, string name, string surname, string email,
string company, string department, string title);
SendContact("+905001112233", "Ahmet", "Yılmaz",
"ahmet.yilmaz@example.com", "QSoft", "Software", "Engineer");Kullanıcılara WebP biçiminde çıkartma dosyaları gönderir.
SendSticker(string stickerUrl);
SendSticker("https://example.com/sticker.webp");Bir mesaja emoji tepkisi ekler veya kaldırır. Tepki başına tek bir emojiye izin verilir; boş bir dize göndermek önceki emojiyi kaldırır. Android/iOS uyumlu emojiler ve işlenmiş emojiler desteklenir.
SendEmoji(string messageId, string emoji);
SendEmoji("1234567890", "😊");
SendEmoji("1234567890", "");Bağlı ürün kataloğunu WhatsApp'ta görüntüler. Parametreler: katalog mesajı içeriği ve alt bilgi metni.
SendCatalog(string message, string footer);
SendCatalog("Discover our products!", "Contact us for more information.");Meta kataloğundan tek bir ürünün ayrıntılarını iletir. Parametre, ürünün benzersiz Meta katalog tanımlayıcısıdır. Ürün ayrıntılarının gönderilebilmesi için ürünün önce Meta kataloğuna eklenmesi gerekir.
this.Messages.SendProductMessage("1");Birden çok ürün listesini tek bir düzenli mesajda gönderir.
SendMultipleProductMessage(string bodyText, string footerText,
string headerText, List<MultiProductSection> products);
var products = new List<MultiProductSection>
{
new MultiProductSection
{
Title = "Group 1",
Items = new List<MultiProductItem>
{
new MultiProductItem { ProductRetailerId = "12345" },
new MultiProductItem { ProductRetailerId = "67890" }
}
}
};
this.Messages.SendMultipleProductMessage("Body text", "Footer text",
"Header text", products);Özel WhatsApp chatbot'ları için CxPerium SDK'da WhatsApp Flows nasıl kullanılır.
WhatsApp Flows, yapılandırılmış etkileşimler sağlayan bir işletme mesajlaşma özelliğidir. Geleneksel sohbet yerine, WhatsApp'tan ayrılmadan form benzeri bir arayüz sunar — kusursuz bir kullanıcı deneyimi, düzenli veri toplama ve verimli bilgi edinme sağlar.
this.Messages.SendFlowMessage metodu WhatsApp Flows mesajları gönderir ve birden çok aşırı yüklemeye (overload) sahiptir:
// Kullanım 1
SendFlowMessage(string message, string headerText, string footerText,
string buttonText, Type catchedDialog, string flowIdOrName, string screen)
// Kullanım 2
SendFlowMessage(string message, Uri url, string footerText,
string buttonText, Type catchedDialog, string flowIdOrName, string screen)
// Kullanım 3
SendFlowMessage(string message, Uri url, string footerText,
string buttonText, Type catchedDialog, string flowIdOrName, string screen, JObject data)
// Kullanım 4
SendFlowMessage(string message, string headerText, string footerText,
string buttonText, Type catchedDialog, string flowId, string screen, JObject data)Form verisini yakalayacak diyalog BaseWhatsAppDialog sınıfından türemeli ve IFlowReceiveMessage arayüzünü uygulamalıdır:
using Newtonsoft.Json.Linq;
using QSoft.CxPerium.Dialogs.WhatsApp;
namespace QSoft.CxPerium.Assistant.Dialogs
{
public class UserFormHandlerDialog : BaseWhatsAppDialog, IFlowReceiveMessage
{
public void ReceiveFlowMessage()
{
JObject formValue = this.Activity.Form.ResponseJson;
// Form verisini burada işleyin.
}
}
}Formu açan bir diyalog:
using QSoft.CxPerium.Dialogs.WhatsApp;
using System;
namespace QSoft.CxPerium.Assistant.Dialogs
{
public class MainDialog : WelcomeDialog
{
public override void RunDialog()
{
this.Messages.SendFlowMessage(
"Fill out the form below for your support request.",
"Form",
"Your request will be answered as soon as possible.",
"Open Form",
typeof(UserFormHandlerDialog),
"customer_support",
"DETAILS"
);
}
}
}Form verisini yakalayan bir diyalog:
using Newtonsoft.Json.Linq;
using QSoft.CxPerium.Dialogs.WhatsApp;
namespace QSoft.CxPerium.Assistant.Dialogs
{
public class UserFormHandlerDialog : BaseWhatsAppDialog, IFlowReceiveMessage
{
public void ReceiveFlowMessage()
{
JObject formValue = this.Activity.Form.ResponseJson;
Messages.SendMessage($"The order form entered is {formValue["screen_0_Order_number_1"]} types");
}
}
}Aşağıdaki bot URL'sini Flow endpoint'i olarak yapılandırın — ekran geçişlerini ve form dinamiklerini yönetir:
https://yourboturl/api/CxPerium/flowsdata_exchange eylemini işlemek için IFlowDataExchange arayüzünü uygulayın:
public class UserFormHandlerDialog : BaseWhatsAppDialog, IFlowDataExchange
{
public FlowResponse DataExchange(FlowRequest request)
{
var exchangeData = request.Data;
var response = new FlowResponse();
response.Screen = "another_screen";
response.Action = "navigate";
return response;
}
}Güvenli veri alışverişi için 2048 bit RSA anahtarı gereklidir — ayrıntılar için WhatsApp Business Encryption Guide'a bakın. Özel anahtar dosyasını projeye ekleyin:
Dosyayı private.pem olarak adlandırın.
Dosyanın Build Action (Derleme Eylemi) değerini Embedded resource (Gömülü kaynak) olarak ayarlayın.
Bu çerçeve sayesinde CxPerium, işletmelerin yapılandırılmış ve verimli müşteri etkileşimleri için WhatsApp Flows'tan yararlanmasını sağlar.
CxPerium modüllerine ve bunların C# kullanılarak WhatsApp chatbot'larına entegrasyonuna genel bir bakış. CxPerium, her biri müşteri etkileşimi için farklı işlevler sunan dört ana modül içerir: Canlı Sohbet, Anket, CRM ve Bilet.
Gerçek zamanlı müşteri desteği ve kullanıcı sorularına anında yanıt sağlar. Herhangi bir diyalogdan konuşmayı canlı sohbete aktarın:
using QSoft.CxPerium.Dialogs.WhatsApp;
using System;
namespace QSoft.CxPerium.Assistant.Dialogs
{
public class MainDialog : BaseWhatsAppDialog
{
public override void RunDialog()
{
this.LiveChat.TransferToLiveChat();
}
}
}Konuşmayı belirli bir ekibe aktarın:
string teamId = "TEAM_ID_HERE";
this.LiveChat.TransferToLiveChatByTeam(teamId);Canlı sohbet kapatıldığında tetiklenen webhook'u işleyin:
protected override void OnClosingLiveChat(Contact contact)
{
base.OnClosingLiveChat(contact);
}Kullanıcı deneyimini ölçmek ve memnuniyet ile ihtiyaçlara ilişkin müşteri geri bildirimlerini toplamak için tasarlanmıştır. Anket webhook'ları, yanıtlara ve tamamlanmalara tepki vermenizi sağlar:
protected override void OnSurveyQuestionAnswered(Contact contact,
ConversationState conversation, SurveyCx survey,
SurveyQuestionReplyCx answer)
{
base.OnSurveyQuestionAnswered(contact, conversation, survey, answer);
}
protected override void OnSurveyCompleted(Contact contact,
ConversationState conversation, SurveyCx survey)
{
base.OnSurveyCompleted(contact, conversation, survey);
}Asistan üzerinden anket gönderin:
this.Survey.SendSurvey("surveyid");Müşteri ilişkilerini yönetir ve müşteri etkileşim kayıtlarını saklar. Kullanıcılar bağlı WhatsApp numarasına GDPR onayıyla mesaj gönderdiğinde kayıtlar otomatik olarak oluşturulur. Herhangi bir diyalogdan kişi verilerine erişin:
var user = this.Contact;
// user.Id, user.Phone, user.Email vb. alanlara erişin.Contact sınıfı ayrıca şu metotları sunar:
InsertOrUpdateCustomField(string fieldName, string fieldValue)Anonymize()UpdateEmail(string email)UpdateLanguage(LanguagesEnum language)Kullanıcıların asistanlar aracılığıyla destek bileti oluşturmasına olanak tanıyan bir görev yönetim sistemidir. Biletler, WhatsApp bildirimleriyle birlikte CxPerium kullanıcılarına veya ekiplerine atanabilir.
Teknik ekibimiz entegrasyonunuzda size eşlik etsin — sorunuzu iletin, aynı gün dönelim.
Türkçe teknik destek · Entegrasyon danışmanlığı ücretsiz