{"id":27147973,"url":"https://github.com/r3d4ng3l/personalexpensereport","last_synced_at":"2025-04-08T11:51:54.943Z","repository":{"id":43192797,"uuid":"458752898","full_name":"R3D4NG3L/PersonalExpenseReport","owner":"R3D4NG3L","description":"Personal Expense Report on Google Sheet with Telegram Bot integration","archived":false,"fork":false,"pushed_at":"2022-03-24T18:01:12.000Z","size":561,"stargazers_count":56,"open_issues_count":1,"forks_count":16,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-04-14T10:35:17.097Z","etag":null,"topics":["google-sheets","spending-habits","spending-tracker","telegram-bot"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/R3D4NG3L.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}},"created_at":"2022-02-13T08:34:17.000Z","updated_at":"2024-03-25T04:48:13.000Z","dependencies_parsed_at":"2022-08-24T11:41:11.164Z","dependency_job_id":null,"html_url":"https://github.com/R3D4NG3L/PersonalExpenseReport","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/R3D4NG3L%2FPersonalExpenseReport","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/R3D4NG3L%2FPersonalExpenseReport/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/R3D4NG3L%2FPersonalExpenseReport/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/R3D4NG3L%2FPersonalExpenseReport/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/R3D4NG3L","download_url":"https://codeload.github.com/R3D4NG3L/PersonalExpenseReport/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247838409,"owners_count":21004576,"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":["google-sheets","spending-habits","spending-tracker","telegram-bot"],"created_at":"2025-04-08T11:51:54.464Z","updated_at":"2025-04-08T11:51:54.933Z","avatar_url":"https://github.com/R3D4NG3L.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"**SUMMARY**\n- [🔎 Purpose](#-purpose)\n  - [Features](#features)\n  - [Screenshots](#screenshots)\n- [💪 Installation](#-installation)\n  - [1. Copy Google Spreadsheet](#1-copy-google-spreadsheet)\n  - [2. Create a Telegram Bot](#2-create-a-telegram-bot)\n  - [3. Add App Script to Google Sheet](#3-add-app-script-to-google-sheet)\n  - [4. Deploy App Script as Web Application](#4-deploy-app-script-as-web-application)\n  - [5. App Script personalization with tokens](#5-app-script-personalization-with-tokens)\n    - [Telegram Token](#telegram-token)\n    - [Web App Url](#web-app-url)\n    - [Google Spreadsheet Id](#google-spreadsheet-id)\n    - [Locale Settings](#locale-settings)\n    - [Timezone Settings](#timezone-settings)\n    - [Currency Settings](#currency-settings)\n  - [6. Update App Script Deployment](#6-update-app-script-deployment)\n  - [7. Execute getMe and setWebhook functions](#7-execute-getme-and-setwebhook-functions)\n  - [8. Enable Telegram Bot](#8-enable-telegram-bot)\n\n# 🔎 Purpose\nThe purpose of this open source software is to provide a solution to **personal expense report**.\n\nThis solution includes a **Google Spreadsheet** where all expenses are reported, and a **Telegram bot** integration that allows to view the **latest expenses**, the **total of expense** and to **add or delete expenses**.\n\n## Features\n* ✅ Useful **dashboard** to keep track of your expenses total\n* ✅ Easy **personalizable** expense **categories**\n* ✅ **Data validation** in expense sheet\n* ✅ **Telegram bot integration** with **security protocol** to avoid unexpected unknown users interaction\n\n## Screenshots\n\n| Dashboard  | Expenses  |\n|---|---|\n| ![Dashboard](./img/Screenshot1.png)  | ![Expenses](./img/Screenshot2.png)  |\n\n| Personalizable categories  | Telegram Bot Main Menu  |\n|---|---|\n| ![PersonalizableCategories](./img/Screenshot3.png)  | ![TelegramBot](./img/Screenshot4.png)  |\n\n| Telegram Bot Total Expense   | Telegram Bot Add new expense  |\n|---|---|\n| ![TotalExpenses](./img/Screenshot5.png)  | ![AddNewExpense](./img/Screenshot6.png)  |\n\n\n# 💪 Installation\n## 1. Copy Google Spreadsheet\nCreate a **local copy** to your Google Drive of the following **spreadsheet**:\n* 👉 **[Copy Spreadsheet](https://docs.google.com/spreadsheets/d/1VyCrEkmIRz4T_TmcKiy__y4NPLEFspRelXOKIIBrvbI/edit?usp=sharing)**\n\nRemember to save your **!!LOCAL COPY!! Google Spreedsheet Id** because will be used in the next steps.\ne.g.: https://docs.google.com/spreadsheets/d/1VyCrEkmIRz4T_TmcKiy__y4NPLEFspRelXOKIIBrvbI/edit#gid=479673556\n**The spreedsheet id is '1VyCrEkmIRz4T_TmcKiy__y4NPLEFspRelXOKIIBrvbI'** \u003c- T**his is just an example, you will have definetely a different Google Sheet Id, don't use this otherwise the Telegram Bot integration will not work**\n\n**PAY ATTENTION:** Do not change any sheet name and any column headers otherwise you'll need to update also Telegram bot source code.\n\n![GoogleSheet](./img/Screenshot7.png)\n\n## 2. Create a Telegram Bot\nIf you want to **integrate the Google Spreadsheet with Telegram**, proceed with creating a Telegram Bot.\n\n* 👉 **[How to create a Telegram Bot](https://riptutorial.com/telegram-bot/example/25075/create-a-bot-with-the-botfather)**\n* If you already know how to **create a bot**, here there is the link to **talk with [@BotFather](https://t.me/BotFather)**\n\nRemember to save your **Telegram Token Id** because will be used in the next steps.\n\n![AppScript](./img/Screenshot9.png)\n\n## 3. Add App Script to Google Sheet\n**Copy the content of [TelegramBotIntegration.js](TelegramBotIntegration.js)** source code to a new App Script.\n\nFollow this Google Guide to learn how to add a new App Script:\n* 👉 **[How to add an App Script to a Google Sheet](https://developers.google.com/apps-script/guides/sheets/functions)**\n\n![AppScript](./img/Screenshot8.png)\n\n## 4. Deploy App Script as Web Application\nPerform a new deployment of the App Script as a Web Application.\n* Type: **Web Application**\n* Description: **as you prefer** (e.g. WebAppDeploy)\n* Execute as: **Me**\n* Access authorization: **Everyone**\n* Click on **Execute Deployment**\n* Click on **Authorize Access**\n* Click on **Advanced** in bottom left corner\n* Click on **Open (app script name) (not secure)**\n* Click on **Allow**\n* **SAVE WEB APPLICATION URL GENERATED** (e.g. https://script.google.com/macros/s/AKfycbwHkLLHeAY-07_A2dmXftSX0JNR8gTpeREQmzo2j2aWmItIuSsFSYzlB1bJNw0Dovd3qw/exec)\n* Click on **Finish**\n  \nIn case of problems please **follow this Google guide**:\n* 👉 **[How to deploy an App Script](https://developers.google.com/apps-script/concepts/deployments#new-editor_1\n)**\n\n![Deploy](./img/Screenshot10.png)\n![Deploy](./img/Screenshot11.png)\n\n## 5. App Script personalization with tokens\nIn order to integrate Telegram Bot with Google Sheet we need to **personalize the App Script with the tokens saved in the steps above mentioned**\n\n### Telegram Token\nInsert the **telegram token** saved in step '[2. Create a Telegram Bot](#2-create-a-telegram-bot)' into the variable '**token**' as follows:\n\n```\n/**\n * @var token\n * @brief 1. Fill with your own Telegram Bot Token Id\n *        (e.g. 521xxxx7165:AAHxxxxxxxxjbHr5l-m8rGxxxxxxwbk)\n */\nvar token = \"521xxxx7165:AAHxxxxxxxxjbHr5l-m8rGxxxxxxwbk\";\n```\n\n### Web App Url\nInsert the **web application url** saved in step '[4. Deploy App Script as Web Application](#4-deploy-app-script-as-web-application)' into the variable '**webAppUrl**' as follows:\n\n```\n/**\n * @var webAppUrl\n * @brief 2. Fill with your google web app address\n *        (e.g. https://script.google.com/macros/s/AKfycbwHkLLHeAY-07_A2dmXftSX0JNR8gTpeREQmzo2j2aWmItIuSsFSYzlB1bJNw0Dovd3qw/exec)\n */\nvar webAppUrl = \"https://script.google.com/macros/s/AKfycbwHkLLHeAY-07_A2dmXftSX0JNR8gTpeREQmzo2j2aWmItIuSsFSYzlB1bJNw0Dovd3qw/exec\";\n```\n\n### Google Spreadsheet Id\nInsert the **Google Spreedsheet Id** saved in step '[1. Copy Google Spreadsheet](#1-copy-google-spreadsheet)' into the variable '**ssId**' as follows:\n\n```\n/**\n * @var ssId\n * @brief 3. Fill with Google Spreadsheet Id\n *        (e.g. 1f_IT_kAFIG0TUOZyXL3nW67fxvd0fuSaw6gbAbtxzEo)\n */\nvar ssId = \"1f_IT_kAFIG0TUOZyXL3nW67fxvd0fuSaw6gbAbtxzEo\";\n```\n\n### Locale Settings\nInsert the **locale settings** according to your preferences:\n\n```\n/**\n * @var locale\n * @brief 4. Set your locale for date time parsing\n *           e.g. it-IT\n *           e.g. en-US\n */\n var locale = \"en-US\";\n```\n\n### Timezone Settings\nInsert the **timezone settings** according to your preferences:\n\n```\n /**\n  * @var timeZone\n  * @brief 5. Set your timezone for proper date formatting\n  *           e.g. \"Europe/Rome\"\n  *           e.g. \"America/New_York\"\n  */\n var timeZone = \"America/New_York\";\n```\n### Currency Settings\nInsert the **currency settings** according to your preferences:\n\n```\n /**\n  * @var currency\n  * @brief 6. Set your currency\n  *           e.g. \"$\"\n  *           e.g. \"€\"\n  */\n var currency = \"$\";\n```\n\n\n## 6. Update App Script Deployment\nAfter those personalization we need to update the App Script deployment.\n* Click on **Execute deployment**\n* Click on **Manage deployment**\n* Click on **Modify icon**\n* Click on **Version**\n* Click on **New Version**\n  \n![UpdateDeploy](./img/Screenshot12.png)\n\n## 7. Execute getMe and setWebhook functions\nAfter having deployed the script, you've to execute 'getMe' and 'setWebhook' functions from Google Apps Script\n![getMe](./img/Screenshot17.png)\n![setWebhook](./img/Screenshot18.png)\n\n## 8. Enable Telegram Bot\nSend a **chat to your personal telegram bot** create in step '[2. Create a Telegram Bot](#2-create-a-telegram-bot)' **with any text**\n\n**The bot will reply with:**\n```\n⛔️ You're not authorized to interact with this bot!\n```\n![NotAuthorized](./img/Screenshot13.png)\n\nGo to the **Google Spreadsheet in \"Logs\" sheet, it will be present a new line as follows**:\n```json\n{\n    \"update_id\": 642486188,\n    \"message\": {\n        \"message_id\": 765,\n        \"from\": {\n            \"id\": 8XXXXXXX6,\n            \"is_bot\": false,\n            \"first_name\": \"XXXXXX\",\n            \"last_name\": \"XXXXX\",\n            \"username\": \"XXXXXX\",\n            \"language_code\": \"it\"\n        },\n        \"chat\": {\n            \"id\": 8XXXXXX6,\n            \"first_name\": \"XXXXXX\",\n            \"last_name\": \"XXXXX\",\n            \"username\": \"XXXXX\",\n            \"type\": \"private\"\n        },\n        \"date\": 1644745924,\n        \"text\": \"Hello!\"\n    }\n}\n```\n![Log](./img/Screenshot14.png)\n\nCopy the value of the **field message.from.id**, in this example has been censored as '8XXXXXXX6' and paste it to the sheet 'Authenticated Users' as follows:\n\n![AuthorizedUsers](./img/Screenshot15.png)\n\nNow **send another message to your Telegram bot** and it should reply to you with the main menu, and then you're ready to go **with your Telegram integration**!\n\n![Authenticated](./img/Screenshot16.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr3d4ng3l%2Fpersonalexpensereport","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr3d4ng3l%2Fpersonalexpensereport","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr3d4ng3l%2Fpersonalexpensereport/lists"}