Ultimate Guide to Chatbot Design: A Living Doc

Stefan Kojouharov Stefan Kojouharov, February 26, 2017

After looking at over 15 Billion Messages, talking with many of the top analytics companies, strategic partners, as well as looking at Chatfuel’s internal data we have been able to narrow down the characteristics of good design vs bad design.

Often times bot creators make a number of critical errors when designing their bot. In some cases, they might have a great use case, a good user experience but because of a few design errors, the entire experience falls apart. It can be like having an awesome meal with an old wine. Such nuances, can literally make or break your bot.

After looking at the data, we noticed that it naturally fell into 3 categories: critical problems, things users want, and major areas of opportunity. Features were ranked based on severity and frequency and color coded. Our hope is that we can begin checking off these errors and adding new ones as bot makers read this and improve their bots. For this reason, this will be a living document! You should save and reference this often as it will change, as bots change.

3 Types of Problems

General usability problems fall into 3 categories:

RED = Critical Features your Bot Must Have
Some of these are obvious, however they happen with such frequency that we had no choice but to add them. You should start here and move down the list. If you have any RED/Critical errors, you should address them right away!

Orange = Important Features Users Want
This is the next most important category… These are features users want which will dramatically improve your bots user experience. Look at your data and begin addressing these issues based on your particular situation.

Green = Features Users will Love
This is where you beat your top competitors! The nuance is here and the opportunity to really have a good bot starts here. Your goal, your aim should always be to delight your users.

Evolution of this Document

Over the past year bots have evolved in a major way. Just think about all of the features Facebook alone has added. In the near future many more new features and abilities will be added to bots. As bots evolve and get better over time, this document will also evolve to reflect the reality. We expect that this document will be completely different in a few months.

Leave Comments

This document is a living document and you are welcome to make comments, ask & answer questions and share insights within the doc. If you have any topic suggestions or areas of concern, please do so in the comments below and we will take a look!

This will be an awesome way to learn and interact with the community and meet other bot developers.


Here is the Doc:

Here is the Doc

Version 2 is online (and it’s only the beginning)

Chatfuel Team, December 11, 2015

We’re back in town, stronger than ever! Few days ago, we released the new version of Paquebot. It’s completely updated, with new code in the background. The user interface has completely changed, and allowed us to make it more user friendly, and to create new functionalities in the same time:

Our new commands system allows you to easily create submenus, sub-submenus, sub-sub-sub-menus, etc (sky is the limit), with an easy way to manage content. Also, you can define the behaviour: pagination, random, and more. Go to check it!

Bots were not able to show the previous messages to the previous broadcasts to your users. With Paquebot, it’s now possible: you can now make the history of your bot available to your audience!

You can now schedule broadcasts: it mean you prepare your next messages, choose a date, and then relax. We deal with the rest.

You can now ask questions/feedbacks to your audience, it’s pretty simple and allows you to ask your users for some feedbacks, ideas, new content, answer polls, etc. All the kind of content are allowed!

Some of you still need it, so instead of removing it, we changed the interface, so it’s easier to use! Everything you did is still there, and more simple to administrate!!!

We simply implemented the channels: forward your broadcasts to your channels with Paquebot. Even the ones coming from external services.

We re-implemented the external services to improve your promotion: Boter and the #1 Telegram Store Bot. And we made external services like Zapier, IFTTT easier to use. We have some major partnerships ready to be launched, so stay tuned!

You don’t need to give your token to the other people who help you to administrate your bot anymore. Simply invite them as managers.

You can now make money with your bot! Follow the instructions on your bots.

Your bots now have an administration interface translated in 6 languages, and more are coming! Crazy, huh? Our translation team is amazing and added the translations as soon as we created the new functionnalities!

Few weeks ago already, we changed the broadcasting system. It’s definitely fast and stable, and the only restriction are Telegram limits! And we know how to deal with growth, as our service is optimized for popular bots for a while.

We also improved different small stuff: statistics of your bot, keyboard management, Zapier integration, etc. And all the existing functionalities have a new interface with a simple navigation.



As we told you: it’s only the beginning. Now that we have a great service, it’s also an amazing tool where we can easily deploy new updates. It mean we will make more, and give you more, faster than ever! We have many ideas ready to be implemented on your bots ?

How to choose your media?

Chatfuel Team, October 12, 2015

Telegram just launched their new feature: Channels. It’s a good thing that will help some of you to get an audience on that specific tool. We want you to know what are the real differences before making a choice, as it’s difficult to change the media when your audience is huge.

Maintenance is over

Chatfuel Team, September 6, 2015

Finally, everything is ready!

Two days ago, we made a maintenance on all your bots: bots receiving more than 30 requests per second are now able to work correctly without reaching the Telegram limit! They are not slowing down the system anymore ???

