{"id":24979879,"url":"https://github.com/classy-bear/firebase-cloud-functions-telegram","last_synced_at":"2026-05-03T12:39:23.508Z","repository":{"id":274741043,"uuid":"923920204","full_name":"Classy-Bear/firebase-cloud-functions-telegram","owner":"Classy-Bear","description":"Send and receive notifications with Telegram using Cloud Functions","archived":false,"fork":false,"pushed_at":"2025-02-01T20:15:25.000Z","size":89,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-29T09:44:58.505Z","etag":null,"topics":["cloud-functions","firebase","telegram"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/Classy-Bear.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2025-01-29T04:20:52.000Z","updated_at":"2025-02-02T21:09:36.000Z","dependencies_parsed_at":"2025-01-29T05:35:18.379Z","dependency_job_id":null,"html_url":"https://github.com/Classy-Bear/firebase-cloud-functions-telegram","commit_stats":null,"previous_names":["classy-bear/firebase-cloud-functions-telegram"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Classy-Bear%2Ffirebase-cloud-functions-telegram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Classy-Bear%2Ffirebase-cloud-functions-telegram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Classy-Bear%2Ffirebase-cloud-functions-telegram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Classy-Bear%2Ffirebase-cloud-functions-telegram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Classy-Bear","download_url":"https://codeload.github.com/Classy-Bear/firebase-cloud-functions-telegram/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246168087,"owners_count":20734389,"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":["cloud-functions","firebase","telegram"],"created_at":"2025-02-04T04:15:15.443Z","updated_at":"2026-05-03T12:39:23.441Z","avatar_url":"https://github.com/Classy-Bear.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Firebase Telegraf Telegram Bot\n\nA Node.js project utilizing Firebase Functions and the Telegraf library to create a Telegram bot. This bot can send notifications to users and echo back any messages they send.\n\n## Table of Contents\n\n- [Features](#features)\n- [Prerequisites](#prerequisites)\n- [Project Structure](#project-structure)\n- [Installation](#installation)\n  - [1. Clone the Repository](#1-clone-the-repository)\n  - [2. Install Dependencies](#2-install-dependencies)\n  - [3. Configure Environment Variables](#3-configure-environment-variables)\n  - [4. Set Up Firebase](#4-set-up-firebase)\n  - [5. Build and Deploy Functions](#5-build-and-deploy-functions)\n- [Usage](#usage)\n  - [1. Setting Up the Telegram Webhook](#1-setting-up-the-telegram-webhook)\n  - [2. Sending Notifications](#2-sending-notifications)\n  - [3. Sending Files](#3-sending-files)\n  - [4. Receiving and Echoing Messages](#4-receiving-and-echoing-messages)\n- [Testing the Webhook](#testing-the-webhook)\n  - [Using Firebase HTTPS Endpoint](#using-firebase-https-endpoint)\n  - [Using Tunneling Services (ngrok)](#using-tunneling-services-ngrok)\n- [Ignoring TypeScript Errors](#ignoring-typescript-errors)\n- [Security Considerations](#security-considerations)\n- [Troubleshooting](#troubleshooting)\n- [License](#license)\n- [Acknowledgments](#acknowledgments)\n- [Contact](#contact)\n\n## Features\n\n- **sendNotification**: Sends a \"You received a notification\" message to a specified Telegram user.\n- **sendFile**: Sends a file to a specified Telegram user using a URL.\n- **onReceivedMessage**: Listens for incoming messages from users and echoes back the same message.\n\n## Prerequisites\n\nBefore setting up the project, ensure you have the following installed:\n\n- **Node.js**: Version 16 or higher. [Download Node.js](https://nodejs.org/)\n- **Firebase CLI**: For deploying functions. Install via npm:\n  ```bash\n  npm install -g firebase-tools\n  ```\n- **ngrok** (optional): For local testing of webhooks. [Download ngrok](https://ngrok.com/download)\n- **Telegram Bot Token**: Obtain this from [@BotFather](https://t.me/botfather) on Telegram\n\n### Getting Your Chat ID\n\nTo use the notification features, you'll need your chat ID. Here's how to get it:\n\n1. **Start a conversation** with your bot on Telegram\n2. **Send any message** to your bot\n3. **Visit this URL** in your browser (replace `\u003cBOT_TOKEN\u003e` with your actual bot token):\n   ```\n   https://api.telegram.org/bot\u003cBOT_TOKEN\u003e/getUpdates\n   ```\n4. **Look for the `chat` object** in the response. You'll see something like this:\n   ```json\n   {\n     \"ok\": true,\n     \"result\": [{\n       \"update_id\": 123456789,\n       \"message\": {\n         \"message_id\": 1,\n         \"from\": {\n           \"id\": 123456789,\n           \"first_name\": \"John\",\n           \"username\": \"john_doe\"\n         },\n         \"chat\": {\n           \"id\": 123456789,  // This is your chat ID\n           \"first_name\": \"John\",\n           \"username\": \"john_doe\",\n           \"type\": \"private\"\n         },\n         \"date\": 1677721501,\n         \"text\": \"Hello\"\n       }\n     }]\n   }\n   ```\n\n**Note:** \n- If you don't see any updates, send another message to your bot and refresh the URL\n- The `chat.id` value is what you'll use as the `chatId` parameter in API calls\n- This ID is unique for each chat/user with your bot\n\n## Project Structure\n\n```\nfirebase-telegraf-bot/\n├── functions/\n│ ├── src/\n│ │ └── index.ts\n│ ├── package.json\n│ ├── tsconfig.json\n│ └── .env\n├── .firebaserc\n├── firebase.json\n└── README.md\n```\n\n## Installation\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/your-username/firebase-telegraf-bot.git\ncd firebase-telegraf-bot\n```\n\n### 2. Install Dependencies\n\nNavigate to the `functions` directory and install the required packages:\n\n```bash\ncd functions\nnpm install\n```\n\n### 3. Configure Environment Variables\n\nCreate a `.env` file in the `functions` directory with the following content:\n\n```\nTELEGRAM_BOT_TOKEN=your_telegram_bot_token\n```\n\n**Important:** Ensure that `.env` is added to your `.gitignore` to prevent sensitive information from being committed.\n\n### 4. Set Up Firebase\n\n1. **Login to Firebase:**\n\n   ```bash\n   firebase login\n   ```\n\n2. **Initialize Firebase in Your Project Directory:**\n\n   ```bash\n   firebase init\n   ```\n\n   - Select **Functions** when prompted.\n   - Choose **TypeScript** as the language.\n   - Opt to install dependencies when prompted.\n   - Configure other settings as per your project needs.\n\n### 5. Build and Deploy Functions\n\n**Build the Project:**\n\n```bash\nnpm run build\n```\n\n**Deploy the Functions:**\n\n```bash\nfirebase deploy --only functions\n```\n\nAfter deployment, Firebase CLI will provide URLs for your deployed functions.\n\n## Usage\n\n### 1. Setting Up the Telegram Webhook\n\nTo enable Telegram to communicate with your Firebase Functions, set up a webhook.\n\n**Steps:**\n\n1. **Obtain Your Firebase Functions HTTPS URL:**\n\n   After deployment, you'll receive URLs like:\n\n   ```\n   Function URL (sendNotification): https://us-central1-your-project.cloudfunctions.net/sendNotification\n   Function URL (onReceivedMessage): https://us-central1-your-project.cloudfunctions.net/onReceivedMessage\n   ```\n\n2. **Set the Webhook URL with Telegram:**\n\n   Replace `\u003cYOUR_TELEGRAM_BOT_TOKEN\u003e` and `\u003cYOUR_CLOUD_FUNCTION_URL\u003e` with your actual values.\n\n   ```bash\n   https://api.telegram.org/bot\u003cYOUR_TELEGRAM_BOT_TOKEN\u003e/setWebhook?url=\u003cYOUR_CLOUD_FUNCTION_URL\u003e/onReceivedMessage\n   ```\n\n   **Example:**\n\n   ```bash\n   https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/setWebhook?url=https://us-central1-your-project.cloudfunctions.net/onReceivedMessage\n   ```\n\n3. **Verify Webhook Setup:**\n\n   You can verify the webhook status using:\n\n   ```bash\n   https://api.telegram.org/bot\u003cYOUR_TELEGRAM_BOT_TOKEN\u003e/getWebhookInfo\n   ```\n\n### 2. Sending Notifications\n\nTo send a notification to a user, make an HTTP GET request to the `sendNotification` function with the `chatId` as a query parameter.\n\n**Example Request:**\n\n```bash\ncurl https://us-central1-your-project.cloudfunctions.net/sendNotification?chatId=\u003cUSER_CHAT_ID\u003e\n```\n\n**Parameters:**\n\n- `chatId`: The unique identifier for the target chat or username of the target channel.\n\n**Example using curl:**\n\n```bash\ncurl \"https://us-central1-your-project.cloudfunctions.net/sendNotification?chatId=123456789\"\n```\n\n### 3. Sending Files\n\nTo send a file to a user, make an HTTP GET request to the `sendFile` function with the `chatId` and `fileUrl` as query parameters.\n\n**Example Request:**\n\n```bash\ncurl https://us-central1-your-project.cloudfunctions.net/sendFile?chatId=\u003cUSER_CHAT_ID\u003e\u0026fileUrl=\u003cFILE_URL\u003e\n```\n\n**Parameters:**\n\n- `chatId`: The unique identifier for the target chat or username of the target channel\n- `fileUrl`: A publicly accessible URL of the file you want to send\n\n**Example using curl:**\n\n```bash\ncurl \"https://us-central1-your-project.cloudfunctions.net/sendFile?chatId=123456789\u0026fileUrl=https://example.com/file.pdf\"\n```\n\n**Note:** \n- The file URL must be publicly accessible for the function to fetch and send it to Telegram\n- The function will download the file and send it as a document to the specified chat\n- If the file download fails, you'll receive an appropriate error message\n\n### 4. Receiving and Echoing Messages\n\nWhen a user sends a message to your Telegram bot, the `onReceivedMessage` function is triggered. The bot responds by echoing back the received message.\n\n**Flow:**\n\n1. **User Sends Message:** A user sends a message to your Telegram bot.\n2. **Webhook Triggered:** Telegram sends the message data to the `onReceivedMessage` HTTPS endpoint.\n3. **Bot Responds:** The bot processes the message and replies with the same content.\n\n## Testing the Webhook\n\nTesting your webhook is crucial to ensure that your bot interacts correctly with users. You can test the webhook using HTTPS in two primary ways:\n\n### Using Firebase HTTPS Endpoint\n\nAfter deploying your functions to Firebase, use the provided HTTPS URLs to set up and test the webhook.\n\n**Steps:**\n\n1. **Deploy Functions:**\n\n   ```bash\n   firebase deploy --only functions\n   ```\n\n2. **Set Webhook URL with Telegram:**\n\n   ```bash\n   https://api.telegram.org/bot\u003cYOUR_TELEGRAM_BOT_TOKEN\u003e/setWebhook?url=https://us-central1-your-project.cloudfunctions.net/onReceivedMessage\n   ```\n\n3. **Interact with Your Bot:**\n\n   Send messages to your Telegram bot and observe the responses.\n\n### Using Tunneling Services (ngrok)\n\nDuring development, you might prefer testing locally without deploying to Firebase every time. **ngrok** allows you to expose your local server to the internet securely via HTTPS.\n\n**Steps:**\n\n1. **Install ngrok:**\n\n   Download and install ngrok from [https://ngrok.com/download](https://ngrok.com/download).\n\n2. **Start Firebase Emulator:**\n\n   In your project directory, run:\n\n   ```bash\n   firebase emulators:start\n   ```\n\n   By default, Firebase Functions emulator runs on `localhost:5001`.\n\n3. **Expose Local Server with ngrok:**\n\n   ```bash\n   ngrok http 5001\n   ```\n\n   ngrok will provide a public HTTPS URL forwarding to your local server, e.g., `https://abcd1234.ngrok.io`.\n\n4. **Set Webhook with ngrok URL:**\n\n   ```bash\n   https://api.telegram.org/bot\u003cYOUR_TELEGRAM_BOT_TOKEN\u003e/setWebhook?url=https://abcd1234.ngrok.io/onReceivedMessage\n   ```\n\n5. **Test Your Bot:**\n\n   Interact with your Telegram bot and observe the logs in your local development environment.\n\n## Security Considerations\n\n- **HTTPS Only:** Always use HTTPS for webhooks to ensure encrypted data transmission.\n- **Secret Tokens:** Store sensitive information like `TELEGRAM_BOT_TOKEN` securely using environment variables.\n- **Validate Requests:** Implement checks to verify that incoming requests originate from Telegram.\n- **Limit Exposure:** Restrict access to your Firebase Functions to only necessary endpoints.\n\n## Troubleshooting\n\n### Common Issues and Solutions\n\n1. **Webhook Not Receiving Requests:**\n   - **Check Deployment:** Ensure that your Firebase Functions are deployed correctly.\n   - **Verify ngrok:** If using ngrok, confirm that the tunnel is active and the URL is correctly set.\n   - **Firewall Settings:** Ensure that your local firewall or network settings aren't blocking incoming requests.\n\n3. **Bot Not Responding:**\n   - **Check Logs:** Use Firebase Console or `firebase emulators:start` logs to identify issues.\n   - **Verify Webhook:** Ensure the webhook URL is correctly set and accessible.\n\n3. **Sending Notifications Fails:**\n   - **Validate `chatId`:** Ensure that the `chatId` provided is correct.\n   - **Bot Permissions:** Confirm that your bot has the necessary permissions to send messages to the user.\n\n### Debugging Tips\n\n- **Enable Detailed Logging:** Add console logs in your functions to trace execution.\n- **Use Postman:** Manually send requests to your functions to test responses.\n- **Check Telegram Bot Status:** Use Telegram's `getWebhookInfo` to verify webhook status.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n## Acknowledgments\n\n- [Firebase Functions](https://firebase.google.com/docs/functions)\n- [Telegraf.js](https://telegraf.js.org/)\n- [Telegram Bot API](https://core.telegram.org/bots/api)\n- [ngrok](https://ngrok.com/)\n\n## Contact\n\nFor any questions, issues, or contributions, please open an issue.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclassy-bear%2Ffirebase-cloud-functions-telegram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclassy-bear%2Ffirebase-cloud-functions-telegram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclassy-bear%2Ffirebase-cloud-functions-telegram/lists"}