🤖️ halbot

Just another AI powered Telegram bot, which is simple design, easy to use, extendable and fun.

ℹ️ In the latest version, we've moved away from directly integrating multiple SDKs and are now focusing on supporting OpenAI-style APIs. We recommend using OpenRouter for multi-model access, as it greatly simplifies configuration and usage complexity. This approach also provides more flexibility in selecting and switching between different AI models.

Live demo, click to watch on YouTube:

Screenshots: 👈 Click here to see screenshots

Features

• Telegram Bot (Telegram Bot token required)
• OpenRouter (OpenRouter API Key required)
• ChatGPT (OpenAI API key required)
• Jina (Jina API Key required)
• Ollama (Install Ollama and serve your model)
• Speech-to-Text (OpenAI or Google API key required, or your own engine)
• Text-to-Speech (OpenAI or Google API key required, or your own engine)
• Image generation by DALL·E or Imagen (OpenAI or Google API key required, or your own engine)
• Video generation by veo (Google API key required, or your own engine)
• OCR/OBJECT_DETECT (OpenAI or Google API key required, or your own engine)
• DeepSearch (Jina API Key required)
• Feeding webpage and YouTube to enhance your prompt
• Support Tools (Function Calls)
• Custom prompt at your fingertips
• Support private and public mode, with multiple authenticate methods.
• Middleware style workflow, easy to extend.
• Built-in support parsing webpages, YouTube videos, PDFs, images, Office documents, code files, text files...
• Realtime stream-style response, no more waiting.
• Multimodal support for all supported models.
• Automatically selects the optimal model for the task.
• Audio input and output support for supported models, not just TTS.
• Google Search as a tool support for Gemini 2.0.
• Markdown rendering
• Reference rendering
• Code block rendering, developers friendly.
• Threaded conversation support.
• ESM from the ground up

Basic usage

Configuration

Make the halbot json config file and put it in this path ~/.halbot.json.

Basic config demo:

{
    "telegramToken": "[[Telegram Bot API Token]]",
    "openaiApiKey": "[[OpenAI API Key]]"
}

All supported configuration fields:

{

    // REQUIRED, string.
    "telegramToken": "[[Telegram Bot API Token]]",

    // Set some of these fields if you need Openrouter's LLM/Embedding/STT models.
    // OPTIONAL, string.
    "openrouterApiKey": "[[OpenRouter API Key]]",
    // OPTIONAL, string, default: "*".
    "openrouterModel": "[[Custom OpenRouter Model ID]]",
    // OPTIONAL, integer.
    "openrouterPriority": "[[Custom OpenRouter Priority]]",

    // Set some of these fields if you need Google's search, imagen, veo, TTS features.
    // OPTIONAL, string.
    "googleApiKey": "[[Google Cloud / Gemini API Key]]",
    // OPTIONAL, string, set if you need Google Search as a tool.
    "googleCx": "[[Google Search Engine ID]]",

    // Set some of these fields if you need OpenAI's ChatGPT, TTS/STT, Embedding features.
    // OPTIONAL, string.
    "openaiApiKey": "[[OpenAI API Key]]",
    // OPTIONAL, string.
    "openaiEndpoint": "[[Custom OpenAI API endpoint]]",
    // OPTIONAL, string, default: [[latest gpt mainstream model]].
    "openaiModel": "[[Custom OpenAI Model ID]]",
    // OPTIONAL, integer.
    "openaiPriority": "[[Custom OpenAI Priority]]",

    // Set some of these fields if you need SiliconFlow's AI models.
    // OPTIONAL, string.
    "siliconflowApiKey": "[[SiliconFlow API Key]]",
    // OPTIONAL, string.
    "siliconflowModel": "[[Custom SiliconFlow Model ID]]",
    // OPTIONAL, integer.
    "siliconflowPriority": "[[Custom SiliconFlow Priority]]",

    // Set some of these fields if you need Jina's DeepSearch, reader, search features.
    // OPTIONAL, string.
    "jinaApiKey": "[[Jina API Key]]",
    // OPTIONAL, string.
    "jinaModel": "[[Custom Jina Model ID]]",
    // OPTIONAL, integer.
    "jinaPriority": "[[Custom Jina Priority]]",

    // Set some of these fields if you need Ollama features.
    // OPTIONAL, boolean.
    "ollamaEnabled": "[[Enable Ollama API]]",
    // OPTIONAL, string.
    "ollamaEndpoint": "[[Custom Ollama API endpoint]]",
    // OPTIONAL, string, default: "DeepSeek-R1" (DeepSeek-R1 7B).
    "ollamaModel": "[[Custom Ollama Model ID]]",
    // OPTIONAL, integer.
    "ollamaPriority": "[[Custom Ollama Priority]]",

    // OPTIONAL, undefined || array of string.
    // To open the bot to PUBLIC, DO NOT set this field;
    // To restrict the bot to PRIVATE, set chat/group/channel ids in this array.
    "private": ["[[CHAT_ID]]", "[[GROUP_ID]]", "[[CHANNEL_ID]]", ...],

    // OPTIONAL, string.
    // Use a HOME GROUP to authentication users.
    // Anyone in this group can access the bot.
    "homeGroup": "[[GROUP_ID]]",

    // OPTIONAL, array of enum string.
    // Enum: 'private', 'mention', 'group', 'channel'.
    // Defaule: ['private', 'mention'].
    // By default, it will only reply to `private` chats and group `mention`s.
    // Adding 'group' or 'channel' may cause too much disturbance.
    "chatType": ["mention", "private"],

    // OPTIONAL, string.
    "hello": "[[initial prompt]]",

    // OPTIONAL, string.
    "info": "[[bot description]]",

    // OPTIONAL, string.
    "help": "[[help information]]",

    // OPTIONAL, object.
    // Sessions/conversations storage.
    // support PostgreSQL, MariaDB/MySQL and Redis for now.
    // If omitted, the bot will use memory storage and sync to this file.
    // Example: (Compatibility: https://node-postgres.com/apis/pool)
    // PostgreSQL is recommended for vector storage.
    "storage": {
        "provider": "POSTGRESQL",
        "host": "[[DATABASE HOST]]",
        "database": "[[DATABASE NAME]]",
        "user": "[[DATABASE USER]]",
        "password": "[[DATABASE PASSWORD]]",
        "vector": true, // REQUIRED
        ...[[OTHER DATABASE OPTIONS]],
    },
    // OR: (Compatibility: https://github.com/sidorares/node-mysql2)
    "storage": {
        "provider": "[["MARIADB" || "MYSQL"]]",
        "host": "[[DATABASE HOST]]",
        "database": "[[DATABASE NAME]]",
        "user": "[[DATABASE USER]]",
        "password": "[[DATABASE PASSWORD]]",
        "charset": "utf8mb4", // REQUIRED
        ...[[OTHER DATABASE OPTIONS]],
    },
    // OR: (Compatibility: https://github.com/luin/ioredis)
    "storage": {
        "provider": "REDIS",
        "host": "[[REDIS HOST]]",
        "password": "[[REDIS PASSWORD]]",
        ...[[OTHER REDIS OPTIONS]],
    },

}

