{"id":28882000,"url":"https://github.com/ronihdzz/telegram-connector","last_synced_at":"2026-05-03T01:41:24.111Z","repository":{"id":296605192,"uuid":"993920245","full_name":"ronihdzz/telegram-connector","owner":"ronihdzz","description":"A comprehensive solution for integrating applications with Telegram bots, enabling bidirectional communication to send and receive messages.","archived":false,"fork":false,"pushed_at":"2025-06-14T23:41:43.000Z","size":202,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"feat/telegram-connector","last_synced_at":"2025-10-27T08:42:05.340Z","etag":null,"topics":["api","connector","docker","fastapi","integration","postgresql","python","rest-api","telegram","telegram-bot","webhook"],"latest_commit_sha":null,"homepage":"https://ronihdz.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ronihdzz.png","metadata":{"files":{"readme":"README.es.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-31T20:05:38.000Z","updated_at":"2025-06-13T22:55:32.000Z","dependencies_parsed_at":"2025-06-20T20:42:08.907Z","dependency_job_id":"f42afa0a-57fd-4a97-b450-10d0de5ce26f","html_url":"https://github.com/ronihdzz/telegram-connector","commit_stats":null,"previous_names":["ronihdzz/telgram-connector"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ronihdzz/telegram-connector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronihdzz%2Ftelegram-connector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronihdzz%2Ftelegram-connector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronihdzz%2Ftelegram-connector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronihdzz%2Ftelegram-connector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ronihdzz","download_url":"https://codeload.github.com/ronihdzz/telegram-connector/tar.gz/refs/heads/feat/telegram-connector","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronihdzz%2Ftelegram-connector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32555839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T00:31:16.350Z","status":"ssl_error","status_checked_at":"2026-05-03T00:31:15.546Z","response_time":132,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":["api","connector","docker","fastapi","integration","postgresql","python","rest-api","telegram","telegram-bot","webhook"],"created_at":"2025-06-20T20:41:52.901Z","updated_at":"2026-05-03T01:41:24.081Z","avatar_url":"https://github.com/ronihdzz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 Telegram Connector\n\n**Language / Idioma:**\n* [English](README.md) \n* [Español](README.es.md)\n\n---\n\n| Entorno CI | Cobertura |\n|-----------|----------|\n| development| ![Coverage Badge](https://github.com/ronihdzz/telegram-connector/blob/artifacts/development/latest/coverage.svg) \n\n\n## 📋 Descripción\n\n**Telegram Connector** es una solución integral que permite a las aplicaciones integrarse seamlessly con bots de Telegram, habilitando tanto la **recepción de mensajes entrantes** como el **envío de mensajes salientes** a través de cualquier bot registrado en la plataforma.\n\n### ✨ Características Principales\n\n- 🔄 **Comunicación Bidireccional**: Recibe y envía mensajes desde/hacia Telegram\n- 🎯 **Multi-Bot Support**: Gestiona múltiples bots por usuario\n- 📡 **Webhooks Automatizados**: Configuración automática de webhooks con Telegram\n- 🛡️ **Autenticación Robusta**: Validación de API Keys y secret tokens\n- 📊 **Logging Detallado**: Trazabilidad completa de mensajes y operaciones\n- 🐳 **Docker Ready**: Despliegue containerizado con docker-compose\n\n## 🏗️ Arquitectura del Sistema\n\n### Flujo de Datos\n\n```mermaid\nsequenceDiagram\n    participant User as \"Usuario/Sistema\"\n    participant API as \"API REST\"\n    participant DB as \"PostgreSQL\"\n    participant TG as \"API Telegram\" \n    participant Bot as \"Bot Telegram\"\n    participant Webhook as \"Sistema Destino\"\n    \n    Note over User,Webhook: Flujo de Registro de Bot\n    User-\u003e\u003e+API: POST /v1/telegram/connect\u003cbr/\u003e(bot_user_name, bot_token)\n    API-\u003e\u003e+DB: Crear TelegramConnector\u003cbr/\u003e(credenciales + secret_token)\n    DB-\u003e\u003e-API: Conector creado\n    API-\u003e\u003e+TG: setWebhook\u003cbr/\u003e(webhook_url + secret_token)\n    TG-\u003e\u003e-API: Webhook configurado\n    API-\u003e\u003e-User: Conector registrado exitosamente\n    \n    Note over User,Webhook: Flujo de Mensaje Entrante\n    Bot-\u003e\u003e+TG: Usuario envía mensaje al bot\n    TG-\u003e\u003e+API: POST /v1/telegram/webhook/{id}\u003cbr/\u003e(mensaje + secret_token)\n    API-\u003e\u003e+DB: Validar conector por ID\n    DB-\u003e\u003e-API: Conector válido\n    API-\u003e\u003eAPI: Procesar mensaje\u003cbr/\u003e(extraer texto, chat_id, etc.)\n    API-\u003e\u003e+Webhook: POST webhook_url\u003cbr/\u003e(mensaje procesado)\n    Webhook-\u003e\u003e-API: Mensaje recibido\n    API-\u003e\u003e-TG: Status OK\n    \n    Note over User,Webhook: Flujo de Mensaje Saliente\n    User-\u003e\u003e+API: POST /v1/telegram/send/{id}\u003cbr/\u003e(chat_id, text)\n    API-\u003e\u003e+DB: Validar conector y permisos\n    DB-\u003e\u003e-API: Conector válido\n    API-\u003e\u003e+TG: sendMessage\u003cbr/\u003e(bot_token, chat_id, text)\n    TG-\u003e\u003e+Bot: Entregar mensaje al usuario\n    Bot-\u003e\u003e-TG: Mensaje entregado\n    TG-\u003e\u003e-API: message_id de confirmación\n    API-\u003e\u003e-User: Mensaje enviado exitosamente\n```\n\n### Componentes del Sistema\n\n#### 🎯 Capa API (`api/v1/telegram/`)\n- **endpoints.py**: Exposición de APIs REST para operaciones de Telegram\n- **services.py**: Lógica de negocio para conectar, enviar y recibir mensajes\n- **repositories.py**: Capa de acceso a datos para operaciones CRUD\n- **schema.py**: Modelos de datos y validación con Pydantic\n\n#### 🗄️ Capa de Datos (`db/postgres/`)\n- **telegram_connectors.py**: Modelo de base de datos para gestión de bots\n\n## 📊 Modelo de Datos\n\n### TelegramConnector\n\nTabla principal que almacena la información de los bots conectados:\n\n| Campo | Tipo | Descripción |\n|-------|------|-------------|\n| `id` | UUID | Identificador único del conector |\n| `user_id` | UUID | ID del usuario propietario del bot |\n| `bot_user_name` | String | Nombre de usuario del bot (@ejemplo_bot) |\n| `bot_token` | String | Token de API del bot |\n| `bot_token_secret` | String | Token secreto para validación de webhooks |\n| `created_at` | DateTime | Fecha de creación |\n| `updated_at` | DateTime | Fecha de última actualización |\n\n## 🔌 Endpoints de la API\n\n### 1. Conectar Bot de Telegram\n\n**`POST /v1/telegram/connect`**\n\nRegistra un nuevo bot de Telegram y configura su webhook automáticamente.\n\n**Headers:**\n```json\n{\n  \"X-Api-Key\": \"tu_api_key_aqui\",\n  \"X-User-Id\": \"uuid_del_usuario\"\n}\n```\n\n**Request Body:**\n```json\n{\n  \"bot_user_name\": \"@mi_bot\",\n  \"bot_token\": \"123456789:ABCdefGHIjklMNOpqrsTUVwxyz\"\n}\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"user_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n    \"bot_user_name\": \"@mi_bot\",\n    \"created_at\": \"2024-01-15T10:30:00Z\",\n    \"updated_at\": \"2024-01-15T10:30:00Z\"\n  }\n}\n```\n\n### 2. Webhook para Mensajes Entrantes\n\n**`POST /v1/telegram/webhook/{telegram_connector_id}`**\n\nEndpoint automáticamente configurado por Telegram para recibir mensajes. Telegram envía un objeto `Update` completo en el body del request.\n\n**Headers:**\n```json\n{\n  \"Content-Type\": \"application/json\",\n  \"X-Telegram-Bot-Api-Secret-Token\": \"token_secreto_generado\"\n}\n```\n\n**Request Body (enviado por Telegram):**\n```json\n{\n  \"update_id\": 10000,\n  \"message\": {\n    \"message_id\": 1365,\n    \"date\": 1441645532,\n    \"chat\": {\n      \"id\": 1111111,\n      \"type\": \"private\",\n      \"first_name\": \"Test\",\n      \"last_name\": \"Test Lastname\",\n      \"username\": \"Test\"\n    },\n    \"from\": {\n      \"id\": 1111111,\n      \"is_bot\": false,\n      \"first_name\": \"Test\",\n      \"last_name\": \"Test Lastname\",\n      \"username\": \"Test\"\n    },\n    \"text\": \"¡Hola desde Telegram!\"\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"status\": \"ok\"\n}\n```\n\n### 3. Enviar Mensaje\n\n**`POST /v1/telegram/send/{telegram_connector_id}`**\n\nEnvía un mensaje a través del bot especificado.\n\n**Headers:**\n```json\n{\n  \"X-Api-Key\": \"tu_api_key_aqui\",\n  \"X-User-Id\": \"uuid_del_usuario\"\n}\n```\n\n**Request Body:**\n```json\n{\n  \"chat_id\": 123456789,\n  \"text\": \"¡Hola! Este es un mensaje desde la API\"\n}\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"telegram_message_id\": 987654321,\n    \"status\": \"sent\"\n  }\n}\n```\n\n## ⚙️ Variables de Entorno\n\n### Variables Requeridas\n\n```bash\n# Configuración General\nENVIRONMENT=local                              # Entorno de ejecución\nHOST=http://localhost:8000                     # URL base de la API\nAPI_KEY=tu_api_key_super_secreto              # Clave API para autenticación\n\n# Base de Datos\nPOSTGRESQL_URL=postgresql://user:password@localhost:5432/telegram_connector\n\n# Webhook de Destino\nWEBHOOK_MESSAGE_RECEIVED=https://tu-app.com/api/webhook/telegram-message\n```\n\n### Variables Opcionales\n\n```bash\n# Logging y Monitoreo\nSENTRY_DSN=https://tu-sentry-dsn.com           # Para tracking de errores\nTIME_ZONE=America/Mexico_City                  # Zona horaria\n\n# Configuración del Proyecto\nPROJECT__NAME=Telegram Connector\nPROJECT__VERSION=1.0.0\nPROJECT__DESCRIPTION=API para integración con Telegram\n```\n\n## 🚀 Instalación y Configuración\n\n### Prerrequisitos\n\n- Python 3.12+\n- PostgreSQL\n- Docker y Docker Compose (opcional)\n\n### Instalación con Poetry\n\n1. **Clonar el repositorio:**\n```bash\ngit clone https://github.com/ronihdzz/telegram-connector.git\ncd telegram-connector\n```\n\n2. **Instalar dependencias:**\n```bash\npoetry install\n```\n\n3. **Configurar variables de entorno:**\n```bash\ncp .envs/.example.env .envs/.local.env\n# Editar .envs/.local.env con tu configuración\n```\n\n4. **Ejecutar la aplicación:**\n```bash\npoetry run uvicorn src.main:app --reload --host 0.0.0.0 --port 8000\n```\n\n### Instalación con Docker\n\n1. **Clonar y ejecutar:**\n```bash\ngit clone https://github.com/ronihdzz/telegram-connector.git\ncd telegram-connector\ndocker-compose up -d\n```\n\n## 📖 Ejemplos de Uso\n\n### 1. Registrar un Bot\n\n```python\nimport requests\n\n# Configuración\nAPI_BASE = \"http://localhost:8000/v1\"\nAPI_KEY = \"tu_api_key\"\nUSER_ID = \"550e8400-e29b-41d4-a716-446655440001\"\n\n# Registrar bot\nresponse = requests.post(\n    f\"{API_BASE}/telegram/connect\",\n    headers={\n        \"X-Api-Key\": API_KEY,\n        \"X-User-Id\": USER_ID\n    },\n    json={\n        \"bot_user_name\": \"@mi_bot_de_prueba\",\n        \"bot_token\": \"123456789:ABCdefGHIjklMNOpqrsTUVwxyz\"\n    }\n)\n\nbot_data = response.json()\nconnector_id = bot_data[\"data\"][\"id\"]\nprint(f\"Bot registrado con ID: {connector_id}\")\n```\n\n### 2. Enviar un Mensaje\n\n```python\n# Enviar mensaje usando el bot registrado\nresponse = requests.post(\n    f\"{API_BASE}/telegram/send/{connector_id}\",\n    headers={\n        \"X-Api-Key\": API_KEY,\n        \"X-User-Id\": USER_ID\n    },\n    json={\n        \"chat_id\": 123456789,  # ID del chat destino\n        \"text\": \"¡Hola desde mi aplicación!\"\n    }\n)\n\nresult = response.json()\nprint(f\"Mensaje enviado con ID: {result['data']['telegram_message_id']}\")\n```\n\n### 3. Configurar Webhook de Destino\n\nPara recibir mensajes entrantes, configura un endpoint en tu aplicación:\n\n```python\nfrom fastapi import FastAPI, Request\n\napp = FastAPI()\n\n@app.post(\"/api/webhook/telegram-message\")\nasync def receive_telegram_message(request: Request):\n    \"\"\"\n    Webhook que recibe mensajes entrantes de Telegram\n    \"\"\"\n    data = await request.json()\n    \n    print(f\"Mensaje recibido de {data['bot_user_name']}\")\n    print(f\"Chat ID: {data['chat_id']}\")\n    print(f\"Texto: {data['text']}\")\n    print(f\"Usuario: {data['user_id']}\")\n    \n    # Procesar el mensaje aquí...\n    \n    return {\"status\": \"processed\"}\n```\n\n## 📚 Documentación Adicional\n\n### Documentación de la API\n\nUna vez ejecutándose la aplicación, accede a:\n- **Swagger UI**: `http://localhost:8000/docs`\n- **ReDoc**: `http://localhost:8000/redoc`\n\n### Estructura del Proyecto\n\n```\ntelegram-connector/\n├── src/\n│   ├── api/v1/telegram/          # Endpoints de la API REST\n│   ├── db/postgres/models/       # Modelos de base de datos\n│   ├── core/settings/            # Configuración de la aplicación\n│   ├── shared/                   # Utilidades compartidas\n│   └── tests/                    # Suites de pruebas\n├── docker_images/                # Configuraciones Docker\n├── .envs/                        # Variables de entorno\n└── docs/                         # Documentación adicional\n```\n\n## 🧪 Pruebas\n\nEjecutar la suite de pruebas:\n\n```bash\n# Con Poetry\npoetry run pytest\n\n# Con cobertura\npoetry run pytest --cov=src --cov-report=html\n```\n\n## 🤝 Contribuciones\n\n1. Haz fork del proyecto\n2. Crea tu rama de feature (`git checkout -b feature/CaracteristicaIncreible`)\n3. Confirma tus cambios (`git commit -m 'Agregar alguna CaracteristicaIncreible'`)\n4. Sube a la rama (`git push origin feature/CaracteristicaIncreible`)\n5. Abre un Pull Request\n\n\n## 👨‍💻 Autor\n\n**Ronaldo Hernández** - [@ronihdzz](https://github.com/ronihdzz)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**¿Te gusta el proyecto? ¡Dale una ⭐!**\n\n[🐛 Reportar Bug](https://github.com/ronihdzz/telegram-connector/issues) • [✨ Solicitar Feature](https://github.com/ronihdzz/telegram-connector/issues) • [💬 Discusiones](https://github.com/ronihdzz/telegram-connector/discussions)\n\n\u003c/div\u003e ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronihdzz%2Ftelegram-connector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fronihdzz%2Ftelegram-connector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronihdzz%2Ftelegram-connector/lists"}