# tgpromo
An asynchronous Python SDK for integrating your Telegram bot or service with the [tgpromo.org](https://tgpromo.org) advertising platform.
- 🚀 Supports Python 3.8 and above
- 🔐 Safe by design — robust error handling and health checks
- ⚡️ Minimal integration — just one method call to show ads
---
## 🔗 Useful Links
- **Website:** [tgpromo.org](https://tgpromo.org)
- **API Base URL:** https://api.tgpromo.org
- **Swagger / OpenAPI docs:** https://docs.api.tgpromo.org
- **Telegram Mini-App (bot):** [@tgpromo_bot](https://t.me/tgpromo_bot)
- **Telegram Channel:** [@tgpromo](https://t.me/tgpromo)
---
## 📦 Installation
```bash
pip install tgpromo
```
---
## ⚙️ Quick Start
To integrate your bot with tgpromo, simply call the ad impression method each time you receive a message from a user and want to show an ad.
This is the only required step — the method returns a flag indicating whether the impression was successfully sent.
If your bot responds quickly, you can show the ad **after** sending your reply.
```python
import asyncio
from tgpromo import PartnerClient, TGPromoException
async def main():
client = PartnerClient(token='YOUR_PARTNER_API_TOKEN')
try:
result = await client.ads.impressions.send(
user_id=123,
message_id=456
)
print('Impression sent: ', result.impression_sent)
except TGPromoException as e:
print('Impression send error: ', e)
# Clean up client when done
await client.aclose()
if __name__ == '__main__':
asyncio.run(main())
```
## 🤖 Example with aiogram
This example uses aiogram v3. It sends an ad impression when the /start command is received.
You can also show ads after any user interaction — for example, after completing a task or sending a message.
```python
import asyncio
from os import getenv
from aiogram import Bot, Dispatcher, html
from aiogram.client.default import DefaultBotProperties
from aiogram.enums import ParseMode
from aiogram.filters import CommandStart
from aiogram.types import Message
from tgpromo import PartnerClient, TGPromoException
# Bot token can be obtained via https://t.me/BotFather
BOT_TOKEN = getenv('BOT_TOKEN')
# Partner API token is available in the bot management panel (https://tgpromo.org or https://t.me/tgpromo_bot)
TGPROMO_PARTNER_API_TOKEN = getenv('TGPROMO_PARTNER_API_TOKEN')
dp = Dispatcher()
partner_client = PartnerClient(TGPROMO_PARTNER_API_TOKEN)
@dp.message(CommandStart())
async def command_start_handler(message: Message) -> None:
"""
Handle the /start command and attempt to send an ad impression.
"""
try:
result = await partner_client.ads.impressions.send(
user_id=message.from_user.id,
message_id=message.message_id
)
if not result.impression_sent:
print('Impression not sent - try another network or your own ad ;)')
except TGPromoException as e:
print('Impression send error: ', e)
await message.answer(f'Hello, {html.bold(message.from_user.full_name)}!')
async def main() -> None:
bot = Bot(token=BOT_TOKEN, default=DefaultBotProperties(parse_mode=ParseMode.HTML))
await dp.start_polling(bot)
if __name__ == '__main__':
asyncio.run(main())
```
---
## 🔒 Safety & Resilience Features
- Your service remains stable even if the tgpromo API becomes temporarily unreachable
- API requests are automatically paused during network outages or server errors
- Availability is automatically restored once API connectivity returns
- Raises `TGPromoException` for general errors, and `PartnerAPIException` for partner-specific issues
---
## 📝 License
This project is licensed under the MIT License – see the [LICENSE](./LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://tgpromo.org",
"name": "tgpromo",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "telegram, tgpromo, advertising, async, sdk, api, marketing",
"author": "tgpromo",
"author_email": "contact@tgpromo.org",
"download_url": "https://files.pythonhosted.org/packages/6c/9d/6b2df9a78fc00c5600c2a7b6ec7c1e7d04467868d72c23e290ff83615624/tgpromo-0.1.1.tar.gz",
"platform": null,
"description": "# tgpromo\n\nAn asynchronous Python SDK for integrating your Telegram bot or service with the [tgpromo.org](https://tgpromo.org) advertising platform.\n\n- \ud83d\ude80 Supports Python 3.8 and above \n- \ud83d\udd10 Safe by design \u2014 robust error handling and health checks \n- \u26a1\ufe0f Minimal integration \u2014 just one method call to show ads\n\n---\n\n## \ud83d\udd17 Useful Links\n\n- **Website:** [tgpromo.org](https://tgpromo.org)\n- **API Base URL:** https://api.tgpromo.org \n- **Swagger / OpenAPI docs:** https://docs.api.tgpromo.org \n- **Telegram Mini-App (bot):** [@tgpromo_bot](https://t.me/tgpromo_bot) \n- **Telegram Channel:** [@tgpromo](https://t.me/tgpromo)\n\n---\n\n## \ud83d\udce6 Installation\n\n```bash\npip install tgpromo\n```\n\n---\n\n## \u2699\ufe0f Quick Start\nTo integrate your bot with tgpromo, simply call the ad impression method each time you receive a message from a user and want to show an ad.\n\nThis is the only required step \u2014 the method returns a flag indicating whether the impression was successfully sent.\n\nIf your bot responds quickly, you can show the ad **after** sending your reply.\n\n\n```python\nimport asyncio\nfrom tgpromo import PartnerClient, TGPromoException\n\nasync def main():\n client = PartnerClient(token='YOUR_PARTNER_API_TOKEN')\n\n try:\n result = await client.ads.impressions.send(\n user_id=123,\n message_id=456\n )\n print('Impression sent: ', result.impression_sent)\n except TGPromoException as e:\n print('Impression send error: ', e)\n \n # Clean up client when done\n await client.aclose()\n\nif __name__ == '__main__':\n asyncio.run(main())\n```\n\n## \ud83e\udd16 Example with aiogram\nThis example uses aiogram v3. It sends an ad impression when the /start command is received.\n\nYou can also show ads after any user interaction \u2014 for example, after completing a task or sending a message.\n\n```python\nimport asyncio\nfrom os import getenv\n\nfrom aiogram import Bot, Dispatcher, html\nfrom aiogram.client.default import DefaultBotProperties\nfrom aiogram.enums import ParseMode\nfrom aiogram.filters import CommandStart\nfrom aiogram.types import Message\nfrom tgpromo import PartnerClient, TGPromoException\n\n\n# Bot token can be obtained via https://t.me/BotFather\nBOT_TOKEN = getenv('BOT_TOKEN')\n\n# Partner API token is available in the bot management panel (https://tgpromo.org or https://t.me/tgpromo_bot)\nTGPROMO_PARTNER_API_TOKEN = getenv('TGPROMO_PARTNER_API_TOKEN')\n\ndp = Dispatcher()\npartner_client = PartnerClient(TGPROMO_PARTNER_API_TOKEN)\n\n\n@dp.message(CommandStart())\nasync def command_start_handler(message: Message) -> None:\n \"\"\"\n Handle the /start command and attempt to send an ad impression.\n \"\"\"\n try:\n result = await partner_client.ads.impressions.send(\n user_id=message.from_user.id,\n message_id=message.message_id\n )\n\n if not result.impression_sent:\n print('Impression not sent - try another network or your own ad ;)')\n except TGPromoException as e:\n print('Impression send error: ', e)\n\n await message.answer(f'Hello, {html.bold(message.from_user.full_name)}!')\n\n\nasync def main() -> None:\n bot = Bot(token=BOT_TOKEN, default=DefaultBotProperties(parse_mode=ParseMode.HTML))\n await dp.start_polling(bot)\n\n\nif __name__ == '__main__':\n asyncio.run(main())\n```\n\n---\n\n## \ud83d\udd12 Safety & Resilience Features\n- Your service remains stable even if the tgpromo API becomes temporarily unreachable\n- API requests are automatically paused during network outages or server errors\n- Availability is automatically restored once API connectivity returns\n- Raises `TGPromoException` for general errors, and `PartnerAPIException` for partner-specific issues\n\n---\n\n## \ud83d\udcdd License\n\nThis project is licensed under the MIT License \u2013 see the [LICENSE](./LICENSE) file for details.",
"bugtrack_url": null,
"license": "MIT",
"summary": "Asynchronous SDK for integrating with the tgpromo.org API",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://tgpromo.org",
"Repository": "https://github.com/tgpromo/py-tgpromo"
},
"split_keywords": [
"telegram",
" tgpromo",
" advertising",
" async",
" sdk",
" api",
" marketing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ce0b93c4afae4ae5c5936e6d11551cc5e55bcf4e9d0c5a67efe44d512a820d5b",
"md5": "c81a8a8ed4837742cee012e4115c1aea",
"sha256": "8ab1239fcdb8a2e6f327ffde66c591a7a736139c9726c7a20c509df4d0a89ef3"
},
"downloads": -1,
"filename": "tgpromo-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c81a8a8ed4837742cee012e4115c1aea",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 9781,
"upload_time": "2025-07-18T00:07:22",
"upload_time_iso_8601": "2025-07-18T00:07:22.013879Z",
"url": "https://files.pythonhosted.org/packages/ce/0b/93c4afae4ae5c5936e6d11551cc5e55bcf4e9d0c5a67efe44d512a820d5b/tgpromo-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6c9d6b2df9a78fc00c5600c2a7b6ec7c1e7d04467868d72c23e290ff83615624",
"md5": "510b5d18094d5fafc5482d1f6cacd7d8",
"sha256": "caac941407a47503816cf5fcc3f85b481a478a5dae2591f31ff4ace4dc02680d"
},
"downloads": -1,
"filename": "tgpromo-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "510b5d18094d5fafc5482d1f6cacd7d8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 8022,
"upload_time": "2025-07-18T00:07:23",
"upload_time_iso_8601": "2025-07-18T00:07:23.617028Z",
"url": "https://files.pythonhosted.org/packages/6c/9d/6b2df9a78fc00c5600c2a7b6ec7c1e7d04467868d72c23e290ff83615624/tgpromo-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 00:07:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tgpromo",
"github_project": "py-tgpromo",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "tgpromo"
}
JSON