Run it

In peace-of-mind:

$ npx halbot

Run /help in the chat to get help information.

Integrate to your project

Install:

$ npm i halbot

Code:

import halbot from 'halbot';

const config = {

    // ...[[ALL THE CONFIG FIELDS SUPPORTED ABOVE]]],

    // OPTIONAL, function.
    // Your own authentication logic.
    // return true if the user is authenticated.
    // return false if the user is not authenticated.
    auth: async (ctx) => {
        // ctx is the `telegraf` context object: https://telegraf.js.org/#context-class
        // It has been extended: https://github.com/Leask/utilitas/blob/master/lib/bot.mjs
        return true;
    },

    // OPTIONAL, object (key renderd as name) or array (name ignored).
    ai: {
        [[aiNameA]]: [[aiConfigA]],
        [[aiNameB]]: [[aiConfigB]],
        // ...
    },

    // OPTIONAL, object.
    // Your own embedding engine.
    embedding: [[embeddingApi]],

    // OPTIONAL, object.
    // Your own speech-to-text and text-to-speech engine.
    speech: {
        stt: [[sttApi]],
        tts: [[ttsApi]],
    },

    // OPTIONAL, object.
    // Your own computer-vision engine.
    vision: {
        see: [[ocrAndObjectDetectApi]],
        read: [[documentAnnotateApi]],
    },

    // OPTIONAL, object.
    // Your own image-generator engine.
    image: {
        generate: [[textToImageApi]],
    },

    // OPTIONAL, string.
    // Path to your own middlewares.
    // ./skills
    //  |- skill_a.mjs
    //    | const action = async (bot) => {
    //    |     bot.use(async (ctx, next) => {
    //    |         ctx.reply('42');
    //    |         await next();
    //    |     });
    //    | };
    //    |
    //    | export const { run, priority, func } = {
    //    |     run: true,
    //    |     priority: 100,
    //    |     func: action,
    //    | };
    skillPath: [[pathToYourMiddlewares]],

    // OPTIONAL, object.
    // Using customized storage engine.
    // `storage` should Should be compatible with the `Map` interface:
    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
    storage: {
        provider: [[POSTGRESQL || MARIADB || MYSQL || REDIS]],
        get: async (key) => { /* Return session object by chatId. */ },
        set: async (key, session) => { /* Save session object by chatId. */ },
        client: { /* Customized database client / pool. */ },
            query: async (topic) => { /* Search history and session by topic. */ },
            upsert: async (event) => { /* Save event for history and session. */ },
        },
    },

    // OPTIONAL, function.
    // Using customized embedding engine for history and session search.
    embedding: async (text) => { /* Return vector embedding of the text. */ },

    // OPTIONAL, array of string.
    // Supported mime types of your vision-enabled AI models.
    // If omitted, bot will use standard OCR and Object Detect to handle images.
    supportedMimeTypes: [...[[mimeTypes]]],

    // OPTIONAL, object.
    // Adding extra commands.
    cmds: {
        [[commandA]]: [[descriptionA]],
        [[commandB]]: [[descriptionB]],
        ...[[OTHER COMMANDS]],
    },

    // OPTIONAL, object.
    // Adding extra configurations
    args: {
        [[argA]]: {
            type: 'string',
            short: [[shortCut]],
            default: [[defaultValue]],
            desc: [[description]],
        },
        [[argB]]: {
            type: 'binary',
            short: [[shortCut]],
            default: [[defaultValue]],
            desc: [[description]],
        },
        ...[[OTHER ARGS]],
    },

};

await halbot(config);

Foundations

• halbot uses my other project 🧰 utilitas as the basic framework to handle all the dirty work.
• halbot uses 🤖 utilitas.bot as a Telegram bot engine.
• halbot uses 🤖 utilitas.alan to communicate with the AI engines.

Related Issues:

Besure to upgrade jwa on node v25: auth0/node-jsonwebtoken#992

$ npm upgrade jwa

Contact me