How to create a simple Telegram bot with Voiceflow

Telegram is becoming one of the most important messaging applications in the world today. The free and open-source instant messaging software offers many useful features that make it suitable for implementing sophisticated bots that can assist us in a variety of ways.

Since its inception, there have been several ways to develop bots for Telegram, however only a has been focused on CxD and providing rich conversational experiences. With Voiceflow's new Dialog Manager API, the conversation design platform stands as the best choice for designing, developing, and integrating a Telegram chatbot.


Here is what you'll need to create your very own Telegram bot using Voiceflow

  1. Telegram Account
  2. Voiceflow Account
  3. Visual Studio Code


In this example, we are going to use the Telegraf library for NodeJS projects to interact with our Telegram Bot. As mentioned above, every user interaction in the Telegram bot will be sent to Voiceflow using our Dialog Manager API.

The architecture used to create a Voiceflow Telegram Bot
The architecture used to create this experience

Create your own bot with BotFather

First, we need to use botfather to create our very own bot inside Telegram. BotFather allows you to create new bot accounts and manage existing ones in a few simple clicks. To start the process of creating your bot, you just need to talk to the botfather while following the steps outlined below.

To open a chat with botfather, click on the "start" button.

We'll need to create a new bot by clicking /newbot command. Next, you can name your bot. In this example, we have named ours "Voiceflow bot".

It's that easy. The Telegram setup is now complete! Remember to add your Telegram token to your {% c-line %}.env file{% c-line-end %} in the property {% c-line %}TELEGRAM_TOKEN{% c-line-end %}.

Setting up the project

Install and run the project:

1. Clone this repo:

{% c-line %}git clone <>{% c-line-end %}

2. Install dependencies:

{% c-line %}yarn install{% c-line-end %}

3. Launch project:

{% c-line %}yarn start{% c-line-end %}

Writing the bot’s code

Telegraf setup

We can create bot by the following code lines:

Writing the Telegram Bot's code

Voiceflow setup

NOTE: It's important to note that you will need to create a General Project type on Voiceflow for this experience to work.

Now, let's implement the Voiceflow client to work with Voiceflow's cloud using its Dialog Manager API.

Implementing the Voiceflow client

The {% c-line %}getclient(){% c-line-end %} function calls the {% c-line %}DialogManagerApi.getInstance{% c-line-end %} a REST API client that will interact directly with the Dialog Manager API.

As you can see there are some values that will be added to our {% c-line %}.env{% c-line-end %} file. Let's explain how to obtain those variables.

1. Version ID

To obtain your VersionID you have to go to your Voiceflow Project:

Obtain your VersionID in Voiceflow

Then copy the {% c-line %}VOICEFLOW_VERSION_ID{% c-line-END %} from the URL in your address bar. When you are inside a Voiceflow project, your address bar should have a URL of the form: 

{% c-line %}{VOICEFLOW_VERSION_ID}/...{% c-line-end %}

2. apiKey

To obtain the API Key we have to go to our workspace where we have created our General Project. After this, head to workplace settings and click on the developer tab.

You can find the API key in workplace settings

Then we have to click to {% c-line %}Create new API Key{% c-line-end %} button to create a new one:

Give your API key a name

You need to add a name to the new API Key, for example, {% c-line %}telegram-bot{% c-line-end %}. Once we have filled it, we can click the {% c-line %}Confirm{% c-line-end %} button:

Your new API key is then stored in your project

Finally, we have to add these variables to our final {% c-line %}.env file{% c-line-end %}. It should look like this:

Adding variables to our final .env file

Everything is ready. Let's continue with our Telegram bot code. Let's replace the standard start replay for the one below, getting the correct replay from Voiceflow:

Then we replace the {% c-line %}hi{% c-line-end %} utterance for a regex like {% c-line %}(.+){% c-line-end %}. This means that the bot will hear for everything. All the text received we will pass directly to Voiceflow and we manage the state of the conversation: if it is ended or if it is not ended yet:

The response method is in charge of sending the user input in Telegram to Voiceflow using the runtime client SDK. This allows us to process the response:

In the example above you'll notice different types of responses including {% c-line %}SPEAK{% c-line-end %}, {% c-line %}VISUAL{% c-line-end %} and {% c-line %}AUDIO{% c-line-end %}responses.

Running the Telegram Bot

Telegram bot connected to Voiceflow
You're all set to test this experience in Telegram

Help us help you

Interested in helping us improve this experience? You can submit a PR by following the steps below.

  1. Fork this repo
  2. Clone your fork
  3. Code
  4. 🤓
  5. Test your changes
  6. Submit a PR!



As you can see, with just 60 lines of code you can quickly bring your chat experiences to life. I hope this gives you a better understanding of how you can use Voicefow to bring conversational experiences into your very own interfaces and products. Happy coding!

Voiceflow is Hiring! 📢

Voiceflow is looking for more people who are excited to build the future of interactive conversations. You can visit this link to apply.

Harness the power of OpenAI’s Whisper model for ASR with Voiceflow

No items found.