Build your First Plugin
Last updated
Last updated
Hexabot's features can be extended by developing and installing extensions from the Extension Library. A plugin is an extension that allows to add features like text-to-action and third-party system integrations. Once you add a plugin, a new "Building Block" will appear in the Visual Editor for you to use when designing your flows.
If you want to add your own building block, this guide will walk you through the process of developing a custom plugin for your Hexabot project.
TypeScript, Node.js and Nest.js: Being familiar with TypeScript, Node.js and Nest.js makes the process of plugin development smoother. But don't worry if you're just getting started โ our detailed guide will walk you through creating your first plugin.
Node.js: Ensure you have Node.js and a package manager (npm or yarn) installed.
Docker : Ensure you have Docker installed.
Create a new Hexabot project: Download the Hexabot CLI and run the hexabot create my-project
command.
Hexabot plugins interact with Hexabot's existing boilerplate and can be managed through the Hexabot UI. Each plugin typically includes:
A package.json file : To define the plugin meta-data (name, description, ...) as well as extra dependencies you may need to use.
Integration Code: Code that defines how the plugin interacts with Hexabot and external APIs (like Google Gemini in this case).
Settings: Customizable settings to tailor the pluginโs behaviour.
i18n translation files
A Hexabot plugins resides in the following directory /extensions/plugins/
within the root folder of the Hexabot project. Here's the recommended project structure:
Creating a new plugin will help you create a new custom block in the Visual editor. This guide will walk you through creating a custom plugin, using a basic example: "A block that retrieves and displays the current time". This approach can be expanded further to create all kinds of custom blocks, allowing you to add new functionality that aligns perfectly with your project needs.
Navigate to extensions/plugins/
folder in your Hexabot project.
Create a new folder named hexabot-plugin-time
Inside the hexabot-plugin-time
folder, create README.md
file. The file should use the Markdown syntax in order to provide an overview and essential details about the usage of your plugin.
package.json
The package.json
is the manifest file of your plugin. It describes the plugin to Hexabot:
Inside the hexabot-plugin-time folder, create package.json and add the following:
settings.ts
The settings.ts
file is the place where you'll be able to define the settings of your custom block, whether it's setting up API authentication or any other configurations.
In the same folder, create settings.ts
file and paste the following::
Later, the block configuration menu will display these settings, as illustrated below
This folder stores translation filess for your plugin to be multilingual. You can add as many languages as needed by creating a new folder for each language under i18n
folder. Place under each language file a JSON document that will define your translation for a specific language. For example, the file title.json
includes the translation of your plugin name.
Inside the hexabot-plugin-time directory, create a new folder named i18n
Inside the i18n folder, create a new folder named en
Refer to this example of Gemini Plugin to better understand how to define your i18n translation string :
Implement Block Logic (index.plugin.ts):
This plugin example returns the current time when sending 'time' keyword in the chat to trigger the conversation flow. You can learn more about creating your flow and managing blocks here.
Inside the same directory hexabot-plugin-time create the index.plugin.ts
with the following code:
Let's start by importing necessary modules and services:
Import all the necessary modules, services, and types required for the plugin.
Define the plugin class and specify its template:
Create a class CurrentTimePlugin
extending BaseBlockPlugin
and define the plugin's template with patterns, conversation starter, and a display name.
@Injectable()
: A decorator that makes the class injectable within the NestJS which is the underlying framework for Hexabotโs API.
CurrentTimePlugin extends BaseBlockPlugin<typeof SETTINGS>
: Defines our plugin class, inheriting from BaseBlockPlugin and specifying that the settings are defined by our previously created settings.ts file.
template
: A class attribute that defines the default template for the building block:
patterns
: The list of keywords that will trigger the block.
starts_conversation
: Whether the block can start a conversation or should it only be triggered by previous messages.
name
: The name of the block that will appear in the visual editor.
Constructor to initialize services:
Initialize the necessary services (PluginService
, BlockService
, and SettingService
) in the constructor.
Define the getPath
method:
Adding the getPath()
method is mandatory, which helps Hexabot to identify the directory name of the current module and locating the plugin's files.
process()
method to handle block main logic:The process()
method performs the main logic of the block:
Fetch settings and arguments.
Gets the current time and format it.
Generate a random response message by combining the formatted time with a predefined message.
Create an outgoing message envelope with the response text.
Return the message envelope.
Restart Hexabot API service so that it recognises the newly added plugin. If you are using the development mode (using the `hexabot dev` CLI command), the API should restart automatically. In case you have installed extra node dependencies, then you may need to stop/start the service.
Test in Visual Editor: Open the Visual Editor, your custom block named Current Time Plugin should be available within the left panel under the "Custom Blocks" section. Add it to your flow and use the "time" keyword in the Admin Chat Console, the block should then be triggered and return the formatted time.
The following represents what your custom plugin will look like based on the example above:
After completing your plugin, be sure to connect with the Hexabot community on Discord to showcase your plugin and work in the show-n-tell channel.
Consider publishing your plugin to a repository (e.g., NPM, GitHub) for others to use and continue to improve it.
The Hexabot Extension Library is a collection of extensions built by the community, for the community. Contributors can share their extensions, allowing everyone to benefit from a growing collection of plugins, channels, and helpers to enhance their conversational AIs.
Remember that the best way to learn is to dive in, experiment, and build. Don't hesitate to refer back to the core Hexabot documentation and our Discord community as you continue your development journey!
Below is the complete code for the CurrentTimePlugin
: