{"id":42577874,"url":"https://github.com/armand1m/gringobot","last_synced_at":"2026-01-28T22:01:37.234Z","repository":{"id":43261515,"uuid":"345336241","full_name":"armand1m/gringobot","owner":"armand1m","description":"Bot with utilities for the Telegram Group Programando na Gringa (https://go.d1m.dev/png)","archived":false,"fork":false,"pushed_at":"2024-03-12T10:12:24.000Z","size":261,"stargazers_count":35,"open_issues_count":4,"forks_count":9,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-10-27T09:39:12.338Z","etag":null,"topics":["bot","telegram"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/armand1m.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2021-03-07T12:05:53.000Z","updated_at":"2025-08-25T16:57:27.000Z","dependencies_parsed_at":"2024-03-12T01:44:45.765Z","dependency_job_id":"9677c504-6e74-45da-83b4-da6a96854cea","html_url":"https://github.com/armand1m/gringobot","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/armand1m/gringobot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armand1m%2Fgringobot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armand1m%2Fgringobot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armand1m%2Fgringobot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armand1m%2Fgringobot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/armand1m","download_url":"https://codeload.github.com/armand1m/gringobot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armand1m%2Fgringobot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28853194,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T15:15:36.453Z","status":"ssl_error","status_checked_at":"2026-01-28T15:15:13.020Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["bot","telegram"],"created_at":"2026-01-28T22:01:36.412Z","updated_at":"2026-01-28T22:01:37.226Z","avatar_url":"https://github.com/armand1m.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gringobot\n\nBot with utilities for the Telegram Group [Programando na Gringa](https://go.d1m.dev/png)\n\nThis bot offer features that make the management of a large international group easier. We use it to add common questions and features that make the experience of our members more delightful.\n\nAll content is managed in markdown and is requested over the network through Github API's, so we don't have to redeploy the bot to have updated content.\n\nThe bot allows members to register the country they're located, so when questions about specific places come up, they can just use the bot to find those folks through a simple command like `/whoat NL` and ping them if needed with `/ping NL`\n\nThis bot is available in Telegram as [@PNGGringoBot](https://t.me/PNGGringoBot) and it works in multiple groups. Keep in mind that the admins of [Programando na Gringa](https://go.d1m.dev/png) own this instance as a community effort and manage the data accordingly. Feel free to reach out if you have any questions.\n\n## Features\n\nThe bot replies in English by default. You can change the language using the `/set_language \u003clocale\u003e`. Currently, only `en` and `ptbr` are available locales. Please feel free to open a PR adding more locales.\n\n - [x] Register member location:\n    - [x] English: `/register_member_at NL`, `/imat NL`\n    - [x] Portuguese: `/estou NL`, `/estou Holanda`\n - [x] Find folks from a location:\n    - [x] English: `/find_members_at NL`, `/whoat NL`\n    - [x] Portuguese: `/quem NL`, `/quem Holanda`\n - [x] Ping folks from a location:\n    - [x] English: `/ping_members_at NL`, `/ping NL`, `/ping remote`\n    - [x] Portuguese: `/alo NL`, `/alo Holanda`\n    - **Note on this feature**:\n      - Telegram imposes limits on actually pinging more than 5 mentions in the same message. When trying to ping people registered in a location, this bot will randomly select 5 of those folks and mention them. The rest will still be mentioned, but with silent mentions.\n - [x] Deregister member location:\n    - [x] English: `/leave NL`\n    - [x] Portuguese: `/sair NL`, `/sair Holanda`\n - [x] Find member registered locations:\n    - [x] English: `/find_member`, `/whereami`\n    - [x] Portuguese: `/ondeestou`\n - [x] List Member count per Country:\n    - [x] English: `/list_country_member_count`, `/list`\n    - [x] Portuguese: `/quantos`\n    - [ ] Include remote members when listing\n - [x] Rank countries by number of members\n    - [x] English: `/rank_country_member_count`, `/rank`\n    - [x] Portuguese: `/classificacao`\n    - [ ] Include remote members when ranking\n - [x] Register as Remote Member:\n    - [x] English: `/register_remote_member \u003cfrom\u003e \u003cto\u003e`\n    - [x] Portuguese: `/estou_remoto \u003cfrom\u003e \u003cto\u003e`\n - [x] Deregister as Remote Member:\n    - [x] English: `/deregister_remote_member`\n    - [x] Portuguese: `/sair_remoto`\n - [x] Find remote member working from a location:\n    - [x] English: `/find_remote_member_from BR`\n    - [x] Portuguese: `/quem_remoto_do BR`\n - [x] Find remote member working for a location:\n    - [x] English: `/find_remote_member_to CA `\n    - [x] Portuguese: `/quem_remoto_para CA`\n - [x] Ping all remote members:\n    - [x] `/ping_remote`, `/ping remote` _(case insensitive)_\n - [x] Help Sections:\n    - [x] English: `/help \u003csubject\u003e \u003ctopic\u003e`\n    - [x] Portuguese: `/ajuda \u003cassunto\u003e \u003ctopico\u003e`\n - [x] Ping all admins:\n    - [x] `/ping_admins`, `/admins`, `/eita`\n - [x] Kick user:\n    - [x] `/kick`\n      - Only works by replying a message from the user to be kicked.\n - [x] Set Group Language:\n    - [x] `/set_language en`\n    - [x] `/set_language ptbr`\n - [x] Captcha:\n    - New members will face a simple captcha on groups with this enabled.\n    - All CAPTCHA messages are self-destructable, except the rejection ones.\n    - [x] `/enable_captcha`: Will enable the captcha in the group. Can only be executed by admins.\n    - [x] `/disable_captcha`: Will disable the captcha in the group. Can only be executed by admins.\n - [x] Self preservation habilities\n    - [x] Handle deleted registered users and deregister those when identified\n    - [x] Auto bans accounts with Cyrillic Characters _(huge sorry to all the eastern europeans for this, russians made me do it)_\n - [x] Message Auto Deletion:\n    - [x] Configurable through the `MESSAGE_TIMEOUT_IN_MINUTES` environment variable. Default is `2`.\n    - [x] Feature can be toggled through the `MESSAGE_TIMEOUT_ENABLED` environment variable. Default is `true`.\n    - [x] Deletes both command and reply messages after timeout is reached.\n    - [x] Deletes all interactions that were replied with error messages.\n    - [x] Deletes messages from the following commands:\n      - `/leave`\n      - `/find_member`\n      - `/register_member_at`\n      - `/register_remote_member`\n      - `/deregister_remote_member`\n      - `/find_members_at` (only if no members are found)\n      - `/ping_members_at` (only if no members are found)\n      - `/list_country_member_count` (only if no members are registered)\n      - `/rank_country_member_count` (only if no members are registered)\n\n## Developing\n\nMake sure you have Git and Node 19+ (installed through `nvm` is recommended) available in your local environment.\n\n```sh\n# clone repository\ngit clone https://github.com/armand1m/gringobot.git\n\n# cd into it\ncd ./gringobot\n\n# (optional) in case you have nvm instead of node19 directly installed\nnvm install 19\nnvm use 19\n\n# install yarn package manager\nnpm install -g yarn\n\n# download project dependencies\nyarn\n```\n\nYou must have a Telegram Bot Token created by the Bot Father. Once you have that, run the following command with your bot token:\n\n```sh\ncat \u003e ./.env \u003c\u003cEOL\nNODE_ENV=development\nBOT_TOKEN=your-bot-token-here\nDATA_PATH=./data\nMESSAGE_TIMEOUT_ENABLED=true\nMESSAGE_TIMEOUT_IN_MINUTES=2\nHELP_COMMAND_ENABLED=true\nEOL\n```\n\nNow run `yarn dev` and your bot should be up with live reloading.\n\n## Deploying\n\n### Host\n\nFollow the same configuration step for development, but first override your .env with this: \n\n```sh\ncat \u003e ./.env \u003c\u003cEOL\nNODE_ENV=production\nBOT_TOKEN=your-bot-token-here\nDATA_PATH=./data\nMESSAGE_TIMEOUT_ENABLED=true\nMESSAGE_TIMEOUT_IN_MINUTES=2\nHELP_COMMAND_ENABLED=true\nEOL\n```\n\nthen build the application and start the process:\n\n```sh\nyarn build\nnode ./build/index.js\n```\n\nYou probably want to use a process manager like `systemd` or PM2.\n\n### Docker\n\nThis bot is published publicly as a Docker Image, so you should be able to run it anywhere you can run a Docker Container.\n\nTo run it locally, just run the following:\n\n```sh\n# create a volume to persist data\ndocker volume create gringobot_data\n\n# (optional) build image from source\ndocker build . -t armand1m/gringobot\n\n# run the container\ndocker run \\\n  -e BOT_TOKEN=\"your-bot-token-here\" \\\n  --mount source=gringobot_data,target=/app/data \\\n  armand1m/gringobot\n```\n\n### Kubernetes\n\n[Kubernetes manifests were available at the `./kubernetes` folder.](https://github.com/armand1m/gringobot/blob/d8bd8a2c8c6e9806a9041aa138e6e956cc3ac2b8/kubernetes/deployment.yml)\n\nAs of 2023, this application is now deployed on https://fly.io. I've kept this note for historical reasons.\n\n[Docs are here](https://github.com/armand1m/gringobot/blob/d8bd8a2c8c6e9806a9041aa138e6e956cc3ac2b8/README.md#kubernetes)\n\n### Fly\n\nThis bot is published in https://fly.io \n\nThe CI will take care of publishing the last main branch state into the official bot release.\n\nPublishing it in your instance should be easy:\n\n```sh\n# get credentials\nfly auth login\n\n# set bot token from @BotFather as a secret\n#\n# secrets in fly are automatically added to\n# the instance as env vars with the same name\nfly secrets set BOT_TOKEN=123123123:32132132131312\n\n# create a volume to hold persistent group data\n# 1gb is more than enough.\nfly vol create gringobot_data -s 1\n\n# ship it\nfly deploy\n```\n\nRefer to https://fly.io docs for more details on other commons operations.\n\n## Credits\n\nCredits goes to all the maintainers and participants of the Programando na Gringa group.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farmand1m%2Fgringobot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farmand1m%2Fgringobot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farmand1m%2Fgringobot/lists"}