Create Your First Chat App From Scratch

This document provides a step-by-step guide on how to develop a basic chatbot application that handles user interactions, responds, and directs users. It focuses on building a simple, functional chatbot structure based on a rule-based architecture, which responds according to message types, handles user selections, and requests files when necessary.

What is a Chatbot?

A chatbot is a software application that can automatically respond to user queries, interact, and typically works with predefined rules or artificial intelligence models. They can be used in live support systems, sales guidance, surveys, feedback collection, and many other areas.

Rule-Based Chatbot Approach

The chatbot type discussed here is a "rule-based" model. In these chatbots, incoming messages are checked against specific keywords, choices, or message types, and appropriate responses are returned. Benefits of rule-based chatbots:

Quick to develop
Easy to control
Highly effective for simple workflows

Of course, for more complex applications, AI-based solutions can be preferred, but in this document, we will focus on building a basic interaction system.

In this guide, we will cover the following topics:

Creating an API Endpoint
Handling incoming messages with callbacks
Decision-making based on message types and taking appropriate actions

Creating an Endpoint

To handle user interactions coming from the Chat API, you need to define an HTTP endpoint on your server. This endpoint is the entry point for your system to communicate with the outside world and receive incoming messages. Typically, this endpoint acts as a webhook. When the Chat API sends a POST request to this endpoint, the message content will be processed.

Your endpoint should fulfill the following requirements:

Accept HTTP POST requests
Parse the JSON body
No authentication required (if running in a secure environment)

NestJS
@Post('/callback')
async defaultChatBotCallback(@Body() callbackDto:CallbackDto) {
// Incoming message will be processed here
}

In this example, a POST endpoint is defined using the @Post('/callback') decorator. When the Chat API sends a POST request to this URL, the JSON content from the request body is passed directly to the callbackDto parameter using the @Body() decorator. This allows easy processing of the message data.

Incoming Callback Body Content

The body of the incoming POST request represents the interactions the user has during the chat session. When the user starts the chat, the system sends an "init" type message. This message helps identify the starting point of the chat and allows the chatbot to begin the interaction. The message.content.messageType field is checked for the value "init", indicating that the chat has started, and the initial greeting or interaction can be triggered.

Example Message When User Starts the Chat (messageType: "init")

{
  "message": {
    "baggage": {
      "flags": ["no_client_caching"]
    },
    "category": "chat",
    "content": {
      "messageType": "init",
      "version": 3,
      "messageContent": {
        "initID": null,
        "locale": "en_US",
        "messageText": null,
        "name": "",
        "version": 0
      }
    },
    "conversationId": "s9xV6pP06EHtar/j5e5+oek8fn8uoLjwkFbrD6yNEW8=",
    "from": {
      "ecoId": "skor",
      "userId": "john.doe@kobil.com"
    },
    "idempotencyId": "4e353cd2-56d1-400b-bcbe-f75375faeaea",
    "messageId": "AtmXUlU4mJ56Zh8ucS",
    "timestamp": "2025-05-05T11:09:48.005Z",
    "serviceUuid": "4b4369d4-649e-47c9-95bb-87dd67121347",
    "instanceId": "instance-d95a404b-8949-4092-94ec-6fc6fba4c06f"
  }
}

Key Fields:

Field Name	Description
ecoId	Represents the tenant to which the application belongs.
userId	Identifies the user.
serviceUuid	A unique identifier for the service or session the message belongs to.
messageType	Specifies the type of the message.
messageText	The actual message content from the user, used in the bot’s decision-making process.

First Greeting Based on Message Type, Taking Action Based on Message Content

Message Type Control (messageType)

To determine the start of the chat, check if message.content.messageType equals "init". In this case, a greeting message and options for the user can be displayed.

Decision Based on Message Content (messageText)

The message content allows us to understand the type of feedback the user provides. The messageText represents the choices made by the user, and actions can be triggered based on these selections. This section can be managed using a switch-case structure, where an appropriate action is executed for each specific message.

Switch-Case Structure

The user's message is checked, and for each different message, an appropriate action is taken.

Options and Related Actions

For example, when the user selects "😁 Very Satisfied", a thank- you message is sent, followed by another query. Different paths can be taken for each option.

Example Code Implementation

async defaultChatBotCallback(callbackDto: CallbackDto) {
  const messageText =
    callbackDto?.message?.content?.messageContent?.messageText;

  if (callbackDto?.message?.content?.messageType === 'init') {
    await this.sendMessage(
      {
        messageType: MESSAGE_TYPE.choiceRequest,
        messageContent: {
          messageText: `How satisfied are you with your support experience?`,
          choices: [
            { text: '😁 Very Satisfied' },
            { text: '🙂 Satisfied' },
            { text: '😐 Neutral' },
            { text: '🙁 Dissatisfied' },
            { text: '😡 Very Dissatisfied' },
          ],
        },
      },
      callbackDto.message.serviceUuid,
      callbackDto.message.from.userId,
    );
    return;
  }

  switch (messageText) {
    case '😁 Very Satisfied': {
      await this.sendMessage(
        {
          messageType: MESSAGE_TYPE.processChatMessage,
          messageContent: {
            messageText: 'Thanks for your feedback! We appreciate your time',
          },
        },
        callbackDto.message.serviceUuid,
        callbackDto.message.from.userId,
      );

      await this.sendMessage(
        {
          messageType: MESSAGE_TYPE.choiceRequest,
          messageContent: {
            messageText: 'Is there anything else we can do for you?',
            choices: [
              { text: 'Yes, please!' },
              { text: 'No, thank you!' },
            ],
          },
        },
        callbackDto.message.serviceUuid,
        callbackDto.message.from.userId,
      );
      break;
    }

    case '🙂 Satisfied':
    case '😐 Neutral':
    case '🙁 Dissatisfied':
    case '😡 Very Dissatisfied':
    default: {
      await this.sendMessage(
        {
          messageType: MESSAGE_TYPE.choiceRequest,
          messageContent: {
            messageText: 'You can set any default message here',
            choices: [
              { text: 'Choice 1' },
              { text: 'Choice 2' },
            ],
          },
        },
        callbackDto.message.serviceUuid,
        callbackDto.message.from.userId,
      );
    }
  }
}

In this guide, we have created a simple rule-based chatbot that can respond to user messages and selections. By setting up the necessary endpoints and processing the incoming messages, we built a basic but functional chatbot.

By integrating KOBIL Chat, KOBIL Pay, and KOBIL TMS endpoints, you can extend this chatbot to handle more advanced tasks like payments, invoice generation, and file signing. Storing user selections in a database allows you to create more personalized and intelligent bots for various use cases.