{"id":22677822,"url":"https://github.com/leask/halbot","last_synced_at":"2025-09-07T19:32:41.942Z","repository":{"id":142215652,"uuid":"613045022","full_name":"Leask/halbot","owner":"Leask","description":"Just another `ChatGPT` / `Gemini` / `Mistral (by ollama)` Telegram bob, which is simple design, easy to use, extendable and fun.","archived":false,"fork":false,"pushed_at":"2024-05-23T06:17:30.000Z","size":174,"stargazers_count":97,"open_issues_count":4,"forks_count":17,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-05-23T07:28:52.036Z","etag":null,"topics":["ai","bing","chatgpt","gpt","telegram"],"latest_commit_sha":null,"homepage":"https://leaskh.com/post/711636926789271552/halbot","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Leask.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"leask","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2023-03-12T18:17:12.000Z","updated_at":"2024-05-23T07:28:53.732Z","dependencies_parsed_at":"2023-11-23T06:27:59.339Z","dependency_job_id":"077babb1-485d-4ab0-bae9-f1f4d9588b43","html_url":"https://github.com/Leask/halbot","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Leask%2Fhalbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Leask%2Fhalbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Leask%2Fhalbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Leask%2Fhalbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Leask","download_url":"https://codeload.github.com/Leask/halbot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232250776,"owners_count":18494777,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","bing","chatgpt","gpt","telegram"],"created_at":"2024-12-09T18:02:02.583Z","updated_at":"2025-09-07T19:32:41.930Z","avatar_url":"https://github.com/Leask.png","language":"JavaScript","funding_links":["https://github.com/sponsors/leask"],"categories":[],"sub_categories":[],"readme":"# 🤖️ halbot\n\n[![MIT licensed](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)\n[![Node.js Package](https://github.com/Leask/halbot/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/Leask/halbot/actions/workflows/npm-publish.yml)\n\nJust another `ChatGPT` / `Gemini` / `Claude` / `Azure` / `Jina` / `Ollama` Telegram bot, which is simple design, easy to use, extendable and fun.\n\nLive demo, click to watch on YouTube:\n\n\u003ca href=\"http://www.youtube.com/watch?feature=player_embedded\u0026v=MzBocSyYfcY\" target=\"_blank\"\u003e\u003cimg src=\"http://img.youtube.com/vi/MzBocSyYfcY/0.jpg\"\nalt=\"Halbot live demo\" width=\"240\" height=\"180\" border=\"10\" /\u003e\u003c/a\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eScreenshots: 👈 Click here to see screenshots\u003c/summary\u003e\n  \u003cimg width=\"768\" alt=\"Screenshot 2023-11-10 at 8 37 31 AM\" src=\"https://github.com/Leask/halbot/assets/233022/4d70aa04-49a4-4194-98f9-1a9a7c58b33c\"\u003e\n  \u003cimg width=\"768\" alt=\"Screenshot 1\" src=\"https://user-images.githubusercontent.com/233022/224584278-9c3e3374-6ac2-44ca-8d35-df7747b9c1be.png\"\u003e\n  \u003cimg width=\"768\" alt=\"Screenshot 2\" src=\"https://user-images.githubusercontent.com/233022/224584280-113c03af-54b8-4724-86c7-3aa975f53c9c.png\"\u003e\n  \u003cimg width=\"768\" alt=\"Screenshot 3\" src=\"https://user-images.githubusercontent.com/233022/224584281-526578f9-3f0f-4bf6-a89c-56b07f97beae.png\"\u003e\n  \u003cimg width=\"768\" alt=\"Screenshot 4\" src=\"https://user-images.githubusercontent.com/233022/224584282-d12dca78-1da3-4166-ba39-6d14b78ab3e2.png\"\u003e\n  \u003cimg width=\"768\" alt=\"Screenshot 5\" src=\"https://user-images.githubusercontent.com/233022/232613586-78de64ef-eb53-4a8b-afac-542c9e8975b9.jpg\"\u003e\n  \u003cimg width=\"768\" alt=\"Screenshot 6\" src=\"https://user-images.githubusercontent.com/233022/232613588-c0760c87-15fc-4da8-9e92-fecae8bc7bc4.jpg\"\u003e\n  \u003cimg width=\"768\" alt=\"Screenshot 7\" src=\"https://user-images.githubusercontent.com/233022/232613591-8b863245-ebfb-4f1d-8cb2-7e84be1a34e4.jpg\"\u003e\n  \u003cimg width=\"768\" alt=\"Screenshot 8\" src=\"https://user-images.githubusercontent.com/233022/232613594-86180676-c302-4d12-a79c-b01f61cf13d8.jpg\"\u003e\n\u003c/details\u003e\n\n## Features\n\n- [Telegram](https://telegram.org/) Bot (`Telegram Bot` token required)\n- [ChatGPT](https://openai.com/blog/chatgpt) (`OpenAI` API key required)\n- [Gemini](https://ai.google.dev/gemini-api/docs) (Google `Gemini` API Key required)\n- [Claude](https://www.anthropic.com/api) (`Anthropic` or Google `Vextex` API Key required)\n- [Azure](https://azure.microsoft.com/en-us/solutions/ai) (`Azure` API Key required)\n- [Jina](https://jina.ai/api-dashboard/deepsearch) (`Jina` API Key required)\n- [Ollama](https://github.com/jmorganca/ollama) (Install `Ollama` and serve your model)\n- Speech-to-Text (`OpenAI` or `Google Cloud` API key required, or your own engine)\n- Text-to-Speech (`OpenAI` or `Google Cloud` API key required, or your own engine)\n- Text-to-Image by DALL·E or Imagen (`OpenAI` or Google `Gemini` API key required, or your own engine)\n- OCR/OBJECT_DETECT (`OpenAI` or Google `Gemini` API key required, or your own engine)\n- DeepSearch (`Jina` API Key required)\n- Feeding webpage and [YouTube](https://www.youtube.com/) to enhance your prompt\n- Support Tools (Function Calls)\n- Custom prompt at your fingertips\n- Support `private` and `public` mode, with multiple authenticate methods.\n- `Middleware` style workflow, easy to extend.\n- Built-in support parsing webpages, `YouTube` videos, PDFs, images, Office documents, code files, text files...\n- Realtime stream-style response, no more waiting.\n- Multimodal support for all supported models.\n- Automatically selects the optimal model for the task.\n- Audio input and output support for supported models, not just TTS.\n- Google `Search as a tool` support for [Gemini 2.0](https://ai.google.dev/gemini-api/docs/models/gemini-v2).\n- Markdown rendering\n- Reference rendering\n- Code block rendering, developers friendly.\n- Threaded conversation support.\n- ESM from the ground up\n\n## Basic usage\n\n### Configuration\n\nMake the `halbot` json config file and put it in this path `~/.halbot.json`.\n\nBasic config demo:\n\n```json\n{\n    \"telegramToken\": \"[[Telegram Bot API Token]]\",\n    \"openaiApiKey\": \"[[OpenAI API Key]]\"\n}\n```\n\nAll supported configuration fields:\n\n```js\n{\n\n    // REQUIRED, string.\n    \"telegramToken\": \"[[Telegram Bot API Token]]\",\n\n    // Set some of these fields if you need OpenAI's ChatGPT, Whisper, Embedding features.\n    // OPTIONAL, string.\n    \"openaiApiKey\": \"[[OpenAI API Key]]\",\n    // OPTIONAL, string.\n    \"openaiEndpoint\": \"[[Custom OpenAI API endpoint]]\",\n    // OPTIONAL, string, default: \"gpt-3.5-turbo\".\n    \"openaiModel\": \"[[Custom OpenAI Model ID]]\",\n    // OPTIONAL, integer.\n    \"openaiPriority\": \"[[Custom OpenAI Priority]]\",\n\n    // Set some of these fields if you need Google's Gemini, TTS, STT, OCR, OBJECT_DETECT, Embedding features.\n    // OPTIONAL, string.\n    \"googleApiKey\": \"[[Google Cloud / Gemini API Key]]\",\n    // OPTIONAL, string, default: \"gemini-pro-vision\".\n    \"geminiModel\": \"[[Custom Gemini Model ID]]\",\n    // OPTIONAL, integer\n    \"geminiPriority\": \"[[Custom Gemini Priority]]\",\n\n    // Set some of these fields if you need Anthropic's Claude features.\n    // OPTIONAL, string.\n    \"anthropicApiKey\": \"[[Anthropic API Key]]\",\n    // OPTIONAL, string.\n    \"anthropicCredentials\": \"[[Vertex Anthropic Credentials]]\",\n    // OPTIONAL, string.\n    \"anthropicProjectId\": \"[[Vertex Anthropic Project Id]]\",\n    // OPTIONAL, string, default: `latest claude model`.\n    \"anthropicModel\": \"[[Custom Anthropic Model ID]]\",\n    // OPTIONAL, integer.\n    \"anthropicPriority\": \"[[Custom Anthropic Priority]]\",\n\n    // Set some of these fields if you need SiliconFlow's DeepSearch features.\n    // OPTIONAL, string.\n    \"siliconflowApiKey\": \"[[SiliconFlow API Key]]\",\n    // OPTIONAL, string.\n    \"siliconflowModel\": \"[[Custom SiliconFlow Model ID]]\",\n    // OPTIONAL, integer.\n    \"siliconflowPriority\": \"[[Custom SiliconFlow Priority]]\",\n\n    // Set some of these fields if you need Jina's DeepSearch features.\n    // OPTIONAL, string.\n    \"jinaApiKey\": \"[[Jina API Key]]\",\n    // OPTIONAL, string.\n    \"jinaModel\": \"[[Custom Jina Model ID]]\",\n    // OPTIONAL, integer.\n    \"jinaPriority\": \"[[Custom Jina Priority]]\",\n\n    // Set some of these fields if you need Azure's AI features.\n    // OPTIONAL, string.\n    \"azureApiKey\": \"[[Azure API Key]]\",\n    // OPTIONAL, string.\n    \"azureEndpoint\": \"[[Azure API Endpoint]]\",\n    // OPTIONAL, string.\n    \"azureModel\": \"[[Custom Azure Model ID]]\",\n    // OPTIONAL, integer.\n    \"azurePriority\": \"[[Custom Azure Priority]]\",\n\n    // Set some of these fields if you nee Azure OpenAI's AI features.\n    // OPTIONAL, string.\n    \"azureOpenaiApiKey\": \"[[Azure OpenAI API Key]]\",\n    // OPTIONAL, string.\n    \"azureOpenaiEndpoint\": \"[[Azure OpenAI API Endpoint]]\",\n    // OPTIONAL, string.\n    \"azureOpenaiModel\": \"[[Custom Azure OpenAI Model ID]]\",\n    // OPTIONAL, integer.\n    \"azureOpenaiPriority\": \"[[Custom Azure OpenAI Priority]]\",\n\n    // Set some of these fields if you need Ollama features.\n    // OPTIONAL, boolean.\n    \"ollamaEnabled\": \"[[Enable Ollama API]]\",\n    // OPTIONAL, string.\n    \"ollamaEndpoint\": \"[[Custom Ollama API endpoint]]\",\n    // OPTIONAL, string, default: \"DeepSeek-R1\" (DeepSeek-R1 7B).\n    \"ollamaModel\": \"[[Custom Ollama Model ID]]\",\n    // OPTIONAL, integer.\n    \"ollamaPriority\": \"[[Custom Ollama Priority]]\",\n\n    // OPTIONAL, string.\n    // Using this option along with `googleApiKey` to enable Google Search as a tool.\n    \"googleCx\": \"[[Google Search Engine ID]]\",\n\n    // OPTIONAL, undefined || array of string.\n    // To open the bot to PUBLIC, DO NOT set this field;\n    // To restrict the bot to PRIVATE, set chat/group/channel ids in this array.\n    \"private\": [\"[[CHAT_ID]]\", \"[[GROUP_ID]]\", \"[[CHANNEL_ID]]\", ...],\n\n    // OPTIONAL, string.\n    // Set some of these fields if you want to use a `magic word` to authenticate the bot.\n    \"magicWord\": \"[[Your Magic Word here]]\",\n\n    // OPTIONAL, string.\n    // Use a HOME GROUP to authentication users.\n    // Anyone in this group can access the bot.\n    \"homeGroup\": \"[[GROUP_ID]]\",\n\n    // OPTIONAL, array of enum string.\n    // Enum: 'private', 'mention', 'group', 'channel'.\n    // Defaule: ['private', 'mention'].\n    // By default, it will only reply to `private` chats and group `mention`s.\n    // Adding 'group' or 'channel' may cause too much disturbance.\n    \"chatType\": [\"mention\", \"private\"],\n\n    // OPTIONAL, string.\n    \"hello\": \"[[initial prompt]]\",\n\n    // OPTIONAL, string.\n    \"info\": \"[[bot description]]\",\n\n    // OPTIONAL, string.\n    \"help\": \"[[help information]]\",\n\n    // OPTIONAL, object.\n    // Sessions/conversations storage.\n    // support PostgreSQL, MariaDB/MySQL and Redis for now.\n    // If omitted, the bot will use memory storage and sync to this file.\n    // Example: (Compatibility: https://node-postgres.com/apis/pool)\n    // PostgreSQL is recommended for vector storage.\n    \"storage\": {\n        \"provider\": \"POSTGRESQL\",\n        \"host\": \"[[DATABASE HOST]]\",\n        \"database\": \"[[DATABASE NAME]]\",\n        \"user\": \"[[DATABASE USER]]\",\n        \"password\": \"[[DATABASE PASSWORD]]\",\n        \"vector\": true, // REQUIRED\n        ...[[OTHER DATABASE OPTIONS]],\n    },\n    // OR: (Compatibility: https://github.com/sidorares/node-mysql2)\n    \"storage\": {\n        \"provider\": \"[[\"MARIADB\" || \"MYSQL\"]]\",\n        \"host\": \"[[DATABASE HOST]]\",\n        \"database\": \"[[DATABASE NAME]]\",\n        \"user\": \"[[DATABASE USER]]\",\n        \"password\": \"[[DATABASE PASSWORD]]\",\n        \"charset\": \"utf8mb4\", // REQUIRED\n        ...[[OTHER DATABASE OPTIONS]],\n    },\n    // OR: (Compatibility: https://github.com/luin/ioredis)\n    \"storage\": {\n        \"provider\": \"REDIS\",\n        \"host\": \"[[REDIS HOST]]\",\n        \"password\": \"[[REDIS PASSWORD]]\",\n        ...[[OTHER REDIS OPTIONS]],\n    },\n\n}\n```\n\n### Run it\n\nIn peace-of-mind:\n\n```bash\n$ npx halbot\n```\n\n`If you have multible AI engines configed, use '/chatgpt' or '/bing' to switch between them, or you can use '/*' to ask them all at the same time.`\n\n## Integrate to your project\n\nInstall:\n\n```bash\n$ npm i halbot\n```\n\nCode:\n\n```js\nimport halbot from 'halbot';\n\nconst config = {\n\n    // ...[[ALL THE CONFIG FIELDS SUPPORTED ABOVE]]],\n\n    // OPTIONAL, function.\n    // Your own authentication logic.\n    // return true if the user is authenticated.\n    // return false if the user is not authenticated.\n    auth: async (ctx) =\u003e {\n        // ctx is the `telegraf` context object: https://telegraf.js.org/#context-class\n        // It has been extended: https://github.com/Leask/utilitas/blob/master/lib/bot.mjs\n        return true;\n    },\n\n    // OPTIONAL, object (key renderd as name) or array (name ignored).\n    ai: {\n        [[aiNameA]]: [[aiConfigA]],\n        [[aiNameB]]: [[aiConfigB]],\n        // ...\n    },\n\n    // OPTIONAL, object.\n    // Your own speech-to-text and text-to-speech engine.\n    speech: {\n        stt: [[sttApi]],\n        tts: [[ttsApi]],\n    },\n\n    // OPTIONAL, object.\n    // Your own computer-vision engine.\n    vision: {\n        see: [[ocrAndObjectDetectApi]],\n        read: [[documentAnnotateApi]],\n    },\n\n    // OPTIONAL, object.\n    // Your own image-generator engine.\n    image: {\n        generate: [[textToImageApi]],\n    },\n\n    // OPTIONAL, string.\n    // Path to your own middlewares.\n    // ./skills\n    //  |- skill_a.mjs\n    //    | const action = async (bot) =\u003e {\n    //    |     bot.use(async (ctx, next) =\u003e {\n    //    |         ctx.reply('42');\n    //    |         await next();\n    //    |     });\n    //    | };\n    //    |\n    //    | export const { run, priority, func } = {\n    //    |     run: true,\n    //    |     priority: 100,\n    //    |     func: action,\n    //    | };\n    skillPath: [[pathToYourMiddlewares]],\n\n    // OPTIONAL, object.\n    // Using customized storage engine.\n    // `storage` should Should be compatible with the `Map` interface:\n    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map\n    storage: {\n        provider: [[POSTGRESQL || MARIADB || MYSQL || REDIS]],\n        get: async (key) =\u003e { /* Return session object by chatId. */ },\n        set: async (key, session) =\u003e { /* Save session object by chatId. */ },\n        client: { /* Customized database client / pool. */ },\n            query: async (topic) =\u003e { /* Search history and session by topic. */ },\n            upsert: async (event) =\u003e { /* Save event for history and session. */ },\n        },\n    },\n\n    // OPTIONAL, function.\n    // Using customized embedding engine for history and session search.\n    embedding: async (text) =\u003e { /* Return vector embedding of the text. */ },\n\n    // OPTIONAL, array of string.\n    // Supported mime types of your vision-enabled AI models.\n    // If omitted, bot will use standard OCR and Object Detect to handle images.\n    supportedMimeTypes: [...[[mimeTypes]]],\n\n    // OPTIONAL, object.\n    // Adding extra commands.\n    cmds: {\n        [[commandA]]: [[descriptionA]],\n        [[commandB]]: [[descriptionB]],\n        ...[[OTHER COMMANDS]],\n    },\n\n    // OPTIONAL, object.\n    // Adding extra configurations\n    args: {\n        [[argA]]: {\n            type: 'string',\n            short: [[shortCut]],\n            default: [[defaultValue]],\n            desc: [[description]],\n        },\n        [[argB]]: {\n            type: 'binary',\n            short: [[shortCut]],\n            default: [[defaultValue]],\n            desc: [[description]],\n        },\n        ...[[OTHER ARGS]],\n    },\n\n};\n\nawait halbot(config);\n```\n\n## Foundations\n\n- `halbot` uses my other project [🧰 utilitas](https://github.com/Leask/utilitas) as the basic framework to handle all the dirty work.\n- `halbot` uses [🤖 utilitas.bot](https://github.com/Leask/utilitas/blob/master/lib/bot.mjs) as a Telegram bot engine.\n- `halbot` uses [🤖 utilitas.alan](https://github.com/Leask/utilitas/blob/master/lib/alan.mjs) to communicate with the AI engines.\n\n## Contact me\n\n\u003cimg width=\"320\" alt=\"IMG_2289\" src=\"https://user-images.githubusercontent.com/233022/232649734-ff356d76-1bd6-41b2-ad78-27b62e6a9020.JPG\"\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleask%2Fhalbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleask%2Fhalbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleask%2Fhalbot/lists"}