You designed your chatbot using Chat4Us-Creator. Now it’s time to integrate it into your own website or app, allowing users to interact with the chatbot for customer service or any other purpose. If you navigate to downloads page, you will find two sample projects ready for download.
In this tutorial, we will cover client-server communication mechanisms that are project-specific because the rest of the source code is UI management that any regular developer must master by default.
1. Registering remote clients
Before we move to the main topic, we need to know about how remote clients are registered in Chat4US-Creator so that chatbot servers can recognize them and grant access to chat sessions. Chat4Us-Creator administrator have to provide the following data for a remote client:
- Select the Client tab that is located in the left panel of the main window.
- Right-click on an empty area, then select “Add…” from the popup menu or choose Clients > Add…, the New Remote Soft/Web Client dialog will appear.
- Add the domain name and IP address where the remote client will make requests from.
- Enter a credential key (Key1 and Key2) or generate random ones; save them as you won’t have access to, when you validate the client.
- Select the AI group the client will belong to. A client has restricted access to chatbots belonging to the same AI grouping.
- Enter a description, if needed.
- Validate by pressing Enter or click the Save button to register the new client.
2. ChatBot Server API
All client-server data exchanges are secured using SSL certificates. Chat4Us-Creator allows the use of self-signed certificates, but it is highly discouraged to use them in production especially when chatbot servers are accepting connections from the internet.
2.1. Data structure
The client sends requests using the POST method and application/x-www-form-urlencoded as content type. The chatbot server allways responds with JSON content type that has the following structure:
- STATUS: Response status, either OK or ERROR.
- TOKEN: Exists only on a login response. The token should be part of any further queries.
- MESSAGES: Array of incoming messages from the chatbot server. Usually with a length of 1.
- CHAT_ENDED: True when the chat session is ended and the client is disconnected.
- LOCALE: Current chat session locale. ID of current language (AR, EN, FR, etc.).
- CHATBOT_WAITING: True if the chatbot is waiting to resume the chat session after switching CHAT_STATE.
- CHAT_STATE: Current chat session state. Could be one of the following values:
- CHATBOT: Currently chatting with a static Q&A chat flow.
- AIMODEL: The chat session is animated by a Large Language Model.
- AGENT: The chat is animated by a human via the messenger app Chat4Us-Agent.
When logged in and for any potential reason when the chat bot server encounters an error or refuses to fulfill a client query, a JSon response like the one bellow is returned:{
"STATUS" : "ERROR",
"ERROR_MESSAGE" : "Error message description.",
"ERROR_CODE" : ###
}
2.2. Login query
To log in and access a chatbot server, the client should send a POST query to https://chatbot_host:port/login with the following data:
- key1: Client credential first key.
- key2: Client credential second key.
The chatbot server should respond with a status OK and an access TOKEN that must be included in every further query:{
"STATUS" : "OK",
"TOKEN" : "Random Token String"
}
2.3. Logout query
To log out, a POST query to https://chatbot_host:port/logout with the login token as data should be sent to the chatbot server. A status OK is then returned:{
"STATUS" : "OK"
}
2.4. LetsChat query
The LetsChat query starts a new chat session and returns the chat flow node entry’s message. The client sends a POST request to https://chatbot_host:port/letschat with the login token and the user ID, telling the chatbot server to start a chat session. The following is an example of the expected JSON response:
{
"CHATBOT_MESSAGE" : ["Entry node message."],
"STATUS" : "OK",
"LOCALE" : "EN",
"CHAT_STATE" : "CHATBOT",
"CHAT_ENDED" : false
}
2.5. Message query
The message query is used to deliver a remote user’s input to a chatbot server. A POST request is sent to https://chatbot_host:port/message with the user’s input and ID, along with the login token. The JSON response structure is similar to LetsChat query:
{
"CHATBOT_MESSAGE" : ["Response message."],
"STATUS" : "OK",
"LOCALE" : "EN",
"CHAT_STATE" : "CHATBOT",
"CHAT_ENDED" : false
}
2.6. Special cases to handle
We have seen regular chatbot server responses that a soft/web client will handle from the start of a successful login to a logout, but there are some special cases a client should be aware of and handle to deliver a better user experience.
2.6.1. When CHAT_ENDED is True
When the CHAT_ENDED field is set to True in a JSON response, the client must inform the remote user that the chat session is ended and the chatbot server will refuse any further queries for that session. At that moment, the server already archived the ended session and freed any related system resources from memory. A chat flow logic is usually behind setting an end to chat sessions. In some cases, the server may end a chat when an unexpected error occurs, this is why it is highly recommended to check Chat4Us-Creator’s log files for potential errors or chat flow logic bugs.
2.6.2. When CHATBOT_WAITING is True
The CHATBOT_WAITING field will appear in a JSON response only when the CHAT_STATE changes value. When a chat flow logic switches state from CHATBOT to AIMODEL, the chatbot server returns the message(s) from the node that triggered the switch; then set CHATBOT_WAITING to True to inform the client logic to send an automatic/hidden query to let the connected LLM generate a first response to the remote user. The client should send any message query for this purpose – as indicated in the two sample projects provided on the download page, which include “…”.
The client should make adjustments to the UI in order for users to have a clear understanding of who they are interacting with.
2.6.3. When LOCALE changes
The LOCALE field is set to the RIA file’s main locale value and may change value when running multi-language chat flows. The client should monitor this field and make UI adjustments when the value changes especially when set from LTR to RTL languages.
2.6.4. Messages format
When utilizing the Bahia Palace virtual assistant example, you may observe that chat messages are sent to remote users in HTML format, each accompanied by buttons at their conclusion. This enables effortless interaction with the chat flow logic by simply clicking on a button, which can be utilized as an opportunity to elevate your own implementation by adopting this strategy on a higher level.
3. Sample projects
Now that we have a clear understanding of the chatbot servers API and client-server’s data exchange mechanisms, it’s essential to delve into the sample projects source codes for an even more in-depth understanding. This will serve as a foundation for developing more sophisticated chatbot clients capable of handling complex interactions with users. Furthermore, analyzing the code used within these samples can provide valuable insights into how different components interact and work together seamlessly.
3.1. Software client
An Eclipse IDE Java Swing project. A cross-platform messaging app, developed in a comprehensive manner to let developers understand the mechanisms to use for communicating with chatbot servers to enable users to interact with virtual assistants.
To get a better understanding, start by reviewing ServerConnector.java as it aligns with the concepts covered in this tutorial. The remainder of the project focuses on UI management, utilizing the ServerConnector class to interact with chat bot servers. Notably, the source code is highly readable and adaptable for reuse across platforms like Android Studio, requiring only minor modifications for compatibility.
3.2. Web client
A web project developed using easy to understand HTML, CSS, JavaScript and PHP source code. It is a demo website implementing a chat IFrame that allows users to interact with virtual assistants inside a web browser. This feature is very useful for websites owners who need to integrate a chatbot for any purpose.
To follow along, navigate to webchatclt/WebChatClt/bot/index.php and webchatclt/WebChatClt/js/wcc_main.js in the sample project where the concepts are put into practice. The rest of the development focuses on general web design applications; Apache or Nginx must be installed and running to serve the project locally through your machine.
Conclusion
By reading this tutorial, you may acquire knowledge that leads you to develop your own chatbot clients. In fact, the ability to design and create sophisticated conversational interfaces can be a game-changer for individuals and organizations alike. By understanding how Chat4Us components work together seamlessly, you’ll unlock new possibilities for creating engaging virtual interactions. If not done yet, please refer to the following guides for better undertstanding of how these components are designed to come together in harmony to deliver the most enjoyable virtual chat experience possible.
Get Started
ChatBots Examples
Chat4Us-Creator User Guide
Chat4Us-Agent User Guide