# Blocks

They are methods that receive a block of code as a parameter and must be called within the definition of the method <mark style="color:red;">`blocks()`</mark> in a [<mark style="color:orange;">`Context`</mark>](/contexts.md) class.

All necessary blocks can be added, one for each type of message/event that the context is expecting to receive; where (in most cases) only **one of them will be executed**, if a matches occurs.

## Usage

Below, in the <mark style="color:orange;">`MainContext`</mark> example, we're going to add some blocks and explain how each of them would capture and process an incoming message or event:

* [`intent "greeting"`](/contexts/blocks/intent.md):  A greeting messages, such as <mark style="color:blue;">`"Hello"`</mark> or <mark style="color:blue;">`"Hi"`</mark>. If the intent exists and has been trained on the NLP engine.
* [`postback "get_started"`](/contexts/blocks/postback.md): A click event on a button with a payload with the value <mark style="color:blue;">`"get_started"`</mark> .
* [`regular_expression /([a-z..`](/contexts/blocks/regular_expression.md): Captures the message, if this contains email address, it will return an array with the occurrences found.
* [`any_attachment`](/contexts/blocks/any_attachment.md): Catches any attachment.
* [`keyword`](/contexts/blocks/keyword.md): It will be executed if the incoming message value is <mark style="color:blue;">"stop"</mark>, <mark style="color:blue;">"close"</mark> or <mark style="color:blue;">"quit"</mark>.
* [`everything_else`](/contexts/blocks/everything_else.md): It will be executed in the case of none of the blocks declared above could be executed.

```ruby
class MainContext < Conversation

  def blocks

    intent "greeting" do
      @reply.text "Hello!"
    end

    postback "get_started" do |params|
      @reply.text "Welcome to Kogno framework!"
    end

    regular_expression /([a-zA-Z0-9_\-\.]+)@([a-zA-Z0-9_\-\.]+)\.([a-zA-Z]{2,5})/ do |emails|
      @reply.text "You've sent me these emails #{emails.join(',')}"
    end
    
    any_attachment do |attachment_files|
      @reply.text "You've sent me a file"
    end
    
    keyword ['stop','close','quit'] do
      @reply.text "I'll stop now"
    end
    
    everything_else do
      @reply.text "I can't understand what you say yet."
    end

  end

end
```

{% hint style="info" %}
The order in which these blocks are called is irrelevant. The explanation bellow\..
{% endhint %}

## The Block Matching Process

This process will search for existing matches between **the characteristics of an incoming message or event**, with the **execution criteria of the called blocks** in the active context of the conversation.&#x20;

If the match occurs, the block will be executed and in most cases this process will stop.

{% hint style="success" %}
The matching process is always performed in the same predefined order, this way each block has a different execution priority.
{% endhint %}

## List of Available Blocks

There is a wide variety of blocks, which are going to be listed in order of execution priority:

