# Introduction

It is based on the [MVC](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) pattern and strongly inspired by [Rails](https://rubyonrails.org/), so if you have ever worked on this framework, Kogno will be very familiar to you. 

{% hint style="success" %}
Currently, with Kogno you can develop conversational applications in Messenger, WhatsApp and Telegram, maintaining a **unified code** in a single application for all of them.
{% endhint %}

## It's all About the Conversation.

As Kongo was created to develop conversational applications, many definitions, elements and methods were adopted from conversational concepts.

One of the most important concepts are the **contexts**, where most of the conversational logic will reside in an application, developed with this framework.

When a user sends a message, Kogno will determine the context of the conversation. In this context would reside the logic for processing the message and eventually send a reply to the user and/or even move the conversation to another context if it's necessary.

![](https://3096180315-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LvKT8QLxtgmljG5_-j1%2Fuploads%2FslVD9t9Sy9aPh1629PyS%2Fkogno_conversation_diagram.jpg?alt=media\&token=6d0a4140-2a4f-4566-85fb-80491b839032)

## What does a Context look like in Kogno?

A context in Kogno is represented by a <mark style="color:orange;">`class`</mark>, where a series of [code blocks](https://docs.kogno.io/contexts/blocks) are defined, one for each type of message or event expected.

When a message/event arrives, only one of these blocks will be executed, if the characteristics of the message matches with the block's execution criteria.

In the example below,  <mark style="color:orange;">`MainContext`</mark> will have the ability to handle the following scenarios:

* [`intent`` `<mark style="color:blue;">`"greeting"`</mark>](https://docs.kogno.io/contexts/blocks/intent): A greeting message such as <mark style="color:blue;">"Hello"</mark> or <mark style="color:blue;">"Hi"</mark>. Which was previously created and trained on the NLP engine.
* [`postback`<mark style="color:blue;">`"featured_products"`</mark>](https://docs.kogno.io/contexts/blocks/postback):  Click event on the button <mark style="color:blue;">`"View Products"`</mark> that have been sent as reply in the previous block `intent`` `<mark style="color:blue;">`"greeting"`</mark>.&#x20;
* [`keyword [`<mark style="color:blue;">`"stop"`</mark>`,`` `<mark style="color:blue;">`"quit"`</mark>`]`](https://docs.kogno.io/contexts/blocks/keyword) : Specifically two keywords <mark style="color:blue;">"stop"</mark> or "<mark style="color:blue;">quit"</mark>.
* [`everything_else`](https://docs.kogno.io/contexts/blocks/everything_else): Any message whose characteristics didn't match the execution criteria of the blocks explained above.

```ruby
class MainContext < Conversation

  def blocks

    intent "greeting" do
    
      @reply.text "Hello!"
      @reply.button(
        "How can I help you today?",
        [
          {
            title: "View Products",
            payload: "featured_products"
          },
          { 
            title: "My Cart",
            payload: "purchases/view_cart"
          }
        ]
      )
      
    end
    
    postback "featured_products" do
    
      @reply.text "Alright."
      @reply.template "products/featured", title: "Here is a list of today's featured products."
      
    end
    
    keyword ["stop", "quit"] do
    
      @reply.text "Alright"
      @reply.typing 2.seconds
      @reply.text "I'll stop writing you now.."
      
    end
    
    everything_else do 
    
      @reply.text "Sorry, but I don't understand what you said."
      
    end

  end

end
```

## Parallel with Rails

For best understanding, this introductory chapter will draw a parallel with MVC pattern and Rails.&#x20;

After creating a new project by running <mark style="color:purple;">`kogno new your_project`</mark> in the terminal, the initial directory structure will contain several directories that will be explained in the following chapters, but the part we'll draw the parallel, is on the `bot/` directory.

```
├── bot
│   ├── contexts
│   │   └── main_context.rb
│   ├── templates
│   │   └── main
│   ├── models
│   │   └── user.rb
│   ├── conversation.rb
```

### `contexts/` (Controller in Rails)

The term **"context"** used in Kogno would be the equivalent of what the **"controller"** is in Rails.

Just as in an <mark style="color:orange;">`ActionController`</mark> class in Rails, the logic that coordinates the interactions between a user visiting a web, with views and models is written in files such as `products_controller.rb`, `purchases_controller.rb` and so on.

In a <mark style="color:orange;">`Context`</mark> class in Kogno, the logic that coordinates the interactions between an user who sends a message, with the templates and the models, are also written in files such as`products_context.rb`, `purchases_context.rb` or `main_context.rb` (created by default).

{% hint style="success" %}

### Routes

Just as in Rails, requests to a certain URL on a website can be handled by a particular `controller`, in Kogno you can also route messages and events to a particular context.&#x20;

Check [Routing section](https://docs.kogno.io/contexts/routing) for more information.
{% endhint %}

### `templates/`(Views in Rails)

In a conversational application there are no views like in Rails, but there are reply messages, which could be defined in files with an <mark style="color:purple;">`.erb`</mark> extension in directories like `bot/templates/main` (created by default), `bot/templates/products` and `bot/templates/purchases`.

#### Template creation

The example template below is created in `bot/templates/main/menu.erb` file and will expect two parameters: `message` and `buttons_message` which will be explained below.

```ruby
<%  
  @reply.text message
  @reply.typing 1.second
  @reply.button(
    buttons_message,
    [
      {
        title: "View Products",
        payload: "featured_products"
      },
      { 
        title: "My Cart",
        payload: "purchases/view_cart"
      }
    ]
  )
%>
```

#### Use of templates

To use a template, the [<mark style="color:orange;">`@reply.template()`</mark>](https://docs.kogno.io/templates)  method must be called, which would be the equivalent of the [<mark style="color:orange;">`render()`</mark>](https://guides.rubyonrails.org/layouts_and_rendering.html#using-render) method in Rails.&#x20;

#### <mark style="color:orange;">`template(route=String, params=Hash)`</mark>

In the example below you can see how the same template <mark style="color:blue;">`"main/menu"`</mark> is used in different situations in the conversation, such as when the user sends a message like "Hi" , "Thank you" or even when the app hasn't understood what the user has said.

```ruby
class MainContext < Conversation

  def blocks

    intent "greeting" do 
    
      @reply.template("main/menu",
        {
          message: "Hello!",
          buttons_message: "How can I help you today?"
        }
      )
      
    end 

    intent "thanks" do 
    
      @reply.template("main/menu",
        {
          message: "You're welcome!",
          buttons_message: "Is there anything else I can help you with?"
        }
      )
      
    end

    everything_else do
    
      @reply.template("main/menu",
        {
          message: "Sorry, but I don't understand what you said.",
          buttons_message: "Maybe I can help you with this.."
        }
      )
      
    end
  
  end

end
```

### `models/` (Model in Rails)

The way this section works doesn't change at all from Rails, since the [`ActiveRecord`](https://www.rubydoc.info/gems/activerecord) library is also used in Kogno.&#x20;

In a new project, <mark style="color:orange;">`User`</mark> (database table `users`) is a model that by default is already created in `bot/models/users.rb` file.

```ruby
class User < ActiveRecord::Base
end
```

{% hint style="warning" %}
When an incoming message arrives from a user, the framework will automatically create a record with the user's information in the `users` table in database.&#x20;
{% endhint %}

#### Use in the conversation

Within a block or template, <mark style="color:blue;">`@user`</mark> can be called, since this is the instance of the `User` model for the message sender.

```ruby
class MainContext < Conversation

  def blocks

    intent "greeting" do 
    
      unless @user.first_name.nil?
        @reply.text "Hello #{@user.first_name}!"
      else
        @reply.text "Hello!"
      end

      case @user.platform
        when "messenger"
          @reply.text "You're in Messenger"
        when "whatsapp"
          @reply.text "You're in WhatsApp"
        when "telegram"
          @reply.text "You're in Telegram"
      end
      
    end 
      
  end

end
```

Read more about fields and methods of the User model [here](https://docs.kogno.io/models/user-model).

{% hint style="info" %}
All the models needed can be created and make the necessary association between them and/or with `User` model.&#x20;

Read more about `ActiveRecord` in the [official documentation](https://www.rubydoc.info/docs/rails/3.1.1/ActiveRecord/Base).
{% endhint %}

### `conversation.rb` (application\_controller.rb in Rails)

Last but not least, the <mark style="color:orange;">`Conversation`</mark> class, which would be equivalent to <mark style="color:orange;">`ApplicationController`</mark> class in Rails.&#x20;

All contexts inherit from this class and the entire conversation goes through it.&#x20;

In it, global logics or validations of the conversation could be defined by calling callbacks.

```ruby
class Conversation < Kogno::Context

  before_blocks :do_something_before_blocks
  after_blocks :do_something_after_blocks

  def do_something_before_blocks
    # This will be called before the blocks method in the current context will be executed
  end

  def do_something_after_blocks
    # This will be called after the blocks method in the current context will be executed
  end

end
```

## Service Integrations&#x20;

### Messaging Platforms Supported

* [Messenger](https://docs.kogno.io/getting-started/messenger-configuration)
* [Telegram](https://docs.kogno.io/getting-started/telegram-configuration)
* [WhatsApp](https://docs.kogno.io/getting-started/whatsapp-configuration)

### **Natural language processing** (NLP)&#x20;

* [Wit.ai](https://wit.ai)

### Database

A project in Kogno needs to be connected to a database, which will contain the tables associated with the models through the [`ActiveRecord`](https://www.rubydoc.info/gems/activerecord) library.

* MySQL

### Error Notification

* [Slack](https://slack.com)

## About this project

Kogno was designed and developed by Martín Acuña Lledó ([@maraculle](https://twitter.com/maraculle)).

This project was backed by [Start Node](http://startnode.com/en) and my family.

### The Goal

The main goal is to get Kogno adopted as an open-source alternative for developing conversational applications, while also being able to create value-added services around this framework on [kogno.io](http://kogno.io) website.

### Contribute

You can contribute a lot to this project by developing conversational applications with Kogno and in case you find a bug, [please report it](https://github.com/kogno/kogno/issues).

And if you're as passionate about it as we are, come and [code with us on GitHub](https://github.com/kogno/kogno) by fixing bugs, adding more integrations and creating more features.

{% hint style="success" %}

### Demo  App

Learn to develop in Kogno by downloading the source code of a flight booking chatbot developed with this framework at <https://github.com/kogno/travel_chatbot>
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kogno.io/master.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.