Yesterday, we made a maintenance on @Paquebot too (the bot that install Paquebot on your bots), and improved it: keyboard, friendly commands and direct install by forwarding a token! ?

Today, Telegram made an update (but we did nothing), where about 20% of the bots took more than 12 hours to be back. @Paquebot was unfortunately one of them, and our only solution was to wait for Telegram to solve the problem on their side. ? (Note: If your bot is still offline, try to /revoke your token with the @BotFather, and forward the new token to @Paquebot)

The situation is now stable, Paquebot is faster than ever! Enjoy your amazing bots!!

Tomorrow, we will add small stuff that most of you asked during the last weeks: remove start and stop buttons, display bot administrators, etc. Bigger updates will arrive during the next days!!! Your bots will stay online during that maintenance ?

Get more subscribers with Boter

Chatfuel Team, August 31, 2015

We have a new partner:, the first promotion platform for Telegram bots! The concept is simple: you collect points by promoting other bots, and use your points to be promoted on other bots. ?

They just launched their services and Paquebot was lucky enough to test it with some accounts, allowing us to implement it on your bots! ?

To use it, it’s simple:
1) open your bot, type /boter and follow the instructions
2) create your own promotion
3) share other bots campaigns to get points
4) other bots will share your promotion, using your points.
5) repeat points 3 and 4

If you have any feedback about boter please contact them:

We wish you a lot of subscribers!!! ??

IFTTT + Botan support

Chatfuel Team, August 12, 2015

Many news today!!!

We’re currently testing our new integration of IFTTT (if that then that). Some of you maybe already use the similar service “Zapier”, which also allows you to automate some tasks. And IFTTT is free.
Here are some recipes, you can use them:

Do you want to understand your audience? It’s easy with Botan, created by Yandex. You’ll know a lot of interesting stuff about your users: what they do, what they type, who is connected, and many other informations!
Open your bots and type /botan ?

Have fun!!!

The new mailer is ready

Chatfuel Team, August 10, 2015

?? The new version of our mail service is available, way faster than the previous versions.

We took that opportunity to improve our connexion with the database, and to separate the servers receiving your commands and the broadcasting server: the emails are faster, and now the commands quickly get answers again!!! ?

We already sent more updates than we ever did (almost 10 millions today), and everything runs fast! This diagram will help you to understand how it works now: /attachement_mailer ?

You can continue the /paquebot command as usual ? Also, we now show you a preview of what will be sent to your users.

And finally: bots are back in the groups. The only difference is that they only answer to commands starting with a slash (“/”) ? Keyboards are not displayed in groups.

Let’s broadcast everywhere ?

Custom keyboards, new options

Chatfuel Team, August 7, 2015

Now that you have custom commands, you can add custom keyboards, to receive specific answers from your users! ?

For example, on our bot @NewsPaquebot, there is now a command called “Read tutorials”. We can now ask users to answer me which tutorial they want to see, between “Custom commands” and “Auto-updates”. To do so, it is simple, we have to to send one command button” on each line:

> /commands keyboard Read tutorials
> Auto-updates
> Custom commands

The applications are multiples: create sub menus, suggest to load an other random picture, make a step by step tutorial, make a podcast with links to the previous and next episodes. ?

Don’t forget to create all the answers to your texts ?

Enjoy it!

Custom commands 2.0

Chatfuel Team, August 6, 2015

We just enabled the /commands tool on all your bots! It will allow you to create bots that are able to answer directly to your users ?Now let’s check what is new:

You can add commands based on everything a keyboard can type: “/contact”, “⚓️”, “Hello”, “Pictures ?” are all valid commands!

The bots are now able to answer in every format supported by Telegram: pictures, videos, audio, mp3, locations, text, or every kind of file.

You can add as many answers as you want to your bots: that mean that when your bot needs to reply to a request, he will choose one of the answers. And you can mix the file types (sometimes answer text, sometimes audio, sometimes pictures, for example),

The commands don’t require to be all displayed on the keyboard anymore. You can hide the one you don’t want to display, and only show the interesting one!

Start to add answer, then upload your photo album, the music album you just made, and then exit: everything is uploaded in one command!

Here is a new tutorial that explain step by step how to use it:

Have fun, and make your feedbacks here: ?

Enjoy it!

The Paquebot Team ⚓

Enable or disable your keyboards

Chatfuel Team, August 4, 2015

Small improvement requested by some of you: the /showkeyboard command, which allows you to enable or disable the display of commands keyboard on your bots. ☎️?

Use “/showkeyboard yes” or “/showkeyboard no”. For your information, the commands keyboard displays the “/start” and “/stop” commands, but also the one you can create with “/setabout” and “/setcommand” ?

Something bigger will arrive soon!