<table><thead><tr><th width="311.9881497870108">Action</th><th>Definition</th><th>Supported platforms</th></tr></thead><tbody><tr><td><a href="/pages/82GzYLc8T6zE8yALeul6"><code>before_anything</code></a></td><td>If it's called, It will always be executed, at the beginning of the block matching process.</td><td>Messenger, WhatsApp and Telegram</td></tr><tr><td><a href="/pages/-M1XFogDwpfPSik3VBp_"><code>postback</code></a></td><td>A click event in a <a href="/pages/pSatI9sDzM1jmTwkQP1I"><code>button</code></a>, <a href="/pages/lUA76FcljYqvLFiZtaAD"><code>quick_reply</code></a> or <a href="/pages/eJD7aMScdXJVb2JgSTXc"><code>list</code></a>.</td><td>Messenger, WhatsApp and Telegram</td></tr><tr><td><a href="/pages/-M1XFogDwpfPSik3VBp_#any_postback-block"><code>any_postback</code></a></td><td>Catches any <code>postback</code> and returns two parameters. The <code>postback_payload</code> and <code>postback_params</code>.</td><td>Messenger, WhatsApp and Telegram</td></tr><tr><td><a href="/pages/79mamwWyo29lLhcR3AgR"><code>deek_link</code></a></td><td>When a user enters the chat through a link with query string parameters such as <code>ref</code> (for Messenger) or <code>start</code> (for Telegram).</td><td>Messenger and Telegram.</td></tr><tr><td><a href="/pages/zNEVr4w8eWOJiVPkJow8"><code>command</code></a></td><td>Captures a Telegram command. Example: /start</td><td>Telegram</td></tr><tr><td><a href="/pages/-M1XWFa6UKPuKTwDJOGv"><code>any_attachment</code></a></td><td>Captures any attachment like audio, video, image or any file.</td><td>Messenger, WhatsApp and Telegram</td></tr><tr><td><a href="/pages/-M1XXCveED-qEPeGHT_j"><code>regular_expression</code></a></td><td>Captures a message that matches with a given regular expression and returns an array of matches.</td><td>Messenger, WhatsApp and Telegram</td></tr><tr><td><a href="/pages/-M1Xe7xYBdioKVb_OTFP"><code>keyword</code></a></td><td>Captures one or several keywords.</td><td>Messenger, WhatsApp and Telegram</td></tr><tr><td><a href="/pages/p2XbVytZm4NTiVyZUfnI"><code>any_number</code></a></td><td>Capture and return an array of all numeric values ​​in a message</td><td>Messenger, WhatsApp and Telegram</td></tr><tr><td><a href="/pages/F0xAWnFZfFemfGsAhEbW"><code>any_text</code></a></td><td>Capture any text message.</td><td>Messenger, WhatsApp and Telegram</td></tr><tr><td><a href="/pages/-M1XfI6z862RtYW_73xt"><code>intent</code></a></td><td>Capture the provided intent, if it was created and trained in the NLP engine.</td><td>Messenger, WhatsApp and Telegram</td></tr><tr><td><a href="/pages/-M1XfI6z862RtYW_73xt#any_intent-block"><code>any_intent</code></a></td><td>Catches any intent and returns the intent as a parameter.</td><td>Messenger, WhatsApp and Telegram</td></tr><tr><td><a href="/pages/ml7caisa2IG2kNJ0kODq"><code>entity</code></a></td><td>Captures the NLP entity, if it exists and is trained on the NLP engine.</td><td>Messenger, WhatsApp and Telegram</td></tr><tr><td><a href="/pages/-M1XnHZ_rHA9okouJMhr"><code>membership</code></a></td><td>Will be executed when the chatbot has been included or removed from a Telegram group or channel.</td><td>Telegram</td></tr><tr><td><a href="/pages/dGQhmqxqmGo4fCT4H4dj"><code>recurring_notification</code></a></td><td>Will be executed when a user subscribes or unsubscribes from recursive Messenger notifications.</td><td>Messenger</td></tr><tr><td><a href="/pages/7KdFAmeD9vRFSrjpqbDe"><code>everything_else</code></a></td><td>This block will be executed if none of the called blocks in a given context could be executed.</td><td>Messenger, WhatsApp and Telegram</td></tr><tr><td><a href="/pages/p7Na0EYq5I45e4xeEYck"><code>after_all</code></a></td><td>If it is declared, it will always be executed, even if another block has been executed before.</td><td>Messenger, WhatsApp and Telegram</td></tr></tbody></table>

### Execution priority example

To better understand how block matching process works, let's assume the following:

* A user sends a message with the value <mark style="color:blue;">"1"</mark> .
* And the conversation is currently in the context <mark style="color:orange;">`GetNumberContext`</mark>.

```ruby
class GetNumberContext < Conversation

  def blocks

    any_number do |number|
      # This block will not execute, because keyword block 
      # has a higher execution priority. 
      @reply.text "You've send me the number #{number}. Captured by any_number block"
    end
    
    keyword "1" do
      @reply.text "You've send me the number 1. Captured by keyword block"
    end
    
    everything_else do 
      @reply.text "I'm expecting any number to respond something different."
    end
    
  end
  
end
```

As much as `any_number` is called (even first) and its execution condition matches with the message (which is a number), this will not be executed.

<mark style="color:blue;">`keyword "1"`</mark> block will be executed, because it has a higher execution priority than <mark style="color:blue;">`any_number`</mark> block,  and with the execution of the first one, the matching process will be stopped.

## Methods: <mark style="color:orange;">`halt()`</mark> and <mark style="color:orange;">`continue()`</mark>

These methods allows to control the block matching process, they can be called within an action block or in a callback in the [`Conversation`](/conversation.md) class.

### <mark style="color:orange;">`halt()`</mark>

Stops the block matching process.

#### Usage

```ruby
class MainContext < Conversation

  def actions
  
    before_anything do
      @reply.text "This block normaly doesn't stop the block matching process, but in this case it will do"
      halt()
    end
  
  end
  
end
```

### <mark style="color:orange;">`continue()`</mark>

Allows to the block matching process continues when is called in an action block.

#### Usage

Continuing the example in <mark style="color:orange;">`GetNumberContext`</mark>.&#x20;

By calling this method within <mark style="color:blue;">`keyword "1"`</mark> block, <mark style="color:blue;">`any_number`</mark> block will be executed too.

```ruby
class GetNumberContext < Conversation

  def blocks

    any_number do |number|
      # This block will not execute because keyword has will be executed first. 
      @reply.text "You've send me the number #{number}. Captured by any_number block"
    end
    
    keyword "1" do
      @reply.text "You've send me the number 1. Captured by keyword block"
      continue()
    end
    
    everything_else do 
      @reply.text "I'm expecting any number to respond something different."
    end
    
  end
  
end
```


---

# 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/contexts/blocks.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.