{"id":25487830,"url":"https://github.com/rameerez/telegrama","last_synced_at":"2026-01-17T22:24:37.693Z","repository":{"id":278111224,"uuid":"934548702","full_name":"rameerez/telegrama","owner":"rameerez","description":"💬 Send Telegram admin notifications in your Rails app","archived":false,"fork":false,"pushed_at":"2026-01-17T01:57:42.000Z","size":126,"stargazers_count":20,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-17T13:36:11.310Z","etag":null,"topics":["admin","administration","log","logging","notification","notifications","rails","ruby","ruby-gem","ruby-on-rails","summary","telegram","telegram-api","telegram-bot","telegram-bot-api","telegram-bots"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rameerez.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-02-18T02:43:04.000Z","updated_at":"2026-01-17T01:55:59.000Z","dependencies_parsed_at":"2025-02-18T13:18:03.064Z","dependency_job_id":"83ae4762-f750-4b4f-8fb5-22e1e38dfeaa","html_url":"https://github.com/rameerez/telegrama","commit_stats":null,"previous_names":["rameerez/telegrams","rameerez/telegrama"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/rameerez/telegrama","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameerez%2Ftelegrama","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameerez%2Ftelegrama/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameerez%2Ftelegrama/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameerez%2Ftelegrama/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rameerez","download_url":"https://codeload.github.com/rameerez/telegrama/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameerez%2Ftelegrama/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28520326,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T22:11:28.393Z","status":"ssl_error","status_checked_at":"2026-01-17T22:11:27.841Z","response_time":85,"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":["admin","administration","log","logging","notification","notifications","rails","ruby","ruby-gem","ruby-on-rails","summary","telegram","telegram-api","telegram-bot","telegram-bot-api","telegram-bots"],"created_at":"2025-02-18T20:28:10.342Z","updated_at":"2026-01-17T22:24:37.687Z","avatar_url":"https://github.com/rameerez.png","language":"Ruby","readme":"# 💬 `telegrama` – Send Telegram admin notifications in your Rails app\n\n[![Gem Version](https://badge.fury.io/rb/telegrama.svg)](https://badge.fury.io/rb/telegrama) [![Build Status](https://github.com/rameerez/telegrama/workflows/Tests/badge.svg)](https://github.com/rameerez/telegrama/actions)\n\n\u003e [!TIP]\n\u003e **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=telegrama)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go [check it out](https://railsfast.com/?ref=telegrama)!\n\n`telegrama` lets you send quick, simple admin / logging Telegram messages via a Telegram bot.\n\nUseful for Rails developers using Telegram messages for notifications, admin alerts, errors, logs, daily summaries, and status updates, like:\n\n```ruby\nTelegrama.send_message(\"Important admin notification!\")\n```\n\nI use it all the time to alert me of new sales, important notifications, and daily summaries, like this:\n\n\u003e 💸 **New sale!**\n\u003e \n\u003e joh...e@gmail.com paid **$49.99** for Business Plan.\n\u003e \n\u003e 📈 MRR: $12,345\n\u003e \n\u003e 📈 Total customers: 1,234\n\u003e \n\u003e [🔗 View purchase details](https://example.com/admin/subscriptions/123)\n\nWhich is a beautifully formatted message you'll in Telegram with only this:\n\n```ruby\nmessage = \u003c\u003c~MSG\n  💸 *New sale\\!* \n  \n  #{customer.email} paid *$#{amount}* for #{product.name}\\.\n  \n  📈 MRR: $#{Profitable.mrr}\n  📈 Total customers: $#{Profitable.total_customers}\n  \n  [🔗 View purchase details](#{admin_subscription_url(subscription)})\nMSG\n\nTelegrama.send_message(message, formatting: { obfuscate_emails: true })\n```\n\nNote how the email gets redacted automatically to avoid leaking personal information (`john.doe@gmail.com` -\u003e `joh...e@gmail.com`)\n\nThe gem sanitizes weird characters, you can also escape Markdown, HTML, etc.\n\nFor the MRR and revenue metrics you can use my gem [`profitable`](https://github.com/rameerez/profitable); and if you have different group chats for marketing, management, etc. you can send different messages with different information to each of them:\n\n```ruby\nTelegrama.send_message(a_general_message, chat_id: general_chat_id)\nTelegrama.send_message(marketing_message, chat_id: marketing_chat_id)\n```\n\nThe goal with this gem is to provide a straightforward, no-frills, minimal API to send Telegram messages reliably for admin purposes, without you having to write your own wrapper over the Telegram API.\n\n## Quick start\n\nAdd telegrama to your Gemfile:\n\n```ruby\ngem 'telegrama'\n```\n\nThen run:\n\n```bash\nbundle install\n```\n\nThen, create an initializer file under `config/initializers/telegrama.rb` and set your credentials:\n\n```ruby\nTelegrama.configure do |config|\n  config.bot_token = Rails.application.credentials.dig(Rails.env.to_sym, :telegram, :bot_token)\n  config.chat_id   = Rails.application.credentials.dig(Rails.env.to_sym, :telegram, :chat_id)\n  config.default_parse_mode = 'MarkdownV2'\n  \n  # Optional prefix/suffix for all messages (useful to identify messages from different apps or environments)\n  config.message_prefix = nil  # Will be prepended to all messages if set\n  config.message_suffix = nil  # Will be appended to all messages if set\n  \n  # Default formatting options\n  config.formatting_options = {\n    escape_markdown: true,    # Escape markdown special characters\n    obfuscate_emails: false,  # Off by default, enable if needed (it anonymizes email addresses in the message to things like abc...d@gmail.com)\n    escape_html: false,       # Optionally escape HTML characters\n    truncate: 4096            # Truncate if message exceeds Telegram's limit (or a custom limit)\n  }\n\n  # HTTP client options\n  config.client_options = {\n    timeout: 30,               # HTTP request timeout in seconds (default: 30s)\n    retry_count: 3,            # Number of retries for failed requests (default: 3)\n    retry_delay: 1             # Delay between retries in seconds (default: 1s)\n  }\n\n  config.deliver_message_async = false           # Enable async message delivery with ActiveJob (enqueue the send_message call to offload message sending from the request cycle)\n  config.deliver_message_queue = 'default'       # Use a custom ActiveJob queue\nend\n```\n\nDone!\n\nYou can now send Telegram messages using your bot:\n\n```ruby\nTelegrama.send_message(\"Hey, this is your Rails app speaking via Telegram!\")\n```\n\n## Advanced options\n\n### Obfuscate emails in the message\n\nSometimes you want to report user actions including a sufficiently identifiable but otherwise anonymous user email. For example, when someone makes gets a refund, you may want to send a message like `john.doe21@email.com got refunded $XX.XX` – but there may be other people / employees in the group chat, so instead of leaking personal, private information, just turn on the `obfuscate_emails` option and the message will automatically get formatted as: `joh...1@email.com got refunded $XX.XX`\n\n### Overriding defaults with options\n\nYou can pass an options hash to `Telegrama.send_message` to override default behavior on a per‑message basis:\n\n### Message Prefix and Suffix\n\nYou may have multiple applications sending messages to the same Telegram group chat, and it can be hard to identify which message came from which application. Using message prefixes and suffixes, you can easily label messages from different sources:\n\n```ruby\n# Label which environment this message is coming from\nconfig.message_prefix = \"[#{Rails.env}] \\n\"\n\n# Or for different applications:\nconfig.message_prefix = \"[🛍️ Shop App] \\n\"\nconfig.message_suffix = \"\\n--\\nSent from Shop App\"\n\nconfig.message_prefix = \"[📊 Analytics] \\n\"\nconfig.message_suffix = \"\\n--\\nSent from Analytics\"\n```\n\nThis way, when multiple applications send messages to the same chat, you'll see:\n```\n[🛍️ Shop App] \nNew order received: $99.99\n--\nSent from Shop App\n\n[📊 Analytics] \nDaily Report: 150 new users today\n--\nSent from Analytics\n```\n\nBoth `message_prefix` and `message_suffix` are optional and can be used independently. They're particularly useful for:\n- Distinguishing between staging and production environments\n- Identifying messages from different microservices\n- Adding environment-specific tags or warnings\n- Including standardized footers or timestamps\n\n### `send_message` options\n\n- **`chat_id`**\n  *Override the default chat ID set in your configuration.*\n  **Usage Example:**\n  ```ruby\n  Telegrama.send_message(\"Hello, alternate group!\", chat_id: alternate_chat_id)\n  ```\n\n- **`parse_mode`**\n  *Override the default parse mode (default is `\"MarkdownV2\"`).*\n  **Usage Example:**\n  ```ruby\n  Telegrama.send_message(\"Hello, world!\", parse_mode: \"HTML\")\n  ```\n\n- **`disable_web_page_preview`**\n  *Enable or disable web page previews (default is `true`).*\n  **Usage Example:**\n  ```ruby\n  Telegrama.send_message(\"Check out this link: https://example.com\", disable_web_page_preview: false)\n  ```\n\n- **`formatting`**\n  *A hash that overrides the default formatting options provided in the configuration. Available keys include:*\n  - `escape_markdown` (Boolean): Automatically escape Telegram Markdown special characters.\n  - `obfuscate_emails` (Boolean): Obfuscate email addresses found in the message.\n  - `escape_html` (Boolean): Escape HTML entities.\n  - `truncate` (Integer): Maximum allowed message length (default is `4096`).\n  \n  **Usage Example:**\n  ```ruby\n  Telegrama.send_message(\"Contact: john.doe@example.com\", formatting: { obfuscate_emails: true })\n  ```\n\n- **`client_options`**\n  *A hash that overrides the default HTTP client options for this specific request.*\n  - `timeout` (Integer): Request timeout in seconds.\n  - `retry_count` (Integer): Number of times to retry failed requests.\n  - `retry_delay` (Integer): Delay between retry attempts in seconds.\n  \n  **Usage Example:**\n  ```ruby\n  Telegrama.send_message(\"URGENT: Server alert!\", client_options: { timeout: 5, retry_count: 5 })\n  ```\n\n### Asynchronous message delivery\n\nFor production environments or high-traffic applications, you might want to offload message delivery to a background job. Our gem supports asynchronous delivery via ActiveJob.\n\nWith `deliver_message_async` setting enabled, calling:\n```ruby\nTelegrama.send_message(\"Hello asynchronously!\")\n```\n\nwill enqueue a job on the specified queue (`deliver_message_queue`) rather than sending the message immediately.\n\n### HTTP client options\n\nTelegrama allows configuring the underlying HTTP client behavior for API requests:\n\n```ruby\nTelegrama.configure do |config|\n  # HTTP client options\n  config.client_options = {\n    timeout: 30,     # Request timeout in seconds (default: 30s)\n    retry_count: 3,  # Number of retries for failed requests (default: 3)\n    retry_delay: 1   # Delay between retries in seconds (default: 1s)\n  }\nend\n```\n\nThese options can also be overridden on a per-message basis:\n\n```ruby\n# For time-sensitive alerts, use a shorter timeout and more aggressive retries\nTelegrama.send_message(\"URGENT: Server CPU at 100%!\", client_options: { timeout: 5, retry_count: 5, retry_delay: 0.5 })\n\n# For longer messages or slower connections, use a longer timeout\nTelegrama.send_message(long_report, client_options: { timeout: 60 })\n```\n\nAvailable client options:\n- **`timeout`**: HTTP request timeout in seconds (default: 30s)\n- **`retry_count`**: Number of times to retry failed requests (default: 3)\n- **`retry_delay`**: Delay between retry attempts in seconds (default: 1s)\n\n## Robust message delivery with fallback cascade\n\nTelegrama implements a sophisticated fallback system to ensure your messages are delivered even when formatting issues occur:\n\n### Multi-level fallback system\n\n1. **Primary Attempt**: First tries to send the message with your configured formatting (MarkdownV2 by default)\n2. **HTML Fallback**: If MarkdownV2 fails, automatically converts and attempts delivery with HTML formatting\n3. **Plain Text Fallback**: As a last resort, strips all formatting and sends as plain text\n4. **Emergency Response**: Even if all delivery attempts fail, your application continues running without exceptions\n\nThis ensures that critical notifications always reach their destination, regardless of formatting complexities.\n\n## Advanced formatting features\n\nTelegrama includes a sophisticated state machine-based markdown formatter that properly handles:\n\n- **Nested Formatting**: Correctly formats complex nested elements like *bold text with _italic_ words*\n- **Code Blocks**: Supports both inline `code` and multi-line code blocks with language highlighting\n- **Special Character Escaping**: Automatically handles escaping of special characters like !, ., etc.\n- **URL Safety**: Properly formats URLs with special characters while maintaining clickability\n- **Email Obfuscation**: Implements privacy-focused email transformation (joh...e@example.com)\n- **Error Recovery**: Gracefully handles malformed markdown without breaking your messages\n\nThe formatter is designed to be robust even with complex inputs, ensuring your messages always look great in Telegram:\n\n````ruby\n# Complex formatting example that works perfectly\nmessage = \u003c\u003c~MSG\n  📊 *Monthly Report*\n\n  _Summary of #{Date.today.strftime('%B %Y')}_\n\n  *Key metrics*:\n  - Revenue: *$#{revenue}*\n  - New users: *#{new_users}*\n  - Active users: *#{active_users}*\n\n  ```ruby\n  # Sample code that will be properly formatted\n  def calculate_growth(current, previous)\n    ((current.to_f / previous) - 1) * 100\n  end\n  ```\n\n  🔗 [View full dashboard](#{dashboard_url})\nMSG\n\nTelegrama.send_message(message)\n````\n\n## Testing\n\nThe gem includes a Minitest test suite.\n\nTo run the tests:\n\n```bash\nbundle exec rake test\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`.\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/rameerez/telegrama. Our code of conduct is: just be nice and make your mom proud of what you do and post online.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","funding_links":[],"categories":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frameerez%2Ftelegrama","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frameerez%2Ftelegrama","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frameerez%2Ftelegrama/lists"}