1. Home
  2. Docs
  3. Publishers
  4. Basics
  5. Basic Convoworks concepts

Basic Convoworks concepts

We broke the conversation workflow into various components. Each component is defined with a set of editable properties. Properties can be some primitive values, arrays (type multiple actually), or other components (children). When the developer is creating a component, they also have to create the component definition in which they specify what kind of value property they expect. That way GUI can restrict a property to accept a certain type of components (defined by supported interfaces)

There are several main types of components depending on their role in the workflow.

Let’s start with conversation blocks, which represent different steps in our conversation.

It’s all like building a website

It’s a good practice to define a sitemap when you are creating a web application. Each page in the sitemap reveals to the user exactly one main topic. When the user lands on a particular page, it presents them with topic information and possible actions/navigation options they may take from this point.

Let’s consider a simple product catalog. On the home page, we introduce ourselves and we display search box and category list links. The category page has a list of category products, while the product page is displaying full product info.

Well, the same way is when you are building a voice or chatbot app with Convoworks. You define your steps in conversation (sitemap), step is defined with the conversation block and it has one main topic. Actually, it can do several things (like on a webpage: sidebar widgets, additional options, …) but there is one main you will use to name this block and have a nice meaningful sitemap and workflow.

For the sake of simplicity, our initial Convoworks version does not treat a sitemap as a tree, instead, it is just a list of blocks. Our estimate is that in most cases you will have less than a dozen blocks in a workflow and this should not be a problem. Besides that, you can reorder and rename them and get almost similar results. In the future, we plan to support a tree-like structure.

It is interesting to notice that recently published, Google Conversational Actions are also introducing a similar concept. They call it scenes, but they are much less flexible than our Convoworks blocks and they heavily rely on external webhooks.

Single block execution

Here is a small difference between classic webpage and Convoworks blocks. We do not have “links” to move focus on other sitemap pages without any processing. Instead, we have to process every user request and then move focus if it is requested of us.

If you were doing vanilla PHP, you might encounter the pattern which has a PHP chunk at the beginning of the webpage testing if there was a $_POST request and doing some useful things and probably 302 redirect to another page.

This is similar to how the Convoworks blocks are working. A block defines what is presented to the user, so it also defines and knows possible user requests at that stage.

That means that a block has two main parts. One is the initial read phase and it serves for displaying or telling initial information to the user. After that, the system waits for the user’s request. When the user makes a request, the service will try to execute the second, process phase of the current block. It will search among block processors if anyone is willing to accept the current request. When no processor is found, the fallback read stream will be executed. If any processor accepts the request, the service will run it, meaning, it will execute one of its sub-elements flows.

What you can also notice is that we use two main component types: elements and processors serving in read or process workflows. We use green color for marking elements containers and violet for processor containers so the whole usage process should be quite straightforward.

You can read more about blocks here, and more about processors in this guide.


  • Conversation steps are the largest building blocks and you can think of them as pages on a website
  • Elements are sequentially executed components, used in read phases (green)
  • Processors are like routing and one will be executed in process phase (violet), but only if a certain condition is met. Only one process at a time can be executed.