DEV Community: tjtanjin

Unveiling React ChatBotify v2: Plugins, Themes, Hooks, Events and More

tjtanjin — Tue, 17 Jun 2025 17:18:04 +0000

Introduction

Chatbots have become indispensable tools for seeking meaningful, efficient customer interactions. However, creating sophisticated chatbots traditionally required complex development efforts and challenging integrations. About a year ago, React ChatBotify v2 commenced its beta phase, gathering invaluable insights from developers and users to gear up towards a stable release.

Earlier last week, React ChatBotify v2 launched its stable release - packed with advanced plugin integrations, community themes, chatbot events, intuitive hooks, and extensive customization options. Whether you've followed along since the beta announcement or you're exploring React ChatBotify for the first time, this stable release offers transformative capabilities for everyone.

In the beta release article, we covered some of the breaking changes introduced with v2. If you're interested, you'll find the full list of changes in the migration guide helpful. In this article, we'll focus on some of the standout enhancements that will supercharge your chatbot development!

Plugins: Extend & Modify Functionalities

In v1, it was incredibly tedious to extend the chatbot with your own custom features, as functionalities of the chatbot were not exposed for integration. This limitation significantly hindered the ability for developers to create reusable behaviors that could be easily shared across projects - or even with others.

Enter plugins, a powerful feature introduced in v2 which provided a straightforward and convenient approach for developers to extend or even modify existing functionalities of the chatbot in the form of plug-and-play solutions. Built atop the hooks and events API, there now exists countless plugins possibilities! In fact, alongside this v2 release, several official plugins have been released:

LLM Connector Plugin: A generic connector for integrating Large Language Models (LLMs) such as OpenAI ChatGPT & Google Gemini into your chatbot!
Markdown Renderer Plugin: A simple plugin for beautifully rendering markdown formatted messages in your chatbot!
HTML Renderer Plugin: A simple plugin for beautifully rendering html markup formatted messages in your chatbot!
Input Validator: A lightweight plugin to validate user input with visual feedback in your chatbot!

Supporting the plugins feature was no trivial effort, with the work on it leading to the development of the hooks and events API - both of which are also significant enhancements added in v2.

Themes: Styling With Ease

First introduced in the initial v2 beta release, the usage of themes has largely remained unchanged during the beta period - that is, developers will still browse the themes gallery to pick out and apply suitable templates. However, the theme creation process has been gradually improved over time, with an upcoming command-line tool project aimed at bringing the developer experience up another notch.

Hooks: External Control Made Simple

Prior to the introduction of hooks, there was a very limited surface area for developers to directly effect changes on the chatbot externally. For example, it wasn't possible to toggle the chatbot audio (without significant "hacks") via a button that resided outside of the chatbot. This created friction for developers trying to build cohesive UI experiences that extended beyond the chatbot window.

The addition of hooks in React ChatBotify v2 changes the game. With over a dozen specialized hooks available, developers now have direct access to the internal state and behavior of the chatbot. For example, the useAudio hook provides the toggleAudio function which can be easily used in a custom button as shown below:

import { useAudio } from "react-chatbotify";

const CustomButton = () => {
  const { toggleAudio } = useAudio();

  return (
    <button onClick={toggleAudio}></button>
  )
};

This opens the door to fully customized, highly interactive applications where the chatbot is just one of many orchestrated parts.

Events: Listen and React in Real-Time

In v1, there was virtually no visibility into what the chatbot was doing. Developers had no built-in way to know when the chatbot was sending a message, transitioning paths, or toggling notifications. This made it extremely difficult - if not impossible, to build external logic or integrates with other parts of the website.

With the extensive event system provided in v2, developers can listen to events ranging from message injections, to chatbot toggles, to user input submissions. It enables developers to build rich extensions (such as in the form of plugins) around the chatbot's behavior - all without having to hack around the internals.

Upcoming Roadmap

While v2 already packs numerous powerful features, the journey toward enhancing the chatbot development experience continues. Several exciting improvements are already underway, promising even greater ease and capability.

Command-line Tool

Currently, React ChatBotify primarily caters to the React Ecosystem. While it's possible for developers to produce standalone builds for integration outside of React, there is no official streamlined approach, making the process relatively cumbersome. To address this, an upcoming command-line tool is in the works, which aims to deliver the following features:

Scaffold Themes: Easily create new themes using pre-configured templates.
Scaffold Plugins: Effortlessly set up plugin projects without manually cloning repositories.
Generate Standalone Widgets: Quickly build chatbot widgets ready for embedding in environments outside of React, greatly expanding chatbot deployment scenarios.

By simplifying these processes, the tool aims to reduce friction and improve development workflows, enabling developers to focus more on creativity and innovation!

Chat Analytics Plugin

Understanding chatbot interactions is crucial for improving both conversation design and the overall user experience. Currently, it requires considerable manual setup and integrations to gain insights into chatbot usage patterns. An upcoming chat analytics plugin is in the works, which aims to solve this problem by offering plug-and-play analytics, right out of the box.

Live Chat Plugin

One of the most frequently requested features has been the ability to seamlessly transition from automated conversations to human support. While still in the early ideation phase, an upcoming Live Chat Plugin is being explored as a solution to bridge that gap.

The goal is to allow real-time, human-in-the-loop interactions to complement the chatbot experience. This would provide the means to escalate conversations when needed - without disrupting the overall flow.

Conclusion

To round off, React ChatBotify v2 represents a major leap forward in simplifying and empowering chatbot development. With its robust plugin system, flexible theming, extensive hooks and event APIs, and a growing ecosystem of resources, developers now have unprecedented control over how they build and customize their chatbot experiences.

Yet, this is only the beginning. With the items in the upcoming roadmap, React ChatBotify is evolving into a full-featured, developer-friendly platform that adapts to a wide range of use cases, from simple customer support bots to complex, deeply integrated conversational interfaces.

Whether you're just getting started or looking to take your chatbot to the next level, React ChatBotify v2 opens up a world of possibilities!

Introducing the LLM Connector Plugin: A Simpler Way to Build AI Chatbots with React ChatBotify

tjtanjin — Thu, 15 May 2025 18:32:51 +0000

Introduction

If you've ever built an AI chatbot for a website, you know that integrating a large language model (LLM) often means wiring up API calls, managing async flow, and writing custom backend logic - all before your bot can even say "Hello World".

Over a year ago, I wrote about how to integrate LLMs with React ChatBotify, which involves a manual method that worked, but required a fair bit of glue code and configuration. While React ChatBotify has made it easier to build a chatbot UI, LLM integration still demanded work that could quickly grow in complexity.

That's exactly the pain point the LLM Connector Plugin is designed to solve - by providing out-of-the-box LLM integrations.

With the LLM Connector Plugin, you can eliminate boilerplate, abstract away complexity, and get your chatbot talking to an LLM in minutes. In this post, I'll walk you through what the plugin does, how to install it, and how it makes building smart, conversational UIs with React ChatBotify not only simpler, but faster.

What is the LLM Connector Plugin?

The LLM Connector Plugin is an abstraction layer to streamline LLM integrations within React ChatBotify. It enables developers to connect React ChatBotify to Large Language Model Providers such as OpenAI and Google Gemini with ease. It even ships with integrations with Browser models, achievable with an extremely simple setup:

import ChatBot from "react-chatbotify";
import LlmConnector, { WebLlmProvider } from "@rcb-plugins/llm-connector";

const MyComponent = () => {
  const flow = {
    start: {
      llmConnector: {
        initialMessage: "Ask away!",
        provider: new WebLlmProvider({
            model: 'Qwen2-0.5B-Instruct-q4f16_1-MLC',
        }),
      }
    }
  }
  return (
    <ChatBot plugins=[LlmConnector()]/>
  );
};

As can be seen from the snippet above, by providing a simple declarative interface, the plugin lets you focus on your bot's behavior and flow. This is in contrast to the past where you'd have to manually handle API calls and message formatting. The result of the above snippet?

Despite how simple it looks, under the hood, the plugin does a lot of heavy lifting - such as handling streaming of responses, syncing of audio, managing typing indicators and more! Ok so we saw a short snippet, but what did it contain and how exactly do we use the plugin? Let's find out!

Installation and Setup

The LLM Connector Plugin is available on NPM and can be installed via the following command:

npm install @rcb-plugins/llm-connector

Take note that the plugin is only compatible with React ChatBotify versions later than v2.0.0-beta.34!

After installing the plugin, you can import and initialize it in your project as follows:

import ChatBot from "react-chatbotify";
import LlmConnector from "@rcb-plugins/llm-connector";

const MyComponent = () => {
  return (
    <ChatBot plugins=[LlmConnector()]/>
  );
};

We'll next create a block dedicated to handling LLM conversations and proceed to add the llmConnector attribute to it:

import ChatBot from "react-chatbotify";
import LlmConnector from "@rcb-plugins/llm-connector";

const MyComponent = () => {
  const flow = {
    start: {
      llmConnector: {}
    }
  }
  return (
    <ChatBot plugins=[LlmConnector()]/>
  );
};

Hmmm, nothing's happening. But don't fret, we're almost there! We're now just missing a LLM Provider to have your chatbot start talking. We'll look at how that's done through a minimal example next!

A Minimal Example

In this minimal example, we'll import and use the WebLlmProvider, which is provided by default with the plugin. Note that the plugin ships with 3 built-in providers (OpenAI, Gemini and WebLlm), which serve to cover the vast majority of common use cases. Let's go ahead and import the WebLlmProvider as such and initialize it within the provider property inside llmConnector:

import ChatBot from "react-chatbotify";
import LlmConnector, { WebLlmProvider } from "@rcb-plugins/llm-connector";

const MyComponent = () => {
  const flow = {
    start: {
      llmConnector: {
        provider: new WebLlmProvider({
            model: 'Qwen2-0.5B-Instruct-q4f16_1-MLC',
        }),
      }
    }
  }
  return (
    <ChatBot plugins=[LlmConnector()]/>
  );
};

