ابنِ روبوتات محادثة WhatsApp مخصصة باستخدام حزمة QSoft.CxPerium .NET SDK — من التثبيت والحوارات إلى معالجة اللغة الطبيعية والمراسلة وWhatsApp Flows ووحدات المنصة.
أعدّ روبوت محادثة قائمًا على CxPerium من الصفر: أنشئ حسابك، ونزّل المشروع النموذجي، وشغّله خلف وكيل عكسي، ثم اربطه بالمنصة.
قم بزيارة app.cxperium.com. سجّل باسمك الكامل وبريدك الإلكتروني وكلمة المرور ثم أكّد رسالة التفعيل — أو استخدم Sign In (تسجيل الدخول) إذا كان لديك حساب بالفعل.
انتقل إلى مستودع CxPerium.BotTemplate وراجع وصف المشروع. انقر على زر Code، ثم إما أن تنزّل ملف ZIP أو تستنسخ المستودع عبر HTTPS.
أضف حزمة NuGet الخاصة بـ CxPerium QSoft.CxPerium إلى المشروع.
يعمل المشروع افتراضيًا على http://localhost:3978/. عدّل launchSettings.json إذا احتجت إلى تغيير المنفذ.
يلزم وكيل عكسي (ngrok) لتوجيه رسائل WhatsApp إلى جهازك المحلي. دوّن عنوان URL العام المُنشأ (مثل https://xxxxx.ngrok.io/).
حدد موقع appsettings.json وحدّث حقلي BotUrl وHookUrl. ثم انتقل إلى Settings > API Integration (الإعدادات ← تكامل API) في CxPerium، وانقر على Regenerate (إعادة الإنشاء) لإنشاء مفتاح API، وأضفه إلى الملف.
أرسل "Hello" إلى رقم WhatsApp التجريبي +90 850 309 45 52 — يرد الروبوت بـ "Hello World". يمكنك أيضًا استخدام الرابط المباشر https://web.whatsapp.com/send/?phone=908503094552&text=hi. روبوت المحادثة القائم على CxPerium يعمل الآن بنجاح.
# استنساخ المشروع النموذجي
git clone https://github.com/cxperium/CxPerium.BotTemplate.git
# توجيه رسائل WhatsApp إلى جهازك المحلي
ngrok http 3978 --host-header="localhost:3978"{
"BotUrl": "https://xxxxx.ngrok.io",
"HookUrl": "https://hook.example.com",
"ApiKey": "your_generated_api_key_here"
}يأتي مشروع المساعد النموذجي ببنية واضحة: دليل Channels، ودليل Dialogs، وملف التهيئة appsettings.json، ونقطة الدخول Program.cs.
CxPerium.BotTemplate/
├── Channels/
│ ├── CxPerium.cs
│ └── Whatsapp.cs
├── Dialogs/
│ └── MainDialog.cs
├── appsettings.json
└── Program.csتلتقط فئة CxPerium.cs الأحداث من منصة CxPerium:
تعالج فئة Whatsapp.cs الرسائل والأحداث الواردة:
ينبغي عدم تعديل هذا الملف إلا عند الضرورة؛ ويمكن تجاوز (override) أساليبه للمتطلبات الخاصة.
يحتوي مجلد Dialogs على ملف MainDialog.cs. أنشئ جميع حواراتك هنا لتنظيم أفضل للشيفرة وقابلية للتوسع.
يخزّن ملف appsettings.json مفاتيح API ومعلومات webhook التي حصلت عليها من CxPerium.
تدير الحوارات تدفق التفاعلات بين المستخدم والروبوت وتشكّل أساس تجربة المستخدم. يفصّل هذا القسم خطوات إنشاء حوار لروبوت محادثة باستخدام حزمة QSoft.CxPerium .NET SDK.
الحوار بنية منطقية تحدد كيفية استجابة روبوت المحادثة لاستفسارات المستخدم أو معالجته لسير عمل. في حزمة QSoft.CxPerium SDK، تُبرمج الحوارات ضمن إطار منطقي محدد لتحقيق النتائج المرجوة.
سننشئ حوارًا يرد فيه الروبوت بعبارة "I am a special assistant" عندما يرسل المستخدم الرسالة "who are you". أنشئ مجلدًا باسم Dialogs في مشروعك وأضف ملف فئة C# جديدًا باسم WhoAreYouDialog. يجب أن ترث الفئة من BaseWhatsAppDialog، وتنفّذ الواجهة IWhatsAppDialog، وتنفّذ الأسلوب RunDialog الذي تتطلبه.
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");
}
}
}افتح المنصة وانتقل إلى صفحة Assistant > Dialog (المساعد ← الحوار).
انقر على زر New Dialog (حوار جديد).
Dialog Name (اسم الحوار): مساحة الاسم الكاملة (مثل QSoft.CxPerium.Assistant.Dialogs.WhoAreYouDialog). Report Name (اسم التقرير): اسم وصفي لأغراض التقارير. Language (اللغة): لغة التعرف. Regex Value (قيمة Regex): نمط التفعيل ("who are you").
انقر على Save (حفظ) لتسجيل الحوار.
WhoAreYouDialog.BaseWhatsAppDialog.IWhatsAppDialog.RunDialog.Messages.SendMessage.يعتمد CxPerium ثلاثة أساليب متمايزة لفهم رسائل المستخدمين وتوجيهها إلى الحوارات المناسبة.
تُوجَّه الرسائل المطابقة لتعبيرات Regex إلى الحوارات ذات الصلة وتتقدم وفق القواعد المعرفة مسبقًا. يُنصح بتعريف قواعد Regex تطابق رسائل المستخدمين الأكثر تكرارًا.
عندما لا يكون للرسالة تطابق Regex، يفحص النظام إعدادات DialogFlowConfig في شاشة Assistant > Configuration (المساعد ← التهيئة). عند ضبط IsEnabled: true، تنتقل الرسالة إلى Google Dialogflow الذي يحلل دلالات الرسالة ويولّد ردًا أو يعيد إجراءً مقترحًا. يتطلب هذا التكامل مفاتيح Dialogflow API وتفاصيل المشروع.
إذا فشلت مطابقة Regex ولم يقدّم Dialogflow ردًا مناسبًا، يرجع CxPerium إلى إعدادات ChatGPTConfig. عند ضبط IsEnabled: true، تُوجَّه الرسالة إلى ChatGPT الذي يحللها مباشرة باستخدام نموذج معالجة لغة طبيعية مدعوم بالذكاء الاصطناعي. يتطلب هذا التكامل مفاتيح API واختيار النموذج وتعريفات المعلمات.
يضمن هذا التسلسل معالجة الرسائل عبر آليات تحكم متعددة والتعامل معها بالأسلوب الأنسب.
اربط Google Dialogflow بمساعدك بحيث تُحلَّل الرسائل غير المطابقة دلاليًا وتُوجَّه إلى الحوارات الصحيحة.
ادخل إلى Dialogflow Console وأنشئ وكيلًا (على سبيل المثال "DemoAgent" باللغة التركية). افتح إعدادات الوكيل وانتقل إلى إعدادات مشروع Google Cloud عبر رابط Project ID.
في Google Cloud، افتح قائمة Service Accounts (حسابات الخدمة)، وأنشئ حساب خدمة جديدًا بدور Owner (المالك)، وأنشئ ملف مفتاح JSON. احفظ الملف في مكان آمن.
في CxPerium، انتقل إلى Assistant > Configuration (المساعد ← التهيئة) وحرّر حقل DialogFlowConfig. ضع ملف مفتاح JSON في الدليل الجذر للمشروع وهيّئه ليُنسخ أثناء عمليات البناء.
أنشئ intent بردّ نصي في Dialogflow، ثم أرسل عبارة التدريب المرتبطة به عبر WhatsApp للتحقق من عمل التهيئة.
يتطلب حقل DialogFlowConfig ما يلي:
demoagent-xxxxx.json).project_id من ملف JSON.True.أضف custom payload إلى intent في Dialogflow لربطه بفئة حوار:
{
"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 داخل الحوار:
public void RunDialog()
{
var country = this.Parameters["country"];
this.Messages.SendMessage($"Country parameter: {country}");
}هيّئ تكامل ChatGPT بحيث تُجاب الرسائل التي يتعذر على Regex وDialogflow التعامل معها بواسطة مساعد OpenAI.
افتح متصفحك وانتقل إلى https://platform.openai.com/. إذا كان لديك حساب OpenAI بالفعل، فانقر على Log In (تسجيل الدخول)؛ وإلا فانقر على Sign Up (إنشاء حساب) لإنشاء حساب جديد.
بعد تسجيل الدخول، انتقل إلى قائمة Assistants (المساعدون)، وانقر على Create New Assistant (إنشاء مساعد جديد)، وهيّئ المساعد وفق متطلباتك.
افتح صفحة تفاصيل المساعد الذي أنشأته وانسخ Assistant ID (معرّف المساعد). ثم انتقل إلى قسم API Keys (مفاتيح API)، وانقر على Create New API Key (إنشاء مفتاح API جديد)، واحفظ المفتاح المُنشأ في مكان آمن — سيُستخدم أثناء التكامل مع CxPerium.
في منصة CxPerium، انتقل إلى قسم Assistant (المساعد) وافتح شاشة Configuration (التهيئة). هيّئ إعدادات ChatGPTConfig: أدخل قيمتي ApiKey وAssistantId اللتين حصلت عليهما من منصة OpenAI واضبط حقل IsEnabled على True.
بعد إتمام هذه الخطوات، سيكون تكامل ChatGPT مع CxPerium جاهزًا.
تحتوي وحدة التوطين على إعدادات تتيح للمساعد عرض الرسائل المرسلة عبر روبوت المحادثة بلغات مختلفة.
يمكن الوصول إلى قائمة التوطين عبر Assistant > Localization (المساعد ← التوطين). تتيح لك تعريف مفاتيح التوطين والقيم المقابلة لها عبر لغات مختلفة. وداخل مشروعك، تسترجع فئة Localization قيم هذه المفاتيح.
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 النص إلى لغة محددة:
string message = Localization.GetLocalizationTextByLanguage("SessionTimeoutMessage", LanguagesEnum.Turkish);NotImplementedException.أساليب المراسلة في حزمة CxPerium .NET SDK للتواصل عبر WhatsApp. يتم الوصول إلى جميع الأساليب من خلال الكائن Messages المتاح عند الوراثة من الفئة BaseWhatsAppDialog.
يرسل رسائل نصية، مع معاينة اختيارية لعناوين URL.
this.Messages.SendMessage("Hello World");
this.Messages.SendMessage("Hello CXPerium https://www.cxperium.com", true);يسلّم رسالة بأزرار تفاعلية (يُسمح بثلاثة أزرار كحد أقصى).
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);
}
}ثلاثة أشكال لإرسال الصور: ملف محلي أو معرّف وسائط أو عنوان 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");يرسل إحداثيات جغرافية مع تفاصيل الموقع.
this.Messages.SendLocationMessage(40.712776, -74.005974, "New York", "New York, NY, USA");ثلاثة أشكال لإرسال المستندات: ملف أو معرّف وسائط أو عنوان 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");ثلاثة أشكال لإرسال الفيديو: ملف أو معرّف وسائط أو عنوان 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");يسلّم رسائل قوائم تفاعلية بصفوف و/أو أقسام.
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);أساليب مراسلة إضافية: طلبات الموقع وبطاقات جهات الاتصال والملصقات وتفاعلات الرموز التعبيرية ورسائل الكتالوج / المنتجات.
يشارك موقعًا محددًا مع المستخدم عبر الإحداثيات وتفاصيل العنوان. المعلمات: lat (double) وlon (double) وname (string، مثل "Office") وaddress (string).
SendLocationMessage(double lat, double lon, string name, string address);
SendLocationMessage(40.987654, 29.123456, "QSoft Office", "Istanbul, Turkey");يطلب الموقع الحالي للمستخدم عبر WhatsApp. المعلمة هي نص رسالة الطلب.
this.Messages.SendLocationRequest("Please share your location.");يرسل بطاقة جهة اتصال تحتوي على الهاتف والاسم والبريد الإلكتروني والتفاصيل المهنية.
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");يرسل ملفات ملصقات إلى المستخدمين بصيغة WebP.
SendSticker(string stickerUrl);
SendSticker("https://example.com/sticker.webp");يضيف تفاعل رمز تعبيري على رسالة أو يزيله. يُسمح برمز تعبيري واحد لكل تفاعل؛ ويؤدي إرسال سلسلة فارغة إلى إزالة الرمز التعبيري السابق. تُدعم الرموز التعبيرية المتوافقة مع Android/iOS والرموز المعالجة.
SendEmoji(string messageId, string emoji);
SendEmoji("1234567890", "😊");
SendEmoji("1234567890", "");يعرض كتالوج المنتجات المرتبط في WhatsApp. المعلمتان: محتوى رسالة الكتالوج ونص التذييل.
SendCatalog(string message, string footer);
SendCatalog("Discover our products!", "Contact us for more information.");يرسل تفاصيل منتج واحد من كتالوج Meta. المعلمة هي المعرّف الفريد للمنتج في كتالوج Meta. يجب إضافة المنتج أولًا إلى كتالوج Meta قبل إمكان إرسال تفاصيله.
this.Messages.SendProductMessage("1");يرسل قوائم منتجات متعددة في رسالة واحدة منظمة.
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);كيفية استخدام WhatsApp Flows في حزمة CxPerium SDK لروبوتات محادثة WhatsApp المخصصة.
WhatsApp Flows ميزة مراسلة تجارية تتيح تفاعلات منظمة. فبدلًا من المحادثة التقليدية، توفر واجهة شبيهة بالنماذج دون مغادرة WhatsApp — ما يحقق تجربة مستخدم سلسة وجمعًا منظمًا للبيانات وكفاءة في الحصول على المعلومات.
يرسل الأسلوب this.Messages.SendFlowMessage رسائل WhatsApp Flows وله عدة أشكال (overloads):
// الاستخدام 1
SendFlowMessage(string message, string headerText, string footerText,
string buttonText, Type catchedDialog, string flowIdOrName, string screen)
// الاستخدام 2
SendFlowMessage(string message, Uri url, string footerText,
string buttonText, Type catchedDialog, string flowIdOrName, string screen)
// الاستخدام 3
SendFlowMessage(string message, Uri url, string footerText,
string buttonText, Type catchedDialog, string flowIdOrName, string screen, JObject data)
// الاستخدام 4
SendFlowMessage(string message, string headerText, string footerText,
string buttonText, Type catchedDialog, string flowId, string screen, JObject data)يجب أن يشتق الحوار الذي سيلتقط بيانات النموذج من BaseWhatsAppDialog وينفّذ الواجهة IFlowReceiveMessage:
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;
// عالج بيانات النموذج هنا.
}
}
}حوار يفتح النموذج:
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"
);
}
}
}حوار يلتقط بيانات النموذج:
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");
}
}
}هيّئ عنوان الروبوت أدناه كنقطة نهاية للـ Flow — فهو يدير انتقالات الشاشات وديناميكيات النموذج:
https://yourboturl/api/CxPerium/flowsللتعامل مع إجراء data_exchange، نفّذ الواجهة IFlowDataExchange:
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;
}
}يلزم مفتاح RSA بطول 2048 بت لتبادل البيانات الآمن — راجع دليل تشفير WhatsApp Business للتفاصيل. أضف ملف المفتاح الخاص إلى المشروع:
سمِّ الملف private.pem.
اضبط Build Action (إجراء البناء) للملف على Embedded resource (مورد مضمّن).
بوجود هذا الإطار، يمكّن CxPerium الشركات من الاستفادة من WhatsApp Flows لتفاعلات عملاء منظمة وفعالة.
نظرة عامة على وحدات CxPerium ودمجها في روبوتات محادثة WhatsApp باستخدام C#. يوفر CxPerium أربع وحدات رئيسية — المحادثة المباشرة والاستطلاعات وCRM والتذاكر — لكل منها وظائف مميزة للتفاعل مع العملاء.
تتيح دعم العملاء في الوقت الفعلي وردودًا فورية على استفسارات المستخدمين. حوّل محادثة إلى المحادثة المباشرة من أي حوار:
using QSoft.CxPerium.Dialogs.WhatsApp;
using System;
namespace QSoft.CxPerium.Assistant.Dialogs
{
public class MainDialog : BaseWhatsAppDialog
{
public override void RunDialog()
{
this.LiveChat.TransferToLiveChat();
}
}
}حوّل المحادثة إلى فريق محدد:
string teamId = "TEAM_ID_HERE";
this.LiveChat.TransferToLiveChatByTeam(teamId);تعامل مع webhook الذي يُطلق عند إغلاق محادثة مباشرة:
protected override void OnClosingLiveChat(Contact contact)
{
base.OnClosingLiveChat(contact);
}مصممة لقياس تجربة المستخدم وجمع ملاحظات العملاء حول الرضا والاحتياجات. تتيح لك webhooks الاستطلاعات التفاعل مع الإجابات وحالات الإكمال:
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);
}أرسل استطلاعًا من المساعد:
this.Survey.SendSurvey("surveyid");يدير علاقات العملاء ويخزّن سجلات تفاعلاتهم. تُنشأ السجلات تلقائيًا عندما يراسل المستخدمون رقم WhatsApp المرتبط مع موافقة GDPR. اصل إلى بيانات جهة الاتصال من أي حوار:
var user = this.Contact;
// الوصول إلى user.Id وuser.Phone وuser.Email وغير ذلك.توفر فئة Contact أيضًا هذه الأساليب:
InsertOrUpdateCustomField(string fieldName, string fieldValue)Anonymize()UpdateEmail(string email)UpdateLanguage(LanguagesEnum language)نظام إدارة مهام يتيح للمستخدمين إنشاء تذاكر دعم عبر المساعدين. يمكن إسناد التذاكر إلى مستخدمي CxPerium أو الفرق، مع إشعارات WhatsApp.
دع فريقنا التقني يرافقك في عملية التكامل — أرسل سؤالك وسنعاود التواصل معك في اليوم نفسه.
دعم فني متخصص · استشارات تكامل مجانية