{"id":48489493,"url":"https://github.com/cloudblue/telegram-django","last_synced_at":"2026-04-07T11:04:27.267Z","repository":{"id":40481964,"uuid":"352579826","full_name":"cloudblue/telegram-django","owner":"cloudblue","description":null,"archived":false,"fork":false,"pushed_at":"2022-05-05T15:15:02.000Z","size":67,"stargazers_count":5,"open_issues_count":1,"forks_count":4,"subscribers_count":7,"default_branch":"master","last_synced_at":"2026-03-15T22:41:20.252Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/cloudblue.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":"2021-03-29T09:04:19.000Z","updated_at":"2024-08-05T00:12:48.000Z","dependencies_parsed_at":"2022-08-09T21:50:19.270Z","dependency_job_id":null,"html_url":"https://github.com/cloudblue/telegram-django","commit_stats":null,"previous_names":["cloudblue/connect-telegram-bot"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/cloudblue/telegram-django","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudblue%2Ftelegram-django","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudblue%2Ftelegram-django/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudblue%2Ftelegram-django/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudblue%2Ftelegram-django/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudblue","download_url":"https://codeload.github.com/cloudblue/telegram-django/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudblue%2Ftelegram-django/sbom","scorecard":{"id":292369,"data":{"date":"2025-08-11","repo":{"name":"github.com/cloudblue/telegram-django","commit":"c1455dd53beac27e91a571ab470612a22a828773"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.2,"checks":[{"name":"Code-Review","score":8,"reason":"Found 14/16 approved changesets -- score normalized to 8","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/build.yml:1","Warn: no topLevel permission defined: .github/workflows/deploy.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/cloudblue/telegram-django/build.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/cloudblue/telegram-django/build.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/build.yml:42: update your workflow using https://app.stepsecurity.io/secureworkflow/cloudblue/telegram-django/build.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/deploy.yml:11: update your workflow using https://app.stepsecurity.io/secureworkflow/cloudblue/telegram-django/deploy.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/deploy.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/cloudblue/telegram-django/deploy.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/deploy.yml:28: update your workflow using https://app.stepsecurity.io/secureworkflow/cloudblue/telegram-django/deploy.yml/master?enable=pin","Warn: pipCommand not pinned by hash: .github/workflows/build.yml:28","Warn: pipCommand not pinned by hash: .github/workflows/build.yml:29","Warn: pipCommand not pinned by hash: .github/workflows/deploy.yml:18","Warn: pipCommand not pinned by hash: .github/workflows/deploy.yml:19","Info:   0 out of   5 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   1 third-party GitHubAction dependencies pinned","Info:   0 out of   4 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 28 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":0,"reason":"29 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: PYSEC-2024-230 / GHSA-248v-346w-9cwc","Warn: Project is vulnerable to: PYSEC-2022-42986 / GHSA-43fp-rhv2-5gv8","Warn: Project is vulnerable to: PYSEC-2023-135 / GHSA-xqr8-7jwr-rhp7","Warn: Project is vulnerable to: PYSEC-2023-13 / GHSA-2hrw-hx67-34x6","Warn: Project is vulnerable to: PYSEC-2023-225 / GHSA-7h4p-27mh-hmrw","Warn: Project is vulnerable to: GHSA-7xr5-9hcq-chf9","Warn: Project is vulnerable to: PYSEC-2022-245 / GHSA-8x94-hmjh-97hq","Warn: Project is vulnerable to: PYSEC-2023-226 / GHSA-h8gc-pgj2-vjm3","Warn: Project is vulnerable to: PYSEC-2023-100 / GHSA-jh3w-4vvf-mjgr","Warn: Project is vulnerable to: PYSEC-2022-213 / GHSA-p64x-8rxx-wf6q","Warn: Project is vulnerable to: PYSEC-2023-12 / GHSA-q2jf-h9jm-m7p4","Warn: Project is vulnerable to: PYSEC-2023-222 / GHSA-qmf9-6jqf-j8fq","Warn: Project is vulnerable to: PYSEC-2022-304 / GHSA-qrw5-5h28-6cmg","Warn: Project is vulnerable to: PYSEC-2023-61 / GHSA-r3xc-prgr-mg9p","Warn: Project is vulnerable to: GHSA-rrqc-c2jx-6jgv","Warn: Project is vulnerable to: PYSEC-2024-47 / GHSA-vm8q-m57g-pff3","Warn: Project is vulnerable to: PYSEC-2024-28 / GHSA-xxj9-f6rv-m3x4","Warn: Project is vulnerable to: GHSA-gw84-84pc-xp82","Warn: Project is vulnerable to: GHSA-29gw-9793-fvw7","Warn: Project is vulnerable to: PYSEC-2022-42969","Warn: Project is vulnerable to: PYSEC-2023-117 / GHSA-mrwq-x4v8-fh7p","Warn: Project is vulnerable to: GHSA-2m57-hf25-phgg","Warn: Project is vulnerable to: PYSEC-2023-87 / GHSA-rrm6-wvj7-cwh2","Warn: Project is vulnerable to: GHSA-753j-mpmx-qq6g","Warn: Project is vulnerable to: GHSA-7cx3-6m66-7c5m","Warn: Project is vulnerable to: GHSA-8w49-h785-mj3c","Warn: Project is vulnerable to: PYSEC-2023-75 / GHSA-hj3f-6gcp-jg8j","Warn: Project is vulnerable to: GHSA-qppv-j76h-2rpx","Warn: Project is vulnerable to: GHSA-w235-7p84-xx57"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-17T18:35:58.182Z","repository_id":40481964,"created_at":"2025-08-17T18:35:58.183Z","updated_at":"2025-08-17T18:35:58.183Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31509946,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":[],"created_at":"2026-04-07T11:04:21.914Z","updated_at":"2026-04-07T11:04:27.261Z","avatar_url":"https://github.com/cloudblue.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Django Telegram Bot\n\n![pyversions](https://img.shields.io/pypi/pyversions/telegram-django.svg) [![PyPi Status](https://img.shields.io/pypi/v/telegram-django.svg)](https://pypi.org/project/telegram-django/) [![Build Django Telegram Bot](https://github.com/cloudblue/telegram-django/actions/workflows/build.yml/badge.svg)](https://github.com/cloudblue/telegram-django/actions/workflows/build.yml) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=telegram-django\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=telegram-django) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=telegram-django\u0026metric=coverage)](https://sonarcloud.io/dashboard?id=telegram-django) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=telegram-django\u0026metric=sqale_rating)](https://sonarcloud.io/dashboard?id=telegram-django)\n\n## Introduction\n\n`Django Telegram Bot` is the base class which helps to build custom commands for the django models. It allows getting historical data from django models, as well as develop custom pre-defined filters and execute custom django management commands (i.e. those which are executed through  `python manage.py $command`)\n\n## Install\n\n`Django Telegram Bot` requires python 3.8 or later and has the following dependencies:\n\n* python-telegram-bot \u003e=13.3\n* django\u003e=2.2.20\n\n`Django Telegram Bot` can be installed from [pypi.org](https://pypi.org/project/telegram-django/) using pip:\n\n```\n$ pip install telegram-django\n```\n\n## Running The Bot\n### Define your command class extending the base\n\nFor example:\n\n``` \n\nfrom myapp.models import MyAppModel\n\nfrom telegram_bot.telegram_conversation import TelegramConversation\n\n\nclass MyAppConversation(TelegramConversation):\n    def __init__(self, logger, model_datetime_property, suffix):\n        super().__init__(logger, model_datetime_property, suffix)\n        self.model = MyAppModel\n\n    @property\n    def custom_commands(self):\n        return [\n            'custom_command1',\n        ]\n        \n    @property\n    def saved_filters(self):\n        return [\n            'count',\n        ]\n\n    def get_count(self, update):\n        amount = self._get_initial_queryset().count()\n        self._reply(update, amount)\n        self._default_query_context()\n\n\n```\n\nThe method ```custom_commands``` must return a list of defined django commands which can be executed by this conversation handler. These commands are standard django commands which are normally executed via ```python manage.py $command```.\nThe method ```saved_filters``` must return a list of defined custom filters. The filter's body must be implemented in the same class using the convention ```get_$filter_name```, like in the example above: for ```count``` filter the ```get_count``` method is implemented.\n\nAdd the following sections to your ```settings.py```:\n\nDefine application in ```INSTALLED_APPS```\n```\n    INSTALLED_APPS = [\n        ...\n        'django_telegram',\n        ...\n    ]\n```\nAdd section ```TELEGRAM_BOT``` for bot configuration\n```\nTELEGRAM_BOT = {\n    'CONVERSATIONS': [\n        'myapp.package1.package2.MyAppConversation',\n    ],\n    'TOKEN': '',\n    'COMMANDS_SUFFIX': None,\n    'HISTORY_LOOKUP_MODEL_PROPERTY': ''\n}\n```\nAdd section ```django_telegram_bot``` to logger configuration\n```\nLOGGING = {\n...\n    'loggers': {\n...\n        'django_telegram_bot': {\n            'handlers': ['console'],\n            'level': 'INFO',\n        },\n...\n    },\n...\n}\n```\n\nSettings description:\n\n| Variable      | Description  |\n| ------------- |:-------------|\n|`TOKEN`|Telegram Token for the bot. Please refer to https://core.telegram.org/bots on how to create a bot.|\n|`CONVERSATIONS`|List of FQDNs for classes which implement and provide conversation instances|\n|`HISTORY_LOOKUP_MODEL_PROPERTY`|Property of the django model of DateTime type which is used to do history lookups|\n|`COMMANDS_SUFFIX`|In case of having multiple instances of the bot (with the same commands) we want to add some suffix to the commands, so that only specific bot is getting the command, so command becomes `myappconversation_${SUFFIX}`. If there is no need to have multiple instances of the same bot in the chat -- just leave this as ```None```. |\n\n### Running The Bot\n\n`python manage.py start_bot`\n\n## Middleware\nThe library also provides a way to analyse **responses of type application/json** and based on defined rules send pre-defined messages.\nTo enable middleware add the following line into your ```settings.MIDDLEWARE```\n```\nMIDDLEWARE = [\n...\n    'django_telegram.bot.middleware.TelegramMiddleware',\n]\n```\n\nExtend previously defined configuration in ```settings.py``` with the following\n```\nTELEGRAM_BOT = {\n    'CONVERSATIONS': [\n        'myapp.package1.package2.MyAppConversation',\n    ],\n    'TOKEN': '',\n    'COMMANDS_SUFFIX': None,\n    'HISTORY_LOOKUP_MODEL_PROPERTY': '',\n    'MIDDLEWARE': {\n        'CHAT_ID': -12356789,\n        'RULES': [{\n            'view': 'view',\n            'trigger_codes': [204, 200],\n            'conditions': {\n                'type': 'value',\n                'field': 'field',\n                'field_value': 'value',\n            },\n            'message': 'Message when this condition happened!',\n        }],\n    }\n}\n```\nSettings description:\n\n| Variable      | Description  |\n| ------------- |:-------------|\n|`CHAT_ID`|Telegram chat id to where the bot must send messages. Typically an integer like ```-12345677898```|\n|`RULES`|List of rules objects which configure a case when message must be sent|\n|`RULES[i].view`|View id in resolver definition, i.e. ```/v1/reports/fail/123``` URI would be a ```reports-fail```|\n|`RULES[i].trigger_codes`|List of HTTP codes in response where this rule needs to be triggered|\n|`RULES[i].conditions`|Optional. Additional checks which need to be done before sending the message|\n|`RULES[i].conditions.type`|Type of condition, can be either 'function' (when validation is done by user defined function) or 'value' (when validation is done by simple field/value comparison of response JSON).|\n|`RULES[i].conditions.function`|Required if `RULES[i].conditions.type` is `function` otherwise ignored. User defined function which receives as input response JSON as dict and must return either `True` or `False`|\n|`RULES[i].conditions.field`|Required if `RULES[i].conditions.type` is `value` otherwise ignored. Field to look up in response JSON|\n|`RULES[i].conditions.field_value`|Required if `RULES[i].conditions.type` is `value` otherwise ignored. Expected value to look up in response JSON|\n|`RULES[i].message`|Message which needs to be sent to Telegram in case all conditions match|\n\n\n## Testing\n\n* Create virtualenv\n* Install project dependencies\n```commandline\npython -m pip install --upgrade pip\npip install poetry\npoetry update\n```\n* Run tests\n```commandline\npoetry run pytest\n```\n\n\n## License\n\n``Django Telegram Bot`` is released under the [Apache License Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudblue%2Ftelegram-django","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudblue%2Ftelegram-django","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudblue%2Ftelegram-django/lists"}