Notice that when we initialized the WebLlmProvider, we also passed in a minimal set of configurations which included the model. In this case, we tried it with Qwen2–0.5B-Instruct-q4f16_1-MLC but feel free to test it with other models as well (bear in mind the size of the model if you're running it in your browser)!

It is important to note that configurations for providers can actually vary greatly. For the configuration guides of the default providers, you may look here.

The React ChatBotify documentation website also comes with several live examples demonstrating the default providers at work. You are strongly encouraged to check them out:

Creating Your Own Provider

While the plugin offers default providers to cater for the vast majority of common use cases, it's understandable that advanced users may wish to customize their LLM solutions. With that in mind, the plugin is designed to allow users to easily provide their own custom providers!

Developers looking to create custom providers can do so by simply importing and implementing the Provider interface. The only method enforced by the interface is sendMessage, which returns an AsyncGenerator<string> for the LlmConnector Plugin to consume. A minimal example of a custom provider is shown below:

import ChatBot from "react-chatbotify";
import { Provider } from "@rcb-plugins/llm-connector";

class MyCustomProvider implements Provider {
  /**
   * Streams or batch-calls Openai and yields each chunk (or the full text).
   *
   * @param messages  messages to include in the request
   * @param stream    if true, yields each token as it arrives; if false, yields one full response
   */
   public async *sendMessages(messages: Message[]): AsyncGenerator<string> {
     // obviously we should do something with the messages (e.g. call a proxy) but this is just an example
     yield "Hello World!";
   }
}

If you're looking to create your own provider, consider referencing the implementations for the default providers.

Conclusion

I hope this article has demonstrated how much simpler and faster it is now to integrate LLMs with React ChatBotify.

In the next few articles, we'll dive into more detailed integrations with each of the default providers, including how we can end an LLM conversation. If you're keen to dive deeper, do keep a lookout!

Finally, if you have any feedback, suggestions, or thoughts about what's shared, feel free to leave a comment or reach out on discord. Thank you for reading and see you around! 😊

A Hacktoberfest 2024 Journey: Insights from a First-Time Project Maintainer

tjtanjin — Mon, 04 Nov 2024 00:29:48 +0000

This is a submission for the 2024 Hacktoberfest Writing challenge: Maintainer Experience

Introduction

Maintaining an open-source project is incredibly fulfilling yet often exhausting. Since late July this year, I've been knee-deep in preparations for the v2 stable release for my open-source library, React ChatBotify. It is a time-consuming process, and more than once, I found myself thinking how nice it’d be if there were extra hands around to help with the efforts 😪.

Hacktoberfest, a month-long open-source event held every October seemed like it could provide exactly that. Hosted by DigitalOcean, Hacktoberfest encourages developers from around the world to contribute to open-source projects in exchange for learning, community building, and digital rewards. It was a tempting opportunity to bring in fresh contributors, yet committing to it felt daunting due to increased responsibilities. Add on to that the "maintainer's nightmare" stories I'd read about having to deal with spammy PRs arising from the event, and you might understand why I was rather apprehensive 😣.

However, as the month of October kicked off, I noticed an increase in activity on Hacktoberfest's discord server and frankly, the excitement within was hard to ignore. Although I did not plan to participate initially, I felt an urge to dive in and in the spur of a moment, I opened up my project for Hacktoberfest, eager, though anxious to see what the month would bring.

Preparation & Setup

Including a project for Hacktoberfest was surprisingly straightforward. To participate, I only needed to add the hacktoberfest topic to my repository. While the Hacktoberfest website suggested several other best practices for maintainers, having the hacktoberfest topic was technically sufficient to have my project included.

That said, I also spent some time updating the project README, developer guide, as well as contribution guidelines to ensure that they contained the most updated information. Clarity was made a high priority, so that developers can better understand what they're getting into and how to get started.

Troublesome as it may seem, I would eventually learn that this was actually the easiest part 😂. From creating issues, to managing PRs, each of them presented a unique set of problems that ranged from interesting to frustrating. Let's look back on them together in the rest of this article!

Creation of Issues

Initially, I had thought that the creation of issues would be relatively quick and simple. After all, I just had to create issues and tag them with a hacktoberfest label right? However, it proved to be more complex than expected. You see, when trying to create issues, a couple of important questions came to mind:

Who am I catering the issues for?
Which areas does the project need help in?
What kind of issues to create?
How can I help people ease into the issues?

If I wanted to create issues for my project that others would be keen to work on, I had to answer these questions.

An Initial Exploration

Since I was already in the Hacktoberfest Discord, I looked within for answers. Based on a couple days of observations, I gathered that there were a significant number of first-timers who are keen to dip into open source work. With that in mind, I decided to make most of my issues beginner-friendly. It was after all my first time participating in Hacktoberfest as well 😝.

Scoping the Issues

Due to the ongoing v2 changes, significant code rewrites had occurred across the entire project. While there was a basic integration test in place to catch the occasional obvious bugs, it is far from enough with the scale of features introduced in v2. Up till then, I had never properly put in the time and effort to setup unit testing (which would undoubtedly improve the reliability of my project).

With that in mind, scoping my issues to writing tests sounded like an excellent idea. It's a win-win-win situation for aspiring first-time open-source contributors, the React ChatBotify project, and definitely for myself 😝.

Firstly, writing tests is a valuable skill for developers to pick up. It may also comes across as less daunting for first-timers, since tests do not directly interfere with the core logic of the library. Secondly, the project itself stands to benefit from having more robust test cases. This is a particularly apt time as well given the massive rewrite that came along with v2. Lastly, I appreciate the help with writing tests, which gave me more time and confidence to work on the v2 features 😊.

Lowering the Barrier of Entry

With that said, I still had concerns about the quality of the tests that would be written, and acknowledged that beginners may benefit more from a little hand-holding or reference. It wasn't like I could just create the issues and then magically, people come along and the tests would be perfectly created (I wish 😅).

So, what better way than to provide examples within the codebase itself? The project was already neatly structured into components, hooks, services etc. For testing, it made sense to mirror this structure. Hence, before even creating the issues, I wrote several unit tests for a couple of internal hooks. These test cases were then referenced and used as examples in the issues I created for writing test cases!

Now imagine wanting to contribute to a project and being given the task details as below:

It's short and sweet, with appropriate links to the resources that you will need. Hopefully, you'll agree with me that it's pretty welcoming to beginners 😋.

A Continuous Process

Much to my surprise, the issues received a lot of attention, so much so they were being assigned out much faster than I had anticipated. Thus, throughout the month of October, I found myself continuously creating a bunch of fresh issues every few days to keep up with the growth in interest. I know what you may be thinking, but I wasn't creating issues unnecessarily 😐.

In fact, the constant creation of issues was very much possible because the project itself had a lot of components, hooks and services that could be tested individually. As part of the v2 rewrite, majority of the core library logic had been broken down into smaller, more manageable parts which facilitated easier testing.

Stale Issues

Of course, not everything goes well. Some issues became stale overtime either due to a lack of interest, or that their assignees had gone missing-in-action (MIA) 😰. This was not unexpected, though on some occasions, dropping a friendly ping to the assignees brought them back into action 😝.

All in all, by keeping issues beginner-friendly, scoped to testing and with proper references, it worked out pretty well! That said, if given a chance again, I would probably have experimented with creating a handful of challenging issues to cater for different skill levels. But hey, there's always next year!

Management of Pull Requests

Before even the first pull request came in, I knew that the management of pull requests was going to consume a significant amount of time - and it did. Out of all work involved for Hacktoberfest, reviewing pull requests took up the most time and because of that, I actually had to calibrate my approach towards managing pull requests.

A Balanced Approach

Issues only tell half the story. For every issue created, I had to be mentally prepared that there'd be one (or perhaps even more than one) pull request (PR) I have to review. However, unlike issues which were created with a structured template I curated, the solutions that came with pull requests took on various forms. This is understandable, as developers tend to have different approaches and preferences when tackling problems.

Now, there're 2 ways I could do this. One, I could be very picky, insisting that everyone write the same way and take the same approach. Or two, I could focus on the quality of the test cases themselves and close an eye to other minor differences. Some of you may be wondering why not combine both options - i.e. be picky, and focus on the quality of the test cases as well.

That's not impossible, but in the interest of time and resources, I went with an approach to strike a balance. Given that Hacktoberfest was a timed-event with many first-timers, the value of the latter felt greater. After all, it doesn't really help my case if the test cases were poorly designed. As I already had test cases for reference, I was also not expecting approaches and code styles to stray too far off. Hence, unless there was something drastically different, I didn't nitpick too hard.

Resolving Conflicts

Occasionally, multiple PRs are opened for the same issue. This happens when developers directly open a PR without first expressing interest and being assigned an issue. When faced with such a situation, I fell back to the contribution guidelines that I had clearly written:

Ultimately, it is only fair that the assigned developer who followed the guidelines gets priority in having the PR accepted. That said, I also did not want the other party to feel unappreciated. Oftentimes, I would facilitate discussions between the 2 developers to decide how best to proceed. Sometimes, the assigned developers acknowledges that he/she has not started on the issue and was willing to pass it up. Other times, the developer who opened a PR without being assigned happily took up other issues.

I was certainly lucky that all conflicts were resolved amicably, as the developers I worked with were very understanding. I greatly appreciate their help in maintaining a safe environment for the project 😊.

Stale Pull Requests

Like issues, there were also a handful of stale PRs. This happens when a PR is reviewed but there was no subsequent follow-up from the developer. For this Hacktoberfest, there were only 2 of such cases and thankfully, other developers came along to pick up the associated issues!

With that said, stale pull requests weren't much of a problem. In fact, at the end of the event, I was surprised to see the number of pull requests merged. Take a look below!

Before Hacktoberfest:

After Hacktoberfest:

A whopping 56 merged pull requests arising from the event, amazing isn't it?

Key Takeaways & Lessons Learned

Having just been through my first Hacktoberfest event, I must say it has far exceeded my expectations in terms of the value that it brings. I would never have imagined the overwhelming interests, as well as the quality of improvements that would be made to my project. Numbers don't lie - the contributors to my project has more than doubled in just a month:

Reflecting on this entire experience, I believe there a few key areas that contributed to the overall very positive experience.

Clear Contribution Guidelines

Having a clear contribution guideline is extremely important. Imagine trying to learn a game, but being given a poorly written tutorial - or worse, not even finding one. Would you still continue? Maybe, maybe not - but why take the chances?

The same applies when developers search for projects to contribute to. A clear contribution guideline lets developers have clarity on where and how to get started. For React ChatBotify, I freshened up the contribution guidelines for Hacktoberfest alongside the project README and developer guide. They most definitely have a part to play in easing developers into the project!

Quality of Issues

As you may be able to tell from what I've shared, a great amount of effort went into ensuring that issues were well curated. This meant that the issues created contained the necessary information and were of a reasonable quality.

This was important, not just for forming a solid first-impression. It actually gives developers the clarity and confidence required to tackle the issues. As a bonus, it also helps lighten the load on my end as developers are less likely to have to seek clarifications if the issues contain all the relevant information 😊.

Community Engagement

In any collaborative setting, engagement is, if not the highest, certainly one of my top priorities. For a project to thrive, the sense of community is essential — and Hacktoberfest was no exception. I made a point to respond to issues/PRs as fast as I could and provided help to the best of my ability.

This not only kept developers engaged, but also offered them the assurance that they were contributing to an actively maintained project. More importantly, they know that they are not working on issues alone.

You Define Your Own Experience

Despite best efforts, not all things will go as planned. As project maintainers, it’s easy to get caught up in tracking project metrics — like how many issues were assigned or PRs merged.

However, it's not often that we look within ourselves, and consider realistically what we think will come out of the experience. For me, I approached Hacktoberfest with minimal expectations, focusing instead on the process itself. In the end, I was pleasantly surprised, gaining far more than I anticipated and it turned out to be a very fulfilling experience 😊!

Conclusion

Looking back, Hacktoberfest went pass in a flash. It's heartening to see that even now, after the event has ended, a few dedicated developers are still working on open issues and pull requests. Prior to the event, the "horror stories" of spam PRs had me really concerned but as it turns out, the event went much better than I expected.

Hopefully, with the insights and lessons learned from this year, next year's experience will be even more rewarding! As a personal goal, I hope to introduce more challenging and a larger variety of issues next Hacktoberfest. For now, it's a wrap 😊!

Behind the Scenes: Solutioning for React ChatBotify's Themes

tjtanjin — Wed, 31 Jul 2024 14:58:48 +0000

Introduction

If you've ever developed or interacted with chatbots on a website, you'll know that their aesthetics play a crucial role in enhancing the overall visual appeal of the site. However, theming isn't just about making things pretty; it's also about crafting a seamless and engaging user experience. In the past, customising chatbots with React ChatBotify required a fair bit of effort. Users had to style everything from the base template, which could be very time-consuming, especially when pursuing a drastically different design.

With this in mind, the idea for a theming feature emerged to streamline the customisation process. The goal - to provide users with a variety of ready-to-use themes that could be easily applied and refined to match specific requirements. This article takes you behind the scenes on the solutioning journey, where we explore 3 potential approaches to implementing themes in React ChatBotify. We will walk through the factors for consideration, analyse the pros and cons of each approach, before committing to a final solution.

The Problem

Prior to the introduction of themes in React ChatBotify, customising chatbots could involve a highly manual and tedious process. Users started off with a base template, which essentially consisted of the default settings and styles that came with the chatbot.

To achieve a unique look or to complement their websites, developers may have to comb through the documentation to meticulously override default styles. For example, let's consider the stark contrast between the base appearance and a more sophisticated "Terminal" theme:

To transition from the base appearance to the "Terminal" theme shown above, it involved numerous changes across 3 files (settings.json, styles.json & styles.css). Let us just take a quick look at the contents of the styles.json file:

{
  "headerStyle": {
    "backgroundImage": "linear-gradient(to right, #2c2c2a, #2c2c2a)",
    "alignItems": "center",
    "fontSize": "14px",
    "border": 0
  },
  "botBubbleStyle": {
    "textAlign": "left",
    "border": 0,
    "backgroundColor": "#070707",
    "color": "rgba(255, 255, 255, 0.87)",
    "padding": "10px 15px",
    "maxWidth": "none",
    "margin": 0,
    "fontSize": "14px"
  },
  "userBubbleStyle": {
    "textAlign": "left",
    "border": 0,
    "backgroundColor": "#070707",
    "color": "rgba(255, 255, 255, 0.87)",
    "padding": "10px 15px",
    "maxWidth": "none",
    "margin": 0,
    "fontSize": "14px"
  },
  "botOptionStyle": {
    "color": "rgba(255, 255, 255, 0.87)",
    "backgroundColor": "#070707",
    "padding": 0,
    "border": 0,
    "fontSize": "14px"
  },
  "botOptionHoveredStyle": {
    "color": "rgba(255, 255, 255, 0.87)",
    "textDecoration": "underline",
    "backgroundColor": "#070707",
    "padding": 0,
    "border": 0,
    "transition": "none",
    "fontSize": "14px"
  },
  "chatInputContainerStyle": {
    "borderTop": 0,
    "backgroundColor": "transparent"
  },
  "chatInputAreaStyle": {
    "minHeight": 0,
    "border": 0,
    "padding": "8px 15px",
    "backgroundColor": "#070707",
    "color": "rgba(255, 255, 255, 0.87)",
    "fontSize": "14px"
  },
  "sendButtonStyle": {
    "display": "none"
  },
  "chatWindowStyle": {
    "height": "490px",
    "paddingBottom": "10px",
    "backgroundColor": "#070707",
    "border": "1px solid grey"
  },
  "bodyStyle": {
    "paddingBottom": 0,
    "backgroundColor": "#070707"
  },
  "tooltipStyle": {
    "padding": "8px 12px",
    "borderRadius": "15px",
    "color": "rgba(255, 255, 255, 0.87)"
  },
  "chatHistoryLineBreakStyle": {
    "color": "rgba(255, 255, 255, 0.87)"
  },
  "chatHistoryButtonStyle": {
    "color": "rgba(255, 255, 255, 0.87)",
    "backgroundColor": "#070707",
    "border": 0
  },
  "chatHistoryButtonHoveredStyle": {
    "color": "rgba(255, 255, 255, 0.87)",
    "backgroundColor": "#070707",
    "border": 0,
    "textDecoration": "underline"
  }
}

Notice that despite the great degree of flexibility for customisation, the amount of work can get rather significant if you are seeking out a very different design.

With that said, it was obvious that there was a huge room for improvement in the user experience. More specifically, if users could make selections from pre-configured settings and styles, it could potentially make their lives easier by reducing the amount of refinement work required. Thus, the concept of themes was born, which naturally led to the next question - how best to bring themes to users?

The Naive Solution: Pre-package Themes with the Core Library

A naive solution came to mind almost immediately. It is straightforward, and trivial to implement. Simply put, we could pre-make a couple of themes and include their settings and styles directly in the core library. When users specify the themes they desire, we simply fetch and load the relevant settings and styles. Pretty simple, isn't it?

Not only is this solution guaranteed to work, all the changes required to support this feature can be done within the core library itself. It's a tempting solution, but if we pause for a moment and ponder a bit deeper, we quickly realize that the ease of this approach comes with significant tradeoffs.

Firstly, while delivering the initial feature is easy, its maintenance becomes a nightmarish experience for users. This is because every update to the themes - whether it's adding new ones or fixing bugs in existing themes - would necessitate a version bump for the core library. This would be confusing and extremely annoying for users who don't use themes, as they would have to check and update the library for changes irrelevant to their setup.

On top of that, the core library is bound to bloat up overtime as more themes are added. This could potentially lead to degradation in the library's performance, which is most certainly undesirable when trying to craft a seamless chatbot experience.

Advantages

Simple to implement (all changes kept within the core library)
Easy integration for users (themes can be simply applied via the themes prop)

Disadvantages

Poor user experience for maintaining the library in the long term (users may be confused and annoyed by irrelevant version bumps)
Library bloat (unsustainable as more themes are added overtime)

Comparing the advantages and disadvantages, above, it becomes clear that adopting the naive solution trades away scalability and ease of maintenance for a very short-term convenience. With that said, the idea of combining themes into the core library quickly lost its appeal. So, is there a better approach?

A Refined Solution: Create a Themes Extension Package

Drawing on the knowledge from exploring the naive solution, it is apparent that mixing themes with the core library is a terrible idea. So let's address that! In this second solution, we refine the initial idea by addressing its major disadvantages. To do so, we tackle the root of the problem - by keeping themes and the core library separate.

Thus, the idea of a themes extension package came to mind. With this improved approach, themes will be handled independently via a separate NPM package. This reduces the confusion and annoyance caused to users in the naive approach, and prevents the core library from bloating, which helps mitigate the issues faced previously. However, this refined solution is not without its drawbacks.

Firstly, there is now increased complexity in implementing this feature since changes are no longer localised to the core library. Rather, there are now 2 packages to work with, which also increases the effort required to maintain the project. Furthermore, users who wish to use the themes feature will also need to make an additional installation for the extension package and end up having more dependencies.

Advantages

Improved user experience (no confusion or unnecessary updates for those not using themes)
Mitigated library bloat (themes are separated from the core library)

Disadvantages

Additional implementation effort (changes across multiple packages to implement themes)
Additional maintenance effort (2 packages instead of 1)
Additional setup step required from users (installation of extension package required)

The second approach seems slightly better, as the advantages are now oriented to benefit the users while the disadvantages are largely absorbed by… me 🥹. Hmmm, maybe this isn't a terrific idea after all. Can we try something even better?

The Ideal Solution: Serve Themes with JsDeliver & GitHub

In the previous two approaches, we were weighing who should shoulder the seemingly inherent disadvantages that came with implementing themes - whether it was the burden on users or the additional maintenance effort for developers of the library. However, neither of the solutions felt satisfactory. Could we find a way to eliminate or minimize drawbacks for both users and developers?
As a platform engineer, I found inspiration in GitOps -a methodology that uses a Git repository as the single source of truth, with version control providing a clear history of changes. Themes, in the context of React ChatBotify, could be seen as a set-meal containing specific styles and settings (which were configurations stored in json and css files). This realisation led to the idea of hosting themes directly on GitHub, which not only decoupled themes from the core library, but also eliminated the need for maintaining an additional package.

Hence, the third solution explored was to host all theme files, such as settings.json, styles.json and styles.css on GitHub. To avoid rate-limiting issues, the core library would be modified to fetch these themes dynamically using a content delivery network (CDN) such as JSDelivr. This approach offered several very compelling advantages.

Firstly, it eliminated the need for maintaining additional NPM packages and avoided version bumps for the core library when updating themes. Secondly, it preserves the ease of use for users as themes would work out of the box for them. Finally as an added bonus, this solution fosters a more collaborative community environment, as the GitHub repository could be open sourced to welcome contributions from other developers!

Advantages

Improved user experience (no confusion or unnecessary updates for those not using themes)
Mitigated library bloat (themes are separated from the core library)
Easy integration for users (themes can be simply applied via the themes prop)
Encourages open source contributions from the community

Disadvantages

Additional effort required to curate and maintain a GitHub themes repository

Reviewing the above pros and cons, it's clear that this third solution provides a seamless experience for users and allows both themes and the core project to be maintained independently - all while fostering community involvement through the open-source themes repository.

The Winner

After weighing the three options, the third solution emerged as the clear winner due to its strong appeal and comprehensive advantages.
To further enhance the user experience with themes, a separate React ChatBotify Gallery Project was also launched. The Gallery essentially serves as a centralised platform for users to explore and select themes. More details about this was shared in a separate article detailing the release of React ChatBotify v2.

Conclusion

The journey to implementing a theming feature in React ChatBotify was both challenging and rewarding. By leveraging GitOps-inspired principles, the final adopted solution not only simplifies the user experience, it also encourages contributions from the broader developer community. The next step is to encourage creative individuals to craft and contribute themes to the community, but that's a challenge for another time.

With this, we are one step closer to making React ChatBotify a more versatile and customisable library for everyone. I hope you've found this solutioning journey interesting. As usual, if you have any feedback, suggestions, or thoughts about what's shared, feel free to leave a comment or reach out on discord. Thank you for reading! 😊

React ChatBotify v2 Beta Release: What’s Changed, What’s New and What’s Next?

tjtanjin — Fri, 26 Jul 2024 20:27:59 +0000

Introduction

The humble journey of React ChatBotify began in late July of last year. However, it wasn't until recent months that it saw a steady increase in adoptions alongside a series of updates. With the release of v2 beta, it's a great opportunity to look at what's changed, what's new, as well as what's next in future plans down the road.

This article serves to cover the major changes and the thought processes that goes behind them. It's not a migration guide, so if you're looking for detailed steps to upgrade from v1 to v2, refer to the migration guide here.

What's Changed?

In v1, a lot of effort went into making things work. Early adopters might recall issues with the chatbot on mobile devices, such as improper display on certain browsers or operating systems, or notifications causing media controls to appear. The chatbot's come a long way since then and has gotten a lot more stable, thanks to the community of bug reporters who surfaced these issues to be addressed.

In v2, priority shifted to making things right. Admittedly, some early design decisions were not optimal, and a v2 upgrade was timely for rectifying those mistakes. Below, we will look at 3 significant changes from this update.

Reorganization of Options into Settings & Styles

One of the most significant breaking changes in v2 is the reorganization of the options prop (also referred to as BotOptions) into settings and styles. Previously in v1, all configurations for the chatbot were centrally managed within the options prop. This included both configurations for determining the functionalities of the chatbot, as well as styling for the appearance of the chatbot.

However, as the library expanded its capabilities, the options prop grew significantly larger and it became apparent that mixing both functionalities and styles into a single prop was not a great idea. For better clarity and to make configurations more manageable, it was necessary to separate styling from functionalities.

Hence in v2, the settings prop was introduced to manage the functional configurations, such as notification and audio, while the styles prop handles the visual aspects such as headerStyle and botBubbleStyle. This separation not only clarifies the API, it also facilitates future expansions and maintenance.

Dropping of Dynamic Attributes Concept

In v1, dynamic attributes was introduced to refer to a specific set of attributes that allowed you to use params. On hindsight, the concept of dynamic attributes was restrictive, allowing only specific attributes to use params. In fact, removing it would simplify the mental model for developers.

And that's what was done! In v2, all attributes can now access params and users no longer need to make any distinction between them. This change improves consistency across the API and reduces the need for special handling or conditional checks when working with various attributes.

Updates to Internal Message Component

This change is subtle, but for users who were using their own custom components with the chatbot, it is a potential breaking change as the message container itself was updated.

In v1, there was a specific logic written to control the showing of avatars alongside bot or user messages. Internally, default chat messages from both the user and the bot were considered to be chat bubbles and showAvatar was written to specifically only apply to them. Thus, options and checkboxes (which are not chat bubbles) would be specifically filtered out to avoid sending any avatars at all.

This was never an issue, until the need to support media display arose as part of the new showMediaDisplay enhancement for file attachments. With this new feature, there was a need to support sending of avatars for non-chat bubble messages as well because if a user was sending an attachment, it would be weird to not show the avatar if it was enabled. This meant the current design would not work, and prompted a re-look at the need for such special handling in the first place.

To address this and avoid similar issues in future, the decision was made to standardise how avatars will be shown. In short, if enabled, an avatar appears at the beginning of a message group from the same sender, similar to conventional messaging apps (I know, why even do something different in the first place? 😔).

With this change, all message components now adopt a standardised style, which required changes to how messages were displayed. Thus, custom components may experience breaking changes where minor styling updates need to be applied. This was a genuine oversight but it's a necessary update to avoid further issues down the road.

What's New?

Beyond the above changes, v2 itself also brings several exciting new features. A bulk of the new features in v2 stem from user requirements, which often present themselves in the form of feature requests or clarifications for use cases. Below, we'll look at a handful of new features that you might find useful!

Greater Customisation of Header, Chat Input & Footer Buttons

A question that has popped up numerous times - Is it possible to add my own buttons in the header?

In v1, the chatbot came with a set of buttons available in the header, chatInput and footer which could be enabled or disabled. However, re-ordering them was not possible, much less adding custom buttons.

This has changed in v2, with a new buttons prop added to the header, chatInput and footer sections. The buttons prop is essentially an array of buttons, which allows not only custom buttons to be added but also the ability to re-order them however you wish!

Media Displays In Messages

While it was possible to send file attachments in v1, it was not possible to display their content even if they were media files. This meant that viewing images and playing videos or audio in the chatbot was not possible.

Furthermore, without support for media display, it also meant that it's not possible to send voice messages as a playable audio. With v2, support has been added for media display in messages which enables the following features:

Display image, video or audio in file attachments
Send voice messages as an audio file to be played

These are disabled by default but for those who are actively using the file attachment features or would like to send voice messages in the form of audio, enabling them could enhance the overall experience that your chatbot provides for your users!

New Themes Prop

In v1, customising the chatbot appearance could involve heavy styling work, especially if you were looking for a design that was drastically different from the base template.

To improve the customisation experience, a new themes prop was added in v2 which allows users to specify a theme (or list of themes) to apply pre-configured settings and styles quickly. This meant that it is now possible to browse for themes, pick out a design that you like, apply it to your chatbot, then add further refinements on top of it. It helps to think of themes as a set-meal containing settings and styles that save you the work of having to do all the customisations from scratch.

On a small note, implementing the themes feature was an interesting experience itself and I’ve dedicated a separate short article to share about my experience working on it. If you're keen, do take a look!

What's Next?

So far, we've explored features that have been improved or made newly available. Looking ahead, there are a plethora of exciting features still in the works. Below, we visit a few ideas that hold great potential.

To manage expectations, it is important to note that while these features hold great potential, they are all still being explored or worked on. The result might be different or the approach may change along the way while grappling with challenges and navigating new ideas. Keep an open mind!

Theme Builder

If you've checked out the React ChatBotify Gallery website mentioned earlier, you might have noticed a few other pages apart from themes. If you've also tried logging on, you'll notice that GitHub OAuth integration has been added. These are all leading towards an eventual plan to have a theme builder on the website, allowing users to craft custom themes directly before optionally uploading them to share with others.

If you're wondering about the GitHub integration, it is an implementation detail of themes, which will be covered in a separate article that will discuss about this more in depth.

Plugins

Plugins arose as an idea from several requests for live chat support. While exploring how best to support this feature, the appeal of a plugin stood out. This is because there simply isn't a clean way to provide in-built live chat support without restricting the kind of backend setup that could be supported. On the contrary, enabling third-party plugin integrations presents a much more adaptable solution, opening the doors for more possibilities.

With that in mind, the live chat feature evolved into something even more ambitious - rewriting parts of the library to support third-party plugin integrations. More than just live chats, we're looking at the possibility of features such as chatbot analytics, how cool is that!

Emitting ChatBot Events

Last but not least and as an extension to complement the plugin feature, exploratory work is being done for emitting chatbot events. The intention is to allow users to listen for these chatbot events and trigger custom logic based on them.

If you've ever thought about performing certain actions when a message is sent, when a chatbot is opened, or when certain features are enabled, this would be a feature to look forward to!

Conclusion

The newly released v2 beta of React ChatBotify marks the beginning of many more exciting updates. There are various interesting pieces of ongoing work, several of which are gearing us towards enabling and fostering a much more collaborative community.

While I'd like to think that the library is already very feature-rich with a great degree of flexibility for customisation, the truth is there's always room for improvements if you look hard enough and definitely much more that can be achieved.

I hope that this sharing has been interesting, and if you happen to be looking to contribute to open source projects, then do consider picking up some of the good-first-issues! It's always great to have people come together to build something cool! Finally and as usual, feel free to reach out and connect on discord or share your thoughts, suggestions and feedback in the comments. Hope to catch you in the next article!😊

Automating Telegram Bot Deployment with GitHub Actions and Docker

tjtanjin — Wed, 12 Jun 2024 16:16:24 +0000

Introduction

In previous articles, we explored the benefits of Docker, as well as walked through examples of how we may dockerize our project and integrate CI/CD into our development workflows. However, we haven't yet examined how to piece them together in practical applications.

In this article, we will embark on a journey to automate the deployment of a Telegram bot with Docker and GitHub Actions. By the end of this walkthrough, you will garner deeper insights into how Docker and GitHub Actions may be used in tandem to streamline the deployment of your projects. So without further ado, let's dive into the content!

Prerequisites

Before we explore the automating of a Telegram bot deployment, do note that the guide assumes knowledge of the following:

Familiarity with Linux command line
Dockerizing a Project
Basic Understanding of GitHub Actions

We will not be covering the above as they are not the focus of this guide - links to relevant guides for them have been provided! All that said, if you need help with any of the above, you are more than welcome to reach out for assistance.

Note that the contents of this tutorial can be generalized and applied to projects other than Telegram bots. However, for the purpose of this tutorial, you are encouraged to follow it through with this simple Telegram bot project. Even better if you have read my previous articles, because then you would be comfortable working with Telegram bots by now!

Project Setup

As mentioned, we will be using (TeleQR) as an example so go ahead and clone the project to your local computer with the command:

git clone https://github.com/tjtanjin/tele-qr.git

The project already comes with GitHub Actions setup by default. For the purpose of this tutorial, let us remove that by deleting all the contents within the .github/workflows folder. Once that's done, we are ready to create our own workflows!

Specifically for TeleQR, we are keen to create 3 workflows:

Flake8 Lint (for checking of code styles)
Docker Hub (for building and uploading of our docker image)
Deployment (for deploying our Telegram bot)

We will create the workflow files in the order above and watch how all of them come together at the end of this! But first, what makes a typical GitHub Actions workflow?

A Typical GitHub Actions Workflow

A GitHub Actions workflow is a YAML file that automates tasks in your development lifecycle, such as for linting your code or deploying your project. Typically, it's located in the .github/workflows directory of your repository and consist of the following parts:

Name: Provides a convenient identifier for the workflow
Trigger Events: Defines what events trigger the workflow, such as push or pull_request
Jobs and Steps: Specifies jobs that are made up of steps that perform tasks like checking out code, setting up environments, installing dependencies and running tests.
Environment Variables: Defines environment variables that can be used throughout the workflow

There are more properties not covered above but this is enough for understanding the walkthrough. If they look foreign to you, don't fret! We'll now curate a simple workflow file for linting our code that will provide you with more clarity.

Create Flake8 Lint Workflow

To create the Lint workflow, let us first create a flake8-lint.yml file within the .github/workflows folder. For linting, we are using flake8 so let us name this workflow Flake8 Lint:

name: Flake8 Lint

We are also keen to run this workflow only when pushes are made to the master branch, so let us include that as a trigger event:

on:
  push:
    branches: [ "master" ]

Next, we will specify a single lint job to run using the latest Ubuntu image:

jobs:
  lint:
    name: Lint Codebase
    runs-on: ubuntu-latest
    steps:
    # our steps here

As you can see from the comment in the snippet above, we actually need to define the steps in the job. For this lint job, we will carry out the following 4 steps:

Step 1: Checkout Code

Before we can lint our codebase, we need to understand that workflow runs are done on a runner. In this case, you can think of it as a separate server or virtual machine that will run the linting job. The Checkout Code step uses actions/checkout, which is crucial for bringing your repository code into the runner environment:

- name: Checkout code
  uses: actions/checkout@v4

Without this step, your codebase will not even be available for linting!

Step 2: Setup Python

For this Python project, we are using Python 3.10 so let us setup and install this Python version:

- name: Set up Python
  run: |
    sudo add-apt-repository ppa:deadsnakes/ppa
    sudo apt-get update
    sudo apt-get install python3.10 -y
    sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1
    sudo update-alternatives --set python3 /usr/bin/python3.10

Step 3: Install Dependencies

Next, in order to run flake8, we need it to be installed:

- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install flake8

Step 4: Run flake8

Finally, once the setup is complete, we can do the actual linting by running flake8:

- name: Run Flake8
  run: |
    python -m flake8

Putting all our configurations together, our final file for linting will look similar to the following:

name: Flake8 Lint
run-name: Flake8 Lint

on:
  push:
    branches: [ "master" ]

jobs:
  lint:
    name: Lint Codebase
    runs-on: ubuntu-latest
    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up Python
      run: |
        sudo add-apt-repository ppa:deadsnakes/ppa
        sudo apt-get update
        sudo apt-get install python3.10 -y
        sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1
        sudo update-alternatives --set python3 /usr/bin/python3.10

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install flake8

    - name: Run Flake8
      run: |
        python -m flake8

Now that we've gone through the various parts of the workflow, it's getting pretty straightforward - isn't it? Let us move on and look at how we can create the Docker Hub workflow.

Create Docker Hub Workflow

Similar to the Lint workflow, we will add a docker-hub.yml file within the .github/workflows folder. Since we will be publishing a docker image onto Docker Hub in this workflow, let us name it Docker Hub:

name: Docker Hub

However, unlike the Lint workflow, we only want the Docker Hub workflow to run after the Lint workflow is completed. Thus, we add the following trigger event:

on:
  workflow_run:
    workflows: ["Flake8 Lint"]
    types:
      - completed

With that said, just waiting for the Lint workflow to be completed before running the Docker Hub workflow is not enough, we also want to ensure that the Lint workflow completed successfully. Thus, we will add a check to our job:

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    steps:
    # our steps here

Notice an extra line that checks if the workflow_run concluded successfully. We can then move on to adding the job and steps for our Docker Hub workflow:

Step 1: Checkout Code

As with before, we use actions/checkout to checkout our code:

- name: Checkout code
  uses: actions/checkout@v4

Step 2: Login to Docker Hub

In order to publish our Docker Image to Docker Hub, we need to first login to our account. We can make use of docker/login-action for this:

- name: Log in to Docker Hub
  uses: docker/login-action@
  with:
    username: ${{ secrets.DOCKER_USERNAME }}
    password: ${{ secrets.DOCKER_PASSWORD }}

At this point, some of you may be wondering - how are we going to provide the username and password required for logging in? It's certainly not wise to include our credentials directly in the workflow file, but we can use GitHub secrets!

Head over to your repository settings and look to the tab on the left. Under the Security section, click on Secrets and variables and in the dropdown, click on Actions. This is what you should see:

Since we'll need a username and password to login to docker hub, we'll create 2 secrets with the following names:

DOCKER_USERNAME
DOCKER_PASSWORD

The values for these secrets will have to come from your Docker Hub account. Once these are created, they will be available for our Docker Hub workflow to use!

Step 3: Extract Metadata for Docker

We will next then extract the metadata that will be included with our docker image when we push it to Docker Hub using docker/metadata-action:

- name: Extract metadata (tags, labels) for Docker
  id: meta
  uses: docker/metadata-action@v5
  with:
    images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

If you're observant, you may notice that we have 2 environment variables (REGISTRY and IMAGE_NAME) declared here. Go ahead and declare an env property at the top of the file for these variables in the following manner:

env:
  REGISTRY: docker.io
  IMAGE_NAME: ${{ github.repository }}

We are basically specifying that the registry we'll be uploading our docker image to is docker.io and that the repository name will be used as the image name.

Step 4: Build and Push Docker Image

Finally, we build and push our image to Docker Hub:

- name: Build and push Docker image
  uses: docker/build-push-action@v5
  with:
    context: .
    file: ./Dockerfile
    push: true
    tags: ${{ steps.meta.outputs.tags }}
    labels: ${{ steps.meta.outputs.labels }}

Notice that the tags and labels are obtained from the previous step! Your final Docker Hub workflow file should look similar to the following:

name: Docker Hub
run-name: Docker Hub

on:
  workflow_run:
    workflows: ["Flake8 Lint"]
    types:
      - completed

env:
  REGISTRY: docker.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  push_to_registry:
    name: Push Docker image to Docker Hub
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    steps:
      - name: Check out the repo
        uses: actions/checkout@v3

      - name: Log in to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          file: ./Dockerfile
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

Create Deployment WorkFlow

Upon successfully pushing our docker image to Docker Hub, the final workflow we want to run would be deployment. Create a deployment.yml file within the .github/workflows folder. We will simply name this Deployment:

name: Deployment

For deployment, we only want it to run after our image has been pushed to Docker Hub. Thus, we add the following trigger event:

on:
  workflow_run:
    workflows: ["Docker Hub"]
    types:
      - completed

Similarly, we only want to deploy if the Docker Hub workflow succeeded so we add a quick check:

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    steps:
    # our steps here

For this workflow, the job only has a single step which calls the deployment script - the script resides on a Virtual Private Server (VPS) that I have:

- name: executing deployment script
  uses: appleboy/ssh-action@v0.1.10
  with:
    host: ${{ secrets.DEPLOYMENT_HOST }}
    username: ${{ secrets.DEPLOYMENT_USERNAME }}
    password: ${{ secrets.DEPLOYMENT_PASSWORD }}
    script: cd tele-qr/ && ./scripts/deploy.sh tele-qr

Note that we have provided 3 more secrets to authenticate to my VPS using appleboy/ssh-action. For the deployment workflow, it will likely vary depending on how you wish to deploy/host the project. For my project, I hosted it on a simple VPS server and this is the final workflow file:

name: Deployment
run-name: Deployment

on:
  workflow_run:
    workflows: ["Docker Hub"]
    types:
      - completed

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    steps:
    - name: executing deployment script
      uses: appleboy/ssh-action@v0.1.10
      with:
        host: ${{ secrets.DEPLOYMENT_HOST }}
        username: ${{ secrets.DEPLOYMENT_USERNAME }}
        password: ${{ secrets.DEPLOYMENT_PASSWORD }}
        script: cd tele-qr/ && ./scripts/deploy.sh tele-qr

Testing & Verification

Having put everything together, we can easily do a quick test to verify that our workflows are setup as intended. Trigger the workflows to run by making any code changes to the project (e.g. adding a comment) and you should see the Lint workflow beginning to run under the Actions tab of your repository. If everything runs successfully, you'll be greeted with results similar to the following:

Conclusion

Anddddd it's a wrap! In this tutorial, we've gone through detailed steps of setting up our GitHub Actions workflows to automate the deployment of a Telegram bot. If you are keen, you can go further and explore the adding of a test workflow as well as using matrix strategy to run against multiple versions. For reference, the workflows for a chatbot project of mine can be found here.

Finally, I hope that you've found this sharing useful, and that you'll see value in applying what was covered here into your projects. As usual, feel free to share your thoughts, ideas, or feedback in the comments or reach out to me directly. Thank you for your time and see you in the next article!

Level Up Your Projects with GitHub Actions & CI/CD

tjtanjin — Sat, 27 Apr 2024 09:49:13 +0000

Introduction

In today's rapidly-evolving landscape of software development, streamlining workflows, fostering collaboration and producing reliable software have become indispensable goals for developers. Consequently, there has been a notable surge in the adoption of Continuous Integration/Continuous Deployment (CI/CD) practices across the industry.

GitHub, as one of the leading web-based Git repository hosting service, provides a powerful suite of CI/CD tools in the form of GitHub Actions. These are directly integrated into the platform which empowers developers to increase the speed, efficiency and reliability of delivering products. In this brief article, we will take a look at what CI/CD is, why we should use it, as well as some of its applications in my projects.

What is CI/CD?

But first, what is CI/CD? CI/CD, as you may have glimpsed earlier, is an acronym for Continuous Integration/Continuous Deployment, which encompasses a set of practices and methodologies aimed at automating various stages of the software development lifecycle. Specifically in GitHub, CI/CD is also often referred to as GitHub Actions. GitHub Actions can be used to automate tasks ranging from basic code linting and testing for correctness, to even simplifying and speeding up the deployment process.

Why use CI/CD?

Some of you might be thinking: "But I can lint, test and deploy all without CI/CD!" Now, while it's certainly true that all these tasks can be performed manually, leveraging on CI/CD brings about several advantages that can significantly enhance a developer's experience:

Automation: A key benefit of CI/CD is automation. By automating repetitive tasks such as linting and testing, developers can free up their mind to focus on more critical aspects of their development work.
Reliability: Running checks in your CI/CD allow you to catch bugs early, and acts as a safeguard in scenarios where individual developers may have neglected to test their changes. The catching of potential problems before they escalate leads to more reliable software and fewer surprises in production.
Efficiency: With CI/CD, developers are able to quickly validate and receive feedback on their changes, leading to faster iterations and shorter development cycles. Having a streamlined development workflow also boasts better collaboration, enabling teams to deliver updates to production more rapidly and with greater confidence.
Consistency: If you have developed in a team, then you may be familiar with the phrase: "But it works on my computer!" If you've been in those shoes, then the benefits of having CI/CD is obvious. With workflows managed on the Repository, all tests are run in a standardized environment which makes issues more easily reproducible.

Thus, despite it being possible to perform the above tasks manually, the benefits of CI/CD are manifold and adopting it can significantly improve the development process and the quality of the software produced.

Real-World Applications

Now that we've got a better idea of what CI/CD entails and the advantages that it offers, let's delve into a couple of real-world scenarios! Below, I share three examples drawn from my projects to illustrate how CI/CD, specifically GitHub Actions, helps enhance my development experience.

QuickTax

QuickTax originated as a Minecraft plugin designed to keep checks on economies in Minecraft servers. Initially developed for personal use, I eventually released it as an open-source project and the plugin found itself actively used by dozens of servers. With an active user base, maintaining the integrity of the plugin was important. At the bare minimum, changes shouldn't cause the build process to fail.

To provide myself with that reassurance, I added a simple workflow to GitHub Actions which I share below:

name: Build

on:
  push:
    branches: [ "master" ]
  pull_request:
    branches: [ "master" ]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - name: Set up JDK 17
      uses: actions/setup-java@v3
      with:
        java-version: '17'
        distribution: 'temurin'
        cache: maven
    - name: Build with Maven
      run: mvn -B package --file pom.xml

In the snippet above, we can see that the job is set to run whenever there are pushes or pull requests being made to the master branch. Within the job itself, it is simply checking that the plugin can be successfully built with Maven and Java 17. By automating this process, I am able to have the confidence that passing GitHub Actions imply my project can be built reliably.

React ChatBotify

React ChatBotify is a React library that allows users to effortlessly integrate a highly customizable chatbot to their websites. Available on npm, it is slowly gaining adoption and there is an increasing need to ensure its reliability and consistency for users. While the previous project had a single build workflow, this project contains 3 separate workflows for lint, test and build.

We won't delve into the details of the workflow files, as they are quite lengthy, but you can explore them on the project repository. In summary, the lint stage checks for code quality, while the build and test stage ensures correctness. Thus, when GitHub Actions succeed, I have the assurance that the quality of the codebase is upheld and that the library functions as intended.

Simple Media Converter

Simple Media Converter is a Telegram bot created for easy media conversions in my university days when lessons and submissions were mostly online due to covid. Initially, the bot was deployed via Screen and I had to do manual deployments after every code change. When I moved to Docker, I automated the entire deployment flow with GitHub Actions to simplify this process. You can find the workflow files on the project repository.

Recently, HealthPing was also added to notify me to ensure the application liveness. The end result? Pushing code changes to my repository automatically re-deploys my Telegram bot. Should there be errors with the bot, I am notified by HealthPing and I can simply run the deployment workflow again to re-deploy the bot. In fact, I could potentially take things further by having a failed HealthPing automatically trigger a redeployment - but that's a consideration for another time.

Conclusion

To wrap things up, we have seen what CI/CD is along with the benefits it can bring to your software development experience. I hope the examples provided above have convinced you of its usefulness in real-world applications.

If you are keen to look into how to automate an entire deployment process with GitHub Actions, look out for the upcoming article that will be covering how to automate Telegram Bot Deployment with GitHub Actions and Docker. Over there, we will dive deeper into the workflow files that we have skipped over in this article. As usual, if you have suggestions or feedback, feel free to leave them in the comments or reach out here. Thank you for reading, and I'll see you in the next article!

How to Dockerize a Telegram Bot: A Step-by-Step Guide

tjtanjin — Mon, 01 Apr 2024 18:52:56 +0000

Introduction

In a previous article, I covered how to host a Telegram bot with Screen. More recently I also did a sharing on my gradual shift from Screen to Docker for hosting applications. Building upon this progression, this tutorial aims to guide you through the process of dockerizing a Telegram bot!

This preparation sets the stage for our next article, where we will delve into fully automating deployment using Docker and GitHub CI/CD. By the conclusion of this tutorial, not only will you have acquired practical knowledge on dockerizing your bot, you'll also gain a better appreciation for leveraging Docker as a deployment tool.

Prerequisites

Before we dive into the world of Docker, do note that this guide assumes knowledge of the following:

Familiarity with linux command line
Basic Understanding of Python
Basic Understanding of Docker (if you don't, check out this article!)

We will not be covering the above as they are not the focus of this guide - there are plenty of guides out there for them as well! All that said, if you need help with any of the above, you are more than welcome to reach out for assistance.

Note that the contents of this tutorial can be generalized and applied to programs other than Telegram bots. However, for the purpose of this tutorial, you are encouraged to follow it through with a simple Telegram bot that I have. Even better if you have read my previous articles, because then you would be comfortable working with Telegram bots by now. So without further ado, let us begin!

Step 1: Installing Docker

Unsurprisingly, the first step to dockerizing our Telegram bot is to have Docker installed. Depending on your operating system, the installation steps may differ as provided in Docker's installation guide. The steps below are for Ubuntu but you should reference Docker's installation guide if you're using a different operating system:

1. Set up Docker's apt repository.

sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

2. Install the Docker packages.

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3. Verify that the Docker Engine installation is successful by running the hello-world image.

sudo docker run hello-world

Step 2 Clone the Project

Once we've got Docker setup, proceed to clone the sample Telegram bot project with the following command:

git clone https://github.com/tjtanjin/tele-qr.git

Step 3: Setup the Project

Within the project directory, you'll find a file called main.py which has the following contents:

import os

from dotenv import load_dotenv
from health_ping import HealthPing
from telegram.ext import Application, CommandHandler, MessageHandler, filters

from submodules.user_input import show_help, get_input

dotenv_path = os.path.join(os.path.dirname(__file__), '.env')
load_dotenv(dotenv_path)

if os.getenv("HEALTHCHECKS_ENDPOINT"):
    HealthPing(url=os.getenv("HEALTHCHECKS_ENDPOINT"),
               schedule="1 * * * *",
               retries=[60, 300, 720]).start()

def main():
    """
    Handles the initial launch of the program (entry point).
    """
    token = os.getenv("BOT_TOKEN")
    application = Application.builder().token(token).concurrent_updates(True).read_timeout(30).write_timeout(30).build() # noqa
    application.add_handler(CommandHandler('start', show_help))
    application.add_handler(CommandHandler('help', show_help))
    application.add_handler(MessageHandler(filters.TEXT, get_input))
    print("TeleQR instance started!")
    application.run_polling()

if __name__ == '__main__':
    main()

Notice that a BOT_TOKEN is required but it has not been set. If you'd like the complete experience, then you may wish to obtain a bot token which was covered in the guide on how to build a telegram bot.

Alternatively, for ease of following through this tutorial, you may also use a modified code snippet which contains a while True loop to simulate a permanently running program. Here's how the modified script would look like if you choose the latter option:

import time

def main():
    """
    Handles the initial launch of the program (entry point).
    """
    print("TeleQR instance started!")
    while True:
       time.sleep(5)
       print("I am running!")

if __name__ == '__main__':
    main()

Now, let us verify that the project is working by installing the required packages and then running the program:

pip install -r requirements.txt
python main.py

If the program is running successfully, you will see "TeleQR instance started!" printed into the console.

Step 4: Create a Dockerfile

Now that we've got the project running, it's time to look at the Dockerfile. For those of you who are using the sample Telegram bot project, you will notice that a Dockerfile already exists. That's because the sample project is already dockerized. Fret not, go ahead and delete the file and we will recreate it in no time!

1. Create an empty Dockerfile:

In your project directory, create an empty file named Dockerfile. This file will contain instructions for Docker on how to build your container.

2. Adding the base image:

The first line in the Dockerfile specifies the base image that our container will use. In this case, we're using Python version 3.10.12 as our base image so we'll declare this at the top of the file:

FROM python:3.10.12

3. Setting the working directory:

Next, we set the working directory inside the docker container where our application code will reside:

WORKDIR /usr/src/app

4. Copying files into the container:

Following which, we need to copy all the files from our local directory into the container which includes our Python scripts, requirements file, and any other project files. In the COPY command below, the first . represents our current project directory while the second . represents the docker container's working directory (which we have just set with the previous command):

COPY . .

5. Creating a directory:

Then, we use the RUN command to execute mkdir ./images within our docker container's working directory. This step is specific to the sample Telegram bot project we are using but you can generalize this portion of the Dockerfile for any other setup in your projects:

RUN mkdir ./images

6. Installing dependencies:

With the project files setup, we now install the dependencies required by our Python application. We'll first install the packages listed in requirements.txt using pip.

RUN pip install - no-cache-dir -r requirements.txt

Additionally, we'll install the python-telegram-bot package with the [job-queue] extras (again specific to the project):

RUN pip install python-telegram-bot[job-queue]

7. Specifying the command to run the application:

Finally, we specify the command that should be executed when the container starts. In this case, we're running our Python script named main.py.

  CMD ["python", "-u", "./main.py"]

Phew! That was quite a lot to step through, wasn't it? But if you've followed till this far, then congratulations! You've successfully created a Dockerfile for your Telegram bot. There's just one last step left - to build a Docker image based on this Dockerfile and run your bot inside a Docker container!

Step 5: Build & Run

Let us first build our docker image with docker build. Within your project directory, run the following command:

docker build -t my_telegram_bot .

This process may take a while the first time so give it a few moments. The above command essentially reads the instructions from your Dockerfile and builds a Docker image with it. Feel free to replace my_telegram_bot with whatever you wish to name your Docker image.

Once the Docker image is built, we can then finally run our Docker container with docker run:

docker run my_telegram_bot

If you've followed all the steps so far, you'll see your application launching successfully! Before you happily call it a day, here are some useful basic Docker commands to know:

docker run -d <image_id_or_name> - to run the Docker container in detached mode
docker ps - to list all running containers
docker stop <container_id_or_name> - to stop a running container
docker rm <container_id_or_name> - to remove a container
docker images - to list all images
docker rmi <image_id_or_name> - to remove an image
docker logs <container_id_or_name> - to view the logs of a container

These are some basic commands you may find useful but there are plenty of other commands that you will be able to find from Docker's documentation.

Conclusion

With that, we've successfully dockerized and run our Telegram bot inside a Docker container! In this tutorial, we stepped through the process of creating a Dockerfile, building a Docker image from it, and finally running a Docker container based on that image. Additionally, we've explored some useful Docker commands for managing containers and images.

As you continue your journey with Docker, remember that there are plenty of other features to explore. Docker's documentation is a great place to checkout if you wish to learn more about advanced Docker concepts and best practices. As always, if you've got ideas, suggestions or feedback to share, feel free to drop them in the comments or reach out!

Happy coding, and if you're keen to automate your deployment process with me, then stay tuned for the upcoming article!

Mobile Web Audio: Removing Media Controls from Notifications Tray

tjtanjin — Fri, 22 Mar 2024 13:45:59 +0000

Introduction

In the world of web development, even the tiniest details can significantly impact user experience. Recently, while working on improving React ChatBotify, I encountered a persistent issue concerning its notifications feature. This problem had lingered since the initial release, but was relegated to the sidelines as other features took precedence.

So what's the issue? While notification sounds played fine for Desktop users, a subtle inconvenience emerged for mobile users: notification sounds triggered the emergence of media controls within the device's notifications tray. Take a look below to see what I mean:

Feature-breaking? No. Annoying? Yes! In the latest version of this library however, I finally resolved this annoyance once and for all.

The Original Implementation

Before delving into my attempts to rectify the issue, I thought it'd help to share some context on the notifications feature. Basically, the chatbot permits toggling of notification sounds for incoming messages. The library achieves this by initially setting up the notification audio and subsequently triggering it when necessary. For those curious about the inner workings, here's the function responsible for setting up notifications:

const setUpNotifications = () => {
  setNotificationToggledOn(botOptions.notification?.defaultToggledOn as boolean);

  let notificationSound = botOptions.notification?.sound;

  if (notificationSound?.startsWith("data:audio")) {
    const binaryString = atob(notificationSound.split(",")[1]);
    const arrayBuffer = new ArrayBuffer(binaryString.length);
    const uint8Array = new Uint8Array(arrayBuffer);
    for (let i = 0; i < binaryString.length; i++) {
      uint8Array[i] = binaryString.charCodeAt(i);
    }
    const blob = new Blob([uint8Array], { type: "audio/wav" });
    notificationSound = URL.createObjectURL(blob);
  }

  notificationAudio.current = new Audio(notificationSound);
  notificationAudio.current.volume = botOptions.notification?.volume as number;
}

Additionally, here's the function responsible for playing the notifications:

const handleNotifications = () => {
  // if embedded, or no message found, no need for notifications
  if (botOptions.theme?.embedded || messages.length == 0) {
    return;
  }
  const message = messages[messages.length - 1]
  // yes i know these conditions are ugly but i will clean this up someday ;-;
  if (message != null && message?.sender !== "user" && !isBotTyping
    && (!botOptions.isOpen || document.visibilityState !== "visible")) {
    setUnreadCount(prev => prev + 1);
    if (!botOptions.notification?.disabled && notificationToggledOn && hasInteracted) {
      notificationAudio.current?.play();
    }
  }
}

In essence, I loaded the audio and adjusted its volume upon initialization, triggering its playback when handleNotifications was invoked. Though functional, the appearance of media controls in mobile devices' notification trays was a thorn in the flesh!

Attempt #1

Hoping for a quick remedy, I did a swift Google search that led me to the controls attribute, which appeared to be what I needed. Surely, setting controls to false would remove the media controls from the notifications tray right? With a hint of optimism, I threw in a single line at the end of setUpNotifications:

notificationAudio.current.controls = false

Much to my dismay, it didn't work. The media controls were still appearing in the notifications tray.

Attempt #2

Since I was using the HTML 5 Audio, I decided to look into its documentation provided. That was when I stumbled upon controlsList, which also seemed like a promising attribute. Seeking to replace controls with controlsList, I was stumped when I noticed that there was no built-in controlsList attribute for my notificationAudio. With a "let's just try" attitude, I added controlsList directly as an attribute instead:

notificationAudio.current.setAttribute("controlsList", "nodownload");

Hmmmmm, not too unexpectedly, it's not working!

Attempt #3

As I combed the internet for more inspirations, I came upon a suggestion to call .load() again on the audio after playing it. I then had the idea to reset the audio after playing it to hopefully make the media controls go away. Feeling a little confident of this idea, I went into handleNotifications and added a line right after I called .play():

notificationAudio.current?.load()

Anddddd nope, still not working!!

Attempt #4

Feeling a little desperate and restless, I decided to try adding an <audio> tag directly and then using controlsList within it. Hopping over to the return block responsible for the render, I plonked in the following line:

<audio ref={notificationAudio} controlsList="nodownload" />

Ughhhhh! As you may have guessed, it's still not working.

Attempt #5

Exhausted and having tried out various approaches without much success, I decided to give Web Audio API a try. While it appeared slightly harder to work with, I was frankly running out of options. All that said, moving from HTML5 Audio to Web Audio API involved quite a fair bit of changes and experimentation.

Without boring you with the details of my struggles, my final changes involved me ditching notificationAudio and replacing it with audioContextRef, audioBufferRef and gainNodeRef as you can see below:

// audio to play for notifications
 const audioContextRef = useRef<AudioContext | null>(null);
 const audioBufferRef = useRef<AudioBuffer>();
 const gainNodeRef = useRef<AudioNode | null>(null);

Needless to say, I also made significant updates to both functions for setting up and playing notification sounds:

/**
 * Sets up the notifications feature (initial toggle status and sound).
 */
const setUpNotifications = async () => {
  setNotificationToggledOn(botOptions.notification?.defaultToggledOn as boolean);

  let notificationSound = botOptions.notification?.sound;
  audioContextRef.current = new AudioContext();
  const gainNode = audioContextRef.current.createGain();
  gainNode.gain.value = botOptions.notification?.volume || 0.2;
  gainNodeRef.current = gainNode;

  let audioSource;
  if (notificationSound?.startsWith("data:audio")) {
    const binaryString = atob(notificationSound.split(",")[1]);
    const arrayBuffer = new ArrayBuffer(binaryString.length);
    const uint8Array = new Uint8Array(arrayBuffer);
    for (let i = 0; i < binaryString.length; i++) {
      uint8Array[i] = binaryString.charCodeAt(i);
    }
    audioSource = arrayBuffer;
  } else {
    const response = await fetch(notificationSound as string);
    audioSource = await response.arrayBuffer();
  }

  audioBufferRef.current = await audioContextRef.current.decodeAudioData(audioSource);
}

/**
 * Handles notification count update and notification sound.
 */
const handleNotifications = () => {
  // if no audio context or no messages, return
  if (!audioContextRef.current || messages.length === 0) {
    return;
  }

  const message = messages[messages.length - 1]
  // if message is null or sent by user or is bot typing, return
  if (message == null || message.sender === "user" || isBotTyping) {
    return;
  }

  // if chat is open but user is not scrolling, return
  if (botOptions.isOpen && !isScrolling) {
    return;
  }

  setUnreadCount(prev => prev + 1);
  if (!botOptions.notification?.disabled && notificationToggledOn && hasInteracted && audioBufferRef.current) {
    const source = audioContextRef.current.createBufferSource();
    source.buffer = audioBufferRef.current;
    source.connect(gainNodeRef.current as AudioNode).connect(audioContextRef.current.destination);
    source.start();
  }
}

Given the substantial amount of changes, I had to tinker around and try out various attempts first. At some point, the notifications even stopped sounding off entirely, which felt like an even larger setback. However, with a bit more testing and determination, the notification sound eventually chimed again!

Needless to say, pulling down the notifications tray, and not seeing the media controls anymore was extremely satisfying! I am very satisfied with the outcome and while I cannot be certain that this is the best approach, this at least worked out for me. I was also a little surprised that I could not find a solution easily online. Perhaps, I'm just not looking in the right place!

Conclusion

I hope this article along with the code snippets I shared above will be helpful to anyone out there grappling with similar issues. While I've shared my journey in tackling the pesky problem of media controls showing up on mobile devices' notification trays, I'm still open to ideas, suggestions and feedback - especially if you know a better solution!

Feel free to leave your thoughts in the comments below or reach out anytime. If you've read so far, thank you for tuning in to my struggles. Catch you later, and happy coding!

From Screen To Docker: A Look at Two Hosting Options

tjtanjin — Mon, 18 Mar 2024 17:19:21 +0000

Introduction

As you progress in your journey as a software engineer, you'll inevitably ponder how best to showcase your projects - perhaps you've developed a Telegram bot or a Discord bot. At this stage, you might not find much satisfaction if your projects are solely confined to running on your computer. Wouldn't it be great if your work could be accessible from anywhere, at any time, for others to experience?

A Brief Reflection

In my early days, I wasn't aware of Docker, so Screen was always my go-to option. I first stumbled upon Screen while attempting to train a simple model on my machine, and its simplicity appealed to me. As a novice, its ease of use allowed me to easily develop and run programs that I could share with others. However, as my number of applications grew, and when I made the decision to change my hosting provider, I found myself facing the arduous task of reconfiguring and setting up each application from scratch.

It was a time-consuming and painful process, so when I came upon Docker, I knew I had been missing out. Don't get me wrong, it's not that Screen is bad - matter of fact, I still host some of my applications via Screen. Yet, the advantages of Docker were apparent, and driven by the desire for enhanced deployment efficiency and streamlined management of projects, I began a journey towards Docker adoption.

A Tale of Two Scenarios

Let's envision two scenarios that vividly contrast the experiences of utilizing Screen and Docker. In the first scenario, likened to a lavish buffet, Screen presents an array of options with its straightforward setup and immediate accessibility. However, unforeseen disruptions akin to a toppling chocolate tower can swiftly derail plans, leaving users stranded amidst chaos.

Conversely, Docker embodies a neatly packed lunchbox, containing a curated selection of applications within containers. Even if a chocolate tower were to topple, items in your lunchbox remain safe. Docker's encapsulation ensures seamless continuity, enabling users to resume tasks with ease. This juxtaposition vividly portrays the evolution from the simplicity of Screen to the robustness and adaptability of Docker in managing hosting needs.

Understanding Docker and Screen

Continuing from our exploration of contrasting scenarios, let's delve into Docker and Screen in more detail. Docker serves as a platform for developing, packaging, and deploying applications in lightweight, isolated containers. These containers encapsulate not only the application code, but also its dependencies, ensuring consistency across different environments and simplifying configuration management. Consequently, Docker not only offers portability but also helps streamline deployment processes.

On the other hand, Screen offers a convenient way to manage terminal sessions, especially for scenarios involving long-running processes or management of multiple sessions. With Screen, users can detach from a session, allowing processes to continue running in the background even after the terminal connection is closed. This functionality proves invaluable for server processes or remote tasks that necessitate continuous operation without an active terminal connection.

Choosing the Right Tool

While both Docker and Screen are capable of running applications, the decision between the two boils down to project requirements and personal preferences. Docker boasts several strengths that make it ideal for various scenarios:

Building and deploying applications in isolated environments.
Ensuring consistency and reproducibility across different environments.
Scaling applications and managing resources efficiently.
Simplifying dependency management and deployment workflows.

Meanwhile, Screen shines in specific scenarios, such as:

Prototyping quickly for testing and sharing.
Running on resource-constrained systems.

In addition to the above considerations, it is also worth noting that investing time in learning Docker may be necessary for those unfamiliar with it. While Screen's simplicity may appeal to hobbyists and beginners, ambitious projects aiming for scalability and consistency may find Docker more suitable.

As I shared earlier in my journey, I initially favored Screen for its ease of use, particularly as a novice hosting projects. However, as I embarked on more projects, I began to see more value in having streamlined deployment processes. Currently, I host projects like Simple Media Converter, Simple Transcriptions and TeleQR in Docker, while a couple of prototypes, such as my Discord bot, remain on Screen.

Conclusion

In conclusion, whether you're savoring a lavish buffet or enjoying a well-packed lunch, remember to evaluate your circumstances and select the hosting solution that aligns best with your needs. Ultimately, your decision between Docker and Screen should be guided by the nature of your projects, your technical capabilities, and your long-term hosting objectives. In an upcoming article, I will do a sharing on how to deploy a Telegram bot with Docker, where I'll delve into the practical steps of this process. If you're keen, do keep a lookout!

Finally, if you've found this comparison helpful in navigating your decision-making process, feel free to share your thoughts, ideas, or feedback in the comments or reach out to me directly. I am more than happy to engage in a conversation. Thank you for taking the time to read my short sharing, and I wish you success in your hosting journey!

How to Build and Integrate a React Chatbot with LLMs: A React ChatBotify Guide (Part 4)

tjtanjin — Tue, 12 Mar 2024 13:14:39 +0000

Introduction

Welcome back to the fourth installment of the React ChatBotify series! In the rapidly evolving landscape of technology, Large Language Models (LLMs) have become a popular topic today and it should come as no surprise that we are witnessing increased adoption of such models in everyday services. In this tutorial, we will explore the integration with Gemini and dive into how we can build a chatbot empowered by LLMs!

A Quick Thought

In the previous tutorial, we briefly took a look at how we can build an effective FAQ bot to address commonly asked questions. However, we also encountered issues such as hard-coded responses and the inability to respond to unforeseen queries.

As we embark on the fourth part of our tutorial series, we will shift our focus to how we can integrate our chatbot with LLMs to provide more dynamic responses. In the upcoming fifth and final installation, we will further delve into the application of Retrieval Augmented Generation (RAG). This step will fully transition our FAQ bot into an LLM empowered solution, enriched with contextual information and capable of answering questions with a personality!

It is important to note that this segment assumes you already have a React ChatBotify chatbot setup. If you have not, then do visit this guide first.

Gemini AI

Amongst the many emerging LLM models, ChatGPT and Gemini are highly spoken about. For this tutorial, I will be using Gemini as an example since it generously provides free API usage. To the credit of OpenAI, ChatGPT also offers generously low-cost APIs (which I use myself!) so don't hesitate to give them a try in your free time.

All that said, before proceeding with the rest of this tutorial, please go ahead and obtain your Gemini API key by following the instructions on the Gemini website. If you're stuck and require assistance, feel free to reach out.

The Basic Bot

Armed with your API key, let us quickly get a basic bot up and running. In fact, if you already have the chatbot setup from part 2 of this series, then you can easily build off it! However, for the purpose of making this tutorial complete, let's assume we have a clean setup with a bot that greets the user! This can be achieved with the following code snippet:



// MyChatBot.js
import React from "react";
import ChatBot from "react-chatbotify";

const MyChatBot = () => {
  const flow = {
    start: {
      message: "Hello, I will become sentient soon!"
    }
  }
return (
    <ChatBot/>
  );
};
export default MyChatBot;

At this point, we have a very excited chatbot that unfortunately does nothing more than wanting to become sentient. Let's make its wish come true!

Initialize Model

The following is a code snippet from Gemini's quickstart guide as of writing this article:



import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(API_KEY);

async function run() {
  // For text-only input, use the gemini-pro model
  const model = genAI.getGenerativeModel({ model: "gemini-pro"});

  const prompt = "Write a story about a magic backpack."

  const result = await model.generateContent(prompt);
  const response = await result.response;
  const text = response.text();
  console.log(text);
}

run();

We will go ahead to copy and paste this snippet within our own chatbot above and replace the API_KEY with what you have obtained earlier. The result would look like this:



// MyChatBot.js
import React from "react";
import ChatBot from "react-chatbotify";

const MyChatBot = () => {
  const genAI = new GoogleGenerativeAI("YOUR_API_KEY");
  async function run() {
    // For text-only input, use the gemini-pro model
    const model = genAI.getGenerativeModel({ model: "gemini-pro"});

    const prompt = "Write a story about a magic backpack."

    const result = await model.generateContent(prompt);
    const response = await result.response;
    const text = response.text();
    console.log(text);
  }

  const flow = {
    start: {
      message: "Hello, I will become sentient soon!"
    }
  }
return (
    <ChatBot/>
  );
};
export default MyChatBot;

We're getting somewhere, but the model hasn't been integrated with our chatbot! In order to achieve that, we are going to make the following changes:

Add another looping block to our conversation flow that will call the run function to handle interactions with the model
Modify the run function to take in a prompt parameter that is provided by the user, remove the hard-coded prompt from the run function and return the text generated



// MyChatBot.js
import React from "react";
import ChatBot from "react-chatbotify";

const MyChatBot = () => {
  const genAI = new GoogleGenerativeAI("YOUR_API_KEY");
  async function run(prompt) {
    // For text-only input, use the gemini-pro model
    const model = genAI.getGenerativeModel({ model: "gemini-pro"});

    const result = await model.generateContent(prompt);
    const response = await result.response;
    const text = response.text();
    return text;
  }

  const flow = {
    start: {
      message: "Hello, I am sentient now, talk to me!",
      path: "model_loop",
    },
    model_loop: {
      message: async (params) => {
        return await run(params.userInput);
      },
      path: "model_loop"
    },
  }
return (
    <ChatBot/>
  );
};
export default MyChatBot;

At this point, you have an initial working integration! If you would like to visualize the above code in action, you may copy and paste the above snippet into the playground (remember to provide your API key).

The current integration with Gemini is cool and all, but you may have noticed that the chatbot is showing you the return result in entire blocks within messages. This may be fine for short messages, but can get a little problematic for long paragraphs. After all, it's not great to have your users wait forever! Wouldn't it be nice if we could show users parts of the response first?

Stream Responses

The streaming of messages is a feature newly introduced in version 1.3.0 of React ChatBotify. This is particularly useful for integrations with LLMs where responses may be streamed in parts. Let's take a look at how we may modify our current approach to support streaming responses.

Referring back once again to the Gemini's quickstart guide, the following snippet is presented for streaming to support faster interactions:



const result = await model.generateContentStream([prompt, ...imageParts]);

let text = '';
for await (const chunk of result.stream) {
  const chunkText = chunk.text();
  console.log(chunkText);
  text += chunkText;
}

We will thus make the following modifications to our code to utilize this new approach:

Add a second streamMessage parameter (provided via params) to the run function
Replace model.generateContent with model.generateContentStream
Add a for-loop to iterate through the stream response chunks and call params.streamMessage with the currently completed text to stream the message into the chatbot
Modify the model-loop block to include params.streamMessage as a second parameter to the run function



// MyChatBot.js
import React from "react";
import ChatBot from "react-chatbotify";

const MyChatBot = () => {
  const genAI = new GoogleGenerativeAI("YOUR_API_KEY");
  async function run(prompt, streamMessage) {
    // For text-only input, use the gemini-pro model
    const model = genAI.getGenerativeModel({ model: "gemini-pro"});

    const result = await model.generateContentStream(prompt);
    let text = '';
    for await (const chunk of result.stream) {
      const chunkText = chunk.text();
      text += chunkText;
      streamMessage(text);
    }
    return text;
  }

  const flow = {
    start: {
      message: "Hello, I am sentient now, talk to me!",
      path: "model_loop",
    },
    model_loop: {
      message: async (params) => {
        return await run(params.userInput, params.streamMessage);
      },
      path: "model_loop"
    },
  }
return (
    <ChatBot/>
  );
};
export default MyChatBot;

Go ahead and give the modified code snippet above a run in the playground. We've done everything right but it still appears a bit strange, isn't it? The messages are no longer sent as a single block, but it's still coming out in chunked parts instead of appearing character by character.

We are seeing the above behavior because the stream response is providing us text in chunks. If we want to have the text show up character by character, we can manually handle the stream logic. This is slightly more involved and we won't be covering it in this guide but you may refer to the live example that I have provided here.

Note that for demonstration in this tutorial, the API keys are directly included in the chatbot. While convenient, it is generally bad practice to expose your API keys on client side. Instead, a best practice would be to employ a server-side component to manage API calls and have your client communicate with your server-side component instead.

Simulated Stream Responses

Recognizing the aesthetics and popularity of streaming responses, React ChatBotify also provides simStream and streamSpeed options for developers who would like to simulate streaming of text response to users. If you are interested in this option, you may refer to the example found here.

Conclusion

In this tutorial, we've explored the exciting realm of integrating LLMs with React ChatBotify. Using Gemini as an example, we have seen how easily we can empower our chatbots with the ability to provide dynamic responses.

As we conclude the fourth installment, the path ahead promises even more innovation. In the upcoming final segment, we'll explore Retrieval Augmented Generation (RAG) to infuse our chatbot with personality and contextual awareness, elevating it to a truly engaging conversational partner. Thank you for reading, and look out for more content!

How to Build a Telegram Bot: A Beginner’s Step-by-Step Guide

tjtanjin — Sat, 09 Mar 2024 18:09:25 +0000

Introduction

Are you a newcomer to Python, uncertain about what to do for your first project? Or perhaps you are a seasoned developer seeking a new endeavor? If so, then welcome to the world of Telegram bot development!

In this beginner-friendly guide, we'll embark on a journey to create our very own Telegram bot using the Python programming language. Whether you're a coding enthusiast taking initial steps or an experienced developer exploring new avenues, this article will provide you with a hands-on experience to help you bring up your very own Telegram bot.

Prerequisites

Before we dive into the exciting contents, do note that this guide assumes knowledge of the following:

Familiarity with Python
Familiarity with pip
Familiarity with Telegram

Basic Python knowledge will suffice, and we will not be covering the above prerequisites as they are not the focus of this guide - there are plenty of Python & pip guides out there while Telegram is a messaging platform that needs little elaboration. All that said, if you need help with any of the above, you are more than welcome to reach out for assistance.

Setup

Since we are working with a simple Telegram bot, the setup is relatively straightforward. Create and head into the folder where we will house our project (e.g. my_telegram_bot).

We will also be using python-telegram-bot, which is a wrapper around the Telegram API. Install the library with the following command:

pip install python-telegram-bot --upgrade

Next, create a main.py file and paste the following short snippet within it.

from telegram.ext import Application

def main():
    """
    Handles the initial launch of the program (entry point).
    """
    token = ""
    application = Application.builder().token(token).concurrent_updates(True).read_timeout(30).write_timeout(30).build()
    print("Telegram Bot started!", flush=True)
    application.run_polling()

if __name__ == '__main__':
    main()

Let's breakdown the above code. We first define a main function that serves as an entry point for the program. Within the function, a variable named token is initialized with an empty string (not to worry, we'll revisit this soon). We then proceed to initialize the Application class, providing configurations via a builder pattern. Finally, we print a message to notify us that the instance has been started before calling the run_polling method to listen for updates.

If you save this file and try running it with python main.py now, you will be faced with an invalid token error. This is not much surprise, since our token hasn't even been set, which brings us on to the next section on obtaining bot tokens.

Bot Token

For our program to startup successfully, the missing ingredient is the bot token that uniquely identifies our Telegram bot! Thankfully, Telegram provides a bot for us to easily obtain bot tokens:

Head over to BotFather and type /newbot. You will be prompted with a series of questions such as the bot name and handle. Follow through with the creation process and you'll be greeted with a bot token at the end of the steps. This token can be used to control your Telegram bot so keep it safe and do not share it with others!

With the bot token obtained above, return to main.py and replace it where your token is currently an empty string. Try running the file again and this time, you'll see your console printing "Telegram Bot started!".

Great! We've now got a bot running. Go ahead and send a message to your Telegram bot. Is it responding? Something feels amiss, we have not defined what the bot should respond to!

The First Message

For the bot to respond to user actions, we need to provide it with handlers. Since we would like our bot to respond to our text messages, let us start with a simple MessageHandler. Within main.py define a short function as outlined below:

def reply(update, context):
    update.message.reply_text("Hello there!")

Next, we add our MessageHandler and have it filter for text messages by applying filters.TEXT. Your new main.py should now look like this (remember to update the imports at the top as well):

from telegram.ext import Application, MessageHandler, filters

async def reply(update, context):
    await update.message.reply_text("Hello there!")

def main():
    """
    Handles the initial launch of the program (entry point).
    """
    token = YOUR_BOT_TOKEN_HERE
    application = Application.builder().token(token).concurrent_updates(True).read_timeout(30).write_timeout(30).build()
    application.add_handler(MessageHandler(filters.TEXT, reply)) # new text handler here
    print("Telegram Bot started!", flush=True)
    application.run_polling()

if __name__ == '__main__':
    main()

Re-run your bot and try sending in a hello message again. Your bot should reply with "Hello there!". Pretty nice, but what if we want it to run commands?

The First Command

You got your bot to utter its first word, now let's try having it greet us when we say hello via a command instead! Similar to how we added messages, we will add another line but instead of a MessageHandler, we will be using a CommandHandler (again, remember to update your imports):

from telegram.ext import Application, CommandHandler, MessageHandler, filters

async def reply(update, context):
    await update.message.reply_text("Hello there!")

def main():
    """
    Handles the initial launch of the program (entry point).
    """
    token = YOUR_BOT_TOKEN_HERE
    application = Application.builder().token(token).concurrent_updates(True).read_timeout(30).write_timeout(30).build()
    application.add_handler(MessageHandler(filters.TEXT, reply))
    application.add_handler(CommandHandler("hello", reply)) # new command handler here
    print("Telegram Bot started!", flush=True)
    application.run_polling()

if __name__ == '__main__':
    main()

Now, go ahead and type /hello to your chatbot. If you've been following this guide diligently, the bot would have responded with "Hello there!" again.

The First Upload

Getting the hang of things? Let's try with a slightly more advanced option, sending an image to your bot! This time round, we will be using MessageHandler again but unlike the first example, the PHOTO filter will be applied instead of the TEXT filter. Go ahead and add the new line as shown below:

from telegram.ext import Application, CommandHandler, MessageHandler, filters

async def reply(update, context):
    await update.message.reply_text("Hello there!")

def main():
    """
    Handles the initial launch of the program (entry point).
    """
    token = YOUR_BOT_TOKEN_HERE
    application = Application.builder().token(token).concurrent_updates(True).read_timeout(30).write_timeout(30).build()
    application.add_handler(MessageHandler(filters.TEXT, reply))
    application.add_handler(CommandHandler("hello", reply))
    application.add_handler(MessageHandler(filters.PHOTO, reply)) # new photo handler here
    print("Telegram Bot started!", flush=True)
    application.run_polling()

if __name__ == '__main__':
    main()

Now, if you send your bot a photo, it will once again greet you enthusiastically with a "Hello there!" - not the most intuitive for a photo upload but you get the point.

Unleash Your Creativity

We've just gone through some basic examples but I hope you're convinced that creating your own Telegram bot is no tough work! From here on out, you may be interested to check out the documentation for python-telegram-bot to find out more of what you can do with the bot.

For those who are interested to take things further, you may also wish to extend the functionalities of the bot into a project. In case you need some inspirations, I've open-sourced a handful of Telegram bots such as TeleQR, Simple Media Converter and Simple Transcriptions.

As a stretch goal, consider hosting your Telegram bot and including liveness checks once you've completed your project!

Conclusion

In this short walkthrough, we've explored how to create a basic Telegram bot. I hope you found this journey useful for your learning and that you're motivated to explore beyond just this guide. If you've got ideas or suggestions, feel free to leave them in the comments below or bounce ideas with me here. Thank you for reading!