TypeScript icon, indicating that this package has built-in type declarations

2.0.3 • Public • Published


such chatblock


Chatbots are just another type of user interface. Nothing more, nothing less.

At least if we think about chatbots as yet-another-UI, we can simplify development in many ways.

Chatblocks allows you to separate presentational layer, bot logic (NLP etc.) and server-side work (configuring webhooks etc). With this approach, learning curve for your team decreases.

Chatblocks treats messages as representation of some state. It does not care about your implementation of webhook, database integration, NLP, or how you deal with payloads.

With our convenient React-style API, you can build your chatbots declaratively, reuse components and integrate with other services (like database or so). We've got ready-made components for Messenger chatbot, but your components can do anything.

It means you can build chatbots nearly as fast as in Chatfuel, for a fraction of the price, but with all elasticity and possibilities of the custom chatbot.

© Szymon Korytnicki,

Sample chatbot

npm install chatblocks

For development purposes, set up Messenger bot the easiest way possible. You have to create your own Facebook app on Developers page. In your webhook, pass events to Chatblocks instance:"/webhook", (req, res) => {
    const data = req.body;
    if (data.object === "page") {
        data.entry.forEach(function (pageEntry) {
            pageEntry.messaging.forEach(function (event) {
                // Receive event
                // Transform each event as you wish
                // Send it to the bot
                    event: event

Well, we should actually create a chatblocks instance:

const Chatblocks = require("chatblocks");
const MainComponent = require("./compiled/blocks/MainComponent");
// pass config in constructor
const Bot = new Chatblocks.Bot({
    facebookAPIVersion: "v2.11",
    pageAccessToken: process.env.pageAccessToken,
    component: MainComponent

and create simple chatblock:

const Chatblocks = require("chatblocks");
const {Block, Text, ButtonTemplate, Button} = Chatblocks;
async function MainComponent(event) {
    return <Block>
        <ButtonTemplate text="How are you?">
            <Button payload="fine">Fine</Button>
            <Button url=""></Button>
module.exports = MainComponent;

This was easy, huh? Let's create another block to react to button click:

const Chatblocks = require("chatblocks");
const {Block, Text, ButtonTemplate, Button} = Chatblocks;
// usually you want to keep one block per file
async function FineBlock(props) {
    return <Text>Test {props.emoji}</Text>
async function MainComponent(event) {
    // event is available in main block only.
    // It can be passed down with props
    if (event.postback && event.postback.payload === "fine") {
        // you can transform event here, or in your webhook
        return <FineBlock emoji="🎉"/>
        // use React-style props to share data
    return <Block>
        <ButtonTemplate text="How are you?">
            <Button payload="fine">Fine</Button>
            <Button url=""></Button>
// Note that it's pure JavaScript. You can perform any operation here (database, whatever)


Chatblocks' JSX has to be compiled to pure JavaScript, which looks like:

async function TextBlock() {
    return await Chatblocks.createElement(Block, null, 
            await Chatblocks.createElement(Text, null, "Hello")

createElement takes function name, props and spread children parameters. Then, chatblocks creates requests to Facebook, to display messages in conversation.

Chatblocks is compiled using transform-react-jsx babel plugin, with custom pragma. Configuration of your build and watch system is up to you. Your .babelrc file can look like:

  "plugins": [
    ["transform-react-jsx", { "pragma": "await Chatblocks.createElement" }]

Then, you can run commands: babel --watch blocks --out-dir build and nodemon app.js assuming app.js is your server file and you have all chatblocks in blocks directory. In app.js, include chatblocks from build directory.

After compilation, you can deploy your bot to Heroku for small price.


Available chatblocks

  • Block
  • Text
  • GenericTemplate
  • ButtonTemplate
  • QuickReply
  • Button
  • MediaTemplate
  • ListTemplate
  • MarkSeen
  • TypingOn
  • TypingOff

Description available in github Wiki.

How to connect multiple fanpages to one webhook?

Create separate Bot instances with different page access tokens.

Chatblock component API

Components are very simple. They are asynchronous functions. Function should return Block, array, or single message.

How to pass the state?

You can process your data in render method or transform it before it reaches your bot (recommended).

Is it production-ready?

It is, and it isn't. There are many features to add and PR's are welcome. Project will have many internal changes in near future, but I don't expect them to break external API. If you are about to build big chatbot (I mean with tens of thousands of daily users), you might want to read chatblocks code and decide yourself about your infrastructure etc.

Why and when should I use it?

  • You build lots of chatbots
  • You want to build your first chatbot
  • You want to optimize developer's work


Take a look at Issues and Projects of github repo.

Sample bot

Generate sample chatbot with chatblocks-cli (npm i -g chatblocks-cli)


Chatblocks is created and maintained by Szymon Korytnicki.


Current Tags

  • Version
    Downloads (Last 7 Days)
    • Tag
  • 2.0.3
    • latest

Version History

Package Sidebar


npm i chatblocks

Weekly Downloads






Unpacked Size

62 kB

Total Files


Last publish


  • skorytnicki