11. Chatbot Source Code
11.1 General Structure of The Dialog File
The dialog page is where the ChatBot process is built according to a specific scenario. These files are created in accordance with CXPerium’s bot engine. Therefore, there are modules that need to be imported and classes that need to be used. Below, the general structure of a dialog page is shown. runDialog() method is the basic structure of the dialog page. All operations to be performed in the dialog process must be done in this method. For example, operations such as sending a message to the user, performing database operations, or redirecting to another dialog should be developed in this method. One thing to note here, if you want to create a method that is defined outside of runDialog() and use it in the Chatbot process, the related method should be called within the runDialog() method.
11.2 The Entry File
The Entry.ts file is a default and required initialize file used to start the Chatbot process or to make initial settings. It is the first file that runs for every interaction in the ChatBot process. For example, when the user types a message or presses a button, the “Entry.ts” file is executed first, followed by other files to be processed according to the corresponding Regex value. For example, in the example in Section 10.2.3.1. above, when the Regex value “hello” is captured as a message from WhatsApp, the “Entry.ts” file runs before the “Hello.ts” file runs. Then the “Hello.ts” file runs.
According to the scenarios built in Chatbot; “Entry.ts” file can be used to control users access to certain pages. For example, settings such as allowing a specific user group or a company’s dealer to access specific pages are made here. In the example below, “Entry.ts is runnig!” will be written in the console every time ChattBot interacts with the process.
11.3 Sending Text Messages
Sending a message is done with the sendMessage() method. The message to be sent is written between “…” in parentheses. For example, in order to reply “welcome” in the Chatbot process in response to the “hello” message in WhatsApp; first of all, the intent settings in Section 10.2. must be made. That is, Regex and file path information must be entered into CXPerium. In the example below, the dialog file path in CXPerium is “WelcomeDialog” and the Regex value is set as “hello.
11.4 Sending Button Messages
11.4.1 Create a Buton
According to WhatsApp rules, a maximum of 3 buttons can be used. The number of characters to be entered in the buttons must not exceed 20. Otherwise, WhatsApp will not recognize the button. (See: https://developers.facebook.com/docs/whatsapp/guides/interactive-messages/) If you want to create more than 3 button messages, a list button message should be sent (See: Section 11.5).
In sending button messages, the id value defined for the buttons is used as a Regex value in CXPerium. In this case, CXPerium captures which button is clicked with the id of the button and redirects the WhatsApp chat to the desired dialog page.
Before creating a button, the “TButton” type must be imported from “cxpreium-engine” and the syntax is
const VariableNameToBeGivenToButtons: TButton[] = [{id: ‘RegexValue1’,title:‘ButtonName1’},{id: ‘RegexValue2’,title:‘ButtonName2’},{{id: ‘RegexValue3’,title:‘ButtonName3’}].
Here the “tittle” must not exceed 20 characters. Otherwise, the button message will not appear. (See also the example in section 11.4.2)
11.4.2 Sending Button Messages
Sending a button message is done using the sendButtonMessage() method, which takes four parameters: Title, Footer, Text, and Buttons. Title, Footer, and Text parameters should be of type “string”, while the Buttons parameter should be a button object.
Syntax of sendButtonMessage() method is
this.sendButtonMessage(‘Header Info’,’Footer Info’,’Message content’,Buttons).
For example, defined as follows in the button message
const buttons: TButton[] = [{id: ‘BtnYes’,title:’Yes’},{id: ‘BtnNo’,title:’No’}],
where the IDs of the “Yes” and “No” buttons are “BtnYes” and “BtnNo”, respectively.
If you want to redirect to the “Yes.ts” file located in the WhatsApp folder inside the dialogs folder when the “Yes” button is clicked, and to the “No.ts” file when the “No” button is clicked, you should configure the intent settings in Section 10.2. as follows:
For the “Yes” button: Intent (File Path): CXPerium.Dialogs.WhatsApp.Yes, Regex Value: BtnYes or ^BtnYes$
For the “No” button: Intent (File Path): CXPerium.Dialogs.WhatsApp.No, Regex Value: BtnNo or ^BtnNo$
11.5 Sending List Messages
11.5.1 Create List Messages Button’s
If the number of buttons is more than 3, the button message cannot be sent due to WhatsApp rules. For this reason, sending a list message is preferred in cases where more than 3 buttons are needed. As a list message, WhatsApp can use a maximum of 10 buttons. The number of characters to be entered in the buttons should not exceed 20. Otherwise, WhatsApp will not recognize the button. (See: https://developers.facebook.com/docs/whatsapp/guides/interactive-messages/)
The id value defined for the buttons in the list message is used as a Regex value in CXPerium. In this case, CXPerium captures which button is clicked with the id of the button and redirects the WhatsApp chat to the desired dialog page.
First, “TRow” type should be imported from “cxpreium-engine” when creating list buttons. The syntax of list buttons as follows.
const listButtons:TRow []=[
{id: ‘RegexValue1′, title:’ButtonName1’, description: ‘Description1’},
{id: ‘RegexValue2′, title:’ButtonName2’, description: ‘Description2’},
{id: ‘RegexValue3′, title:’ButtonName3’, description: ‘Description3’},
{id: ‘RegexValue4′, title:’ButtonName4’, description: ‘Description4’}
];
where listButtons is variable name.
11.5.2 Sending List Messages
Sending a list button message is done with sendListMessage() method. It takes 5 parameters. These parameters are; “Header”, “Footer”, “Text”, “Start Button” and “List Buttons”. Header, Footer, Text and Start Button parameters must be strings. List Button parameter should also be a list button. Since the “Start Button” parameter is a button, it should not exceed 20 characters according to WhatsApp rules. Otherwise, the list button message will not appear.
The syntax of sendListMessage() method is as follows;
this.sendListMessage(‘List Header’, ‘List Footer’, ‘List Message Content’, ‘Start Button’, listButons)
11.6 Sending Survey
Surveys created in CXPerium are captured and used in the source code with the survey ID.
11.6.1 Creating a New Survey in CXPerium
For detailed information on how to create a new survey in CXPerium, see: https://www.cxperium.com/docs/create-a-new-survey/
11.6.2 Generating Survey IDs in CXPerium
The following screen appears when a new survey is created in CXPerium.
Here “Name” represents the name given to the created survey. It is the part that is only addressed to developers and not visible to users. By clicking the “GENERATE” button, the “Survey ID” of the related survey is created.
In CXPerium, a survey is identified by its “Survey ID“. CXPerium recognizes created surveys by their “Survey ID”. The “Survey ID” is the unique characteristic of surveys and is issued by CXPerium.
11.6.3 Sending Survey
Sending a survey is done with the sendSurvey() method. This method takes one parameter and this parameter is Survey ID. The syntax of sendListMessage() method is as follows;
this.sendSurvey (‘SurveyId”)
11.7 Capturing and Using Data
In the ChatBot process, the interactions and personal information of the user who has given permission within the scope of KVKK are kept in “activity” and “contact” objects, respectively. These objects represent user interactions and are used to process user information. These objects help the ChatBot to keep track of user interactions and provide appropriate responses to users. A user’s message on WhatsApp can be received and processed to create an appropriate response to the user’s request, or a personalized experience can be offered depending on the user’s profile. For example, in the Chatbot process, it helps to set up situations such as the separation of the pages that a company’s dealers will see and the pages that its customers will see.
An “activity” object represents the user’s interactions. When a user clicks a button or sends a message, these interactions are recorded in an “activity” object. The “activity” object contains the type of interaction (e.g. button click or message send), its content (e.g. message text or button id value) and other related information (e.g. location information). For example, a user’s location information can be accessed by looking up the location information in the corresponding “activity” object (“this.activity.location“), and the content of a user’s message can be accessed by looking up the “text” information in the “activity” object (“this.activity.text“).
The “contact” object represents personal information about the user. This information includes information about the user’s profile. It includes information such as username, e-mail address or phone number. For example, the user’s profile name can be accessed through the “userProfileName” information of the “contact” object (“this.contact.userProfileName“).
11.8 Interaction With the User
As detailed in Section 10.2., the routing of the Chatbot chat process according to specific Regex values expected from the user is defined in the Intent Section and performed by CXPerium. However, in some cases, the message content expected from the user (Regex value) is impossible to match exactly with the Regex values defined in CXPerium. For example, in scenarios such as asking the user their name or age and directing a Chatbot process based on this information, the answer that the user will enter cannot be determined as a Regex value in CXPerium. In such cases, the addWaitAction() method is used to capture the user’s input. This method waits for the user to interact and provides the ability to act according to the specified scenario.
The addWaitAction() method is used in together with the isWaitAction() method. isWaitAction() returns a boolean result. For example, in a scenario where the user is expected to click a button or send a message, if this interaction occurs, isWaitAction() returns “true”; otherwise, it returns “false” (by default). Then, according to the scenario, the desired actions can be performed using constructs such as if, switch-case. This provides a flexible solution for situations that cannot be handled with specific Regex values.
11.8.1 addWaitAction Method
addWaitAction() is a method in the “conversation” class. This method can be accessed as “this.conversation.addWaitAction“.
The addWaitAction() method has one parameter and takes a “string” expression as a parameter. The variable name to be given to the expected interaction state is entered as a parameter. The isWaitAction() method is also used to capture the name entered as a parameter and execute it if the user interacts with it.
The syntax of addWaitAction() method is as follows;
this.conversation.addWaitAction(‘ExpectedInteractionVariableName’)
(See example in Section 11.8.4)
11.8.2 isWaitAction Method
isWaitAction() method is a method in the “conversation” class and returns a boolean result. Default boolean value is “false“. isWaitAction() method has one parameter and takes a string expression as a parameter. addWaitAction() method takes the variable name of the expected interaction state as a parameter. isWaitAction() method captures the expected interaction from the parameter written from addWaitAction() method. It serves the desired purpose by returning “true” when the expected interaction state occurs. The syntax of the isWaitAction() method is as follows.
this.conversation.isWaitAction(‘VariableNameGivenToExpectedInteraction’)
(See example in Section 11.8.4)
11.8.3 removeWaitAction Method
The addWaitAction() method is used to indicate that an interaction is expected in the Chatbot process. Once the expected interaction is completed, the waiting state needs to be removed to allow the code flow to continue without waiting for further interactions. In this case, the removeWaitAction() method is used. To stop listening for interactions, the removeWaitAction() method should be called at the desired location. It doesn’t take any parameters. (See: Example in Section 11.8.4)
11.8.4 User Interaction Example
In our scenario, the user is asked for their name. Then, the user is addressed by their name. In this case, first, a “Please enter your name” message is sent, and then we wait to capture the name entered by the user using the addWaitAction(“waitName”) method. Here, the interaction waiting variable name is “waitName”. We wait for the user to enter the name with iswaitAction(“waitName”). When the user enters the data, the iswaitAction(“waitName”) method will return “true“, so the code inside the if statement will run. It redirects to the sayHello() method defined here. In the sayHello method, the entered data is captured from the “text” key of the “activity” object, and a message is sent to the person with their name. Then, the removeWaitAction() method ends the interaction.
11.9 Create a Ticket
According to the Chatbot chat process scenario, the “ticket” system can be used to track and resolve problems, requests, complaints and similar situations experienced by users. The requests received by the users in the Chatbot process are recorded as a “ticket” to be resolved by the related personnel. For example, when a user encounters a specific problem or makes a request during the Chatbot process, this request can be automatically created as a ticket. Information such as the subject, title and label of the ticket is stored in this “ticket”. Related tickets can be accessed from the “Ticket” page in CXPerium, the user can be contacted via CXPerium, the tickets created can be assigned to the related representative and the resolution process can be monitored. Ticket system can also increase user satisfaction and be an important tool in managing customer relations.
11.9.1 Ticket Creation Method
The ticket creation process uses the “this.services.cxperium.ticket.create()” method, which takes four parameters: “Subject”, “Contact id”, “Text”, and “Title”. The “Subject”, “Contact id”, and “Text” parameters are strings, while the “Title” parameter is an array. The “Subject” parameter specifies the subject of the created ticket. The “Contact id” parameter specifies the id of the user associated with the ticket. You can access the user’s id information through the “contact” object, as explained in Section 11.7. The “Text” parameter represents the content of the ticket. The “Title” parameter is used to add one or more titles to the ticket. It is not required, and if not used, it can be sent as an empty array.
The syntax of the this.services.cxperium.ticket.create () method is as follows.
this.services.cxperium.ticket.create(“Ticket Subject”, “Contact ID of the user creating the ticket”, “Content of the ticket message”, [“title1”, “title2”]).
11.9.2 Comment Creation Method
Adding a comment to a ticket is done using the “this.services.cxperium.ticket.comment()” method, which takes two parameters: “Ticket id” (strings) and “Text”(strings). The “Ticket id” parameter should contain the ID of the ticket to which the comment will be added. The “Text” parameter represents the content of the comment to be added to the ticket.
The syntax of the “this.services.cxperium.ticket.comment ()” method is as follows.
this.services.cxperium.ticket.comment(‘Ticket ID’, ‘Comment content to be sent’, [“header”])
11.9.3 Ticket Creation Example
In our scenario where the user communicates the return request via ChatBot and ChatBot receives this request and creates a ticket; the user contacts ChatBot to indicate that he wants to return a product. ChatBot sends a welcome message to the user as “To create your product return request, please specify the subject of your request.”. The user sends the message “Faulty product” as the subject of the return request and the details of the return request as “Hello, Faulty product has been sent”. The information received from the user is sent to CXPerium as a ticket. (The methods to be used to develop the Chatbot process that fits this scenario are described in detail in Section 11.3, Section 11.7 and Section 11.8).
First, a welcome message is sent to the user with the sendMessage() method and the 1st interaction from the user is waited with the addWaitAction() method. After the 1st interaction, the user is asked for the return request details with the sendMessage() method and the 2nd interaction is expected with the addWaitAction() method. After the 2nd interaction, the information entered by the user and the user contact id information is added as a parameter to this.services.cxperium.ticket.create() method and the ticket is created. Finally, sendMessage() method sends a message to the user that the request has been processed and the interaction is terminated with removeWaitAction(). In CXPerium, a ticket will be created on the Ticket page as in the picture below. Here, the subject information sent from the source code can be seen.
By clicking on the ticket, the subject and detail information sent from the source code will be seen on the ticket details page.
