telegram-comm-agent

Overview

telegram-comm-agent is a reusable, highly-configurable Telegram communication agent bot template for Node.js, built on Telegraf. It enables you to create powerful, data-driven bots for lead capture, service flows, and chat-based automation—without hardcoding business logic or secrets.

---

Features

• Data-driven step-by-step flows: Define your own service flows, prompts, and menus in config.
• No hardcoded secrets or business logic: All sensitive data and flow logic are externalized.
• Admin/agent lead routing: Flexible forwarding modes (all, no, ask) for leads and messages.
• Web server integration: Built-in Express server for /lead HTTP endpoint.
• Extensible and testable: Clean modular code, full unit and e2e test coverage, easy to mock.

---

Installation

Install the package directly from GitHub Releases or source:

npm install OrithmicSoftware/telegram-comm-agent#main

Note: This package is not published to npm. Use the GitHub repo or releases.

---

Quick Start

1. Install telegraf in your project:

   npm install telegraf

2. Copy and edit config.example.js and secrets.example.js to define your services, prompts, and credentials.
3. Create and launch your bot:

   const { createCommAgent } = require('telegram-comm-agent');
   const config = require('./config');
   const secrets = require('./secrets');
   const bot = createCommAgent(config, secrets);
   bot.launch();

---

Configuration

All bot behavior is controlled by your config and secrets files. See config.example.js for a full template.

• SERVICES: List of services (e.g. pizza, car rental, etc.)
• STRINGS: All prompts, menu labels, and templates
• BUTTONS: Main menu and service menu button labels
• FLOW: Step-by-step fields and prompts for each service
• FORWARD_TO_AGENT: 'all', 'no', or 'ask' (lead routing mode)

---

API

createCommAgent(config, secrets)

Creates and returns a Telegraf bot instance, fully wired with your config and flows.

handleLeadForwarding(bot, config, leadText, options)

Forwards a lead to admin/agent according to your config. See docs/README.md for details.

createLeadWebServer(options) (since v1.0.4)

Creates and starts an Express web server with a /lead POST endpoint that forwards leads to Telegram.

Usage:

const { createLeadWebServer } = require('telegram-comm-agent');
const server = createLeadWebServer({
	BOT_TOKEN: 'your-bot-token',
	ADMIN_CHAT_ID: 'admin-id',
	AGENT_CHAT_ID: 'agent-id',
	port: 3000 // or process.env.PORT
});

This enables direct HTTP integration for web forms and external lead sources.

---

Testing

• Run npm test for full unit and e2e coverage.
• E2E tests simulate Telegram and web flows with instance-level mocking.

---

Documentation

See docs/README.md for advanced usage, configuration reference, and extension patterns.

---

---

GitHub Labels

This repository uses the following labels to organize issues and pull requests:

Label	Color	Description
bug	d73a4a	Something isn't working
documentation	0075ca	Improvements or additions to documentation
duplicate	cfd3d7	This issue or pull request already exists
enhancement	a2eeef	New feature or request
good first issue	7057ff	Good for newcomers
help wanted	008672	Extra attention is needed
invalid	e4e669	This doesn't seem right
question	d876e3	Further information is requested
wontfix	ffffff	This will not be worked on

---

License

MIT Install:

npm install OrithmicSoftware/telegram-comm-agent#main

Note: This package is not published to npm. Install directly from GitHub.

License

MIT