{"id":15015656,"url":"https://github.com/amircandy/perlgram","last_synced_at":"2026-02-13T14:38:33.511Z","repository":{"id":305076110,"uuid":"968090172","full_name":"AmiRCandy/Perlgram","owner":"AmiRCandy","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-17T19:06:53.000Z","size":769,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-18T07:41:18.335Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AmiRCandy.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","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}},"created_at":"2025-04-17T13:44:53.000Z","updated_at":"2025-04-19T12:14:56.000Z","dependencies_parsed_at":"2025-07-18T07:41:20.609Z","dependency_job_id":"1cdde8ae-38ac-4daf-98b1-0c88fc52724f","html_url":"https://github.com/AmiRCandy/Perlgram","commit_stats":null,"previous_names":["amircandy/perlgram"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/AmiRCandy/Perlgram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmiRCandy%2FPerlgram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmiRCandy%2FPerlgram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmiRCandy%2FPerlgram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmiRCandy%2FPerlgram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AmiRCandy","download_url":"https://codeload.github.com/AmiRCandy/Perlgram/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmiRCandy%2FPerlgram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272355760,"owners_count":24920173,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-27T02:00:09.397Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["perl","telegram-api","telegram-bot","telegram-bot-api"],"created_at":"2024-09-24T19:47:44.968Z","updated_at":"2026-02-13T14:38:33.436Z","avatar_url":"https://github.com/AmiRCandy.png","language":"Perl","readme":"# Perlgram - Comprehensive Perl Interface for Telegram Bot API\n\n## Table of Contents\n1. [Overview](#overview)\n2. [Installation](#installation)\n3. [Quick Start](#quick-start)\n4. [Core Components](#core-components)\n   - [Perlgram](#perlgram-main-module)\n   - [Perlgram::CLI](#perlgramcli)\n   - [Perlgram::Webhook](#perlgramwebhook)\n   - [Perlgram::Update](#perlgramupdate)\n   - [Perlgram::Error](#perlgramerror)\n   - [Perlgram::Types](#perlgramtypes)\n5. [Examples](#examples)\n   - [Simple Bot](#simple-bot)\n   - [Webhook Bot](#webhook-bot)\n6. [API Reference](#api-reference)\n7. [Best Practices](#best-practices)\n8. [Troubleshooting](#troubleshooting)\n9. [Contributing](#contributing)\n10. [License](#license)\n\n## Overview\n\nPerlgram is a feature-complete Perl implementation of the Telegram Bot API, providing both CLI polling and webhook modes. It supports all major Telegram Bot API methods and object types, making it suitable for building complex bot applications.\n\nKey Features:\n- Full coverage of Telegram Bot API methods\n- Both polling (CLI) and webhook modes\n- Comprehensive error handling\n- Logging integration\n- Type definitions for all Telegram objects\n- Flexible update processing system\n- CPAN-ready distribution\n\n## Installation\n\n### Prerequisites\n- Perl 5.20 or higher\n- cpan or cpanm\n\n### Installation Methods\n\n**Via CPAN:**\n```bash\ncpan Perlgram\n```\n\n**Manual installation:**\n```bash\ngit clone https://github.com/AmiRCandy/Perlgram.git\ncd Perlgram\nperl Makefile.PL\nmake\nmake test\nmake install\n```\n\n### Dependencies\nPerlgram requires the following Perl modules:\n- HTTP::Tiny\n- JSON\n- URI::Escape\n- Log::Log4perl\n- Mojolicious (for webhook mode)\n- Carp\n\nThese will be automatically installed if you use CPAN.\n\n## Quick Start\n\n### 1. Get a Bot Token\nTalk to @BotFather on Telegram to create a new bot and get your API token.\n\n### 2. Simple Polling Bot\n```perl\nuse Perlgram;\nuse Perlgram::CLI;\n\nmy $bot = Perlgram-\u003enew(token =\u003e 'YOUR_BOT_TOKEN');\nmy $cli = Perlgram::CLI-\u003enew(\n    bot =\u003e $bot,\n    handlers =\u003e {\n        message =\u003e sub {\n            my ($self, $message) = @_;\n            $self-\u003e{bot}-\u003esendMessage(\n                chat_id =\u003e $message-\u003e{chat}{id},\n                text =\u003e \"Echo: \" . ($message-\u003e{text} || ''),\n            );\n        }\n    }\n);\n$cli-\u003erun();\n```\n\n### 3. Webhook Bot\n```perl\nuse Mojolicious::Lite;\nuse Perlgram;\n\nmy $bot = Perlgram-\u003enew(token =\u003e 'YOUR_BOT_TOKEN');\n\npost '/webhook' =\u003e sub {\n    my $c = shift;\n    my $update = $c-\u003ereq-\u003ejson;\n    my $handler = Perlgram::Update-\u003enew(\n        bot =\u003e $bot,\n        update =\u003e $update,\n        handlers =\u003e {\n            message =\u003e sub {\n                my ($self, $message) = @_;\n                $self-\u003e{bot}-\u003esendMessage(\n                    chat_id =\u003e $message-\u003e{chat}{id},\n                    text =\u003e \"Webhook echo: \" . ($message-\u003e{text} || ''),\n                );\n            }\n        }\n    );\n    $handler-\u003eprocess();\n    $c-\u003erender(json =\u003e { ok =\u003e 1 });\n};\n\napp-\u003estart;\n```\n\n## Core Components\n\n### Perlgram (Main Module)\nThe core class that implements all Telegram Bot API methods.\n\n**Key Methods:**\n- `new(token =\u003e $token, [api_url =\u003e $url, on_error =\u003e $callback])` - Creates a new bot instance\n- `api_request($method, $params)` - Low-level API request method\n- All Telegram Bot API methods (sendMessage, getUpdates, etc.)\n\n**Example:**\n```perl\nmy $bot = Perlgram-\u003enew(\n    token =\u003e '123:ABC',\n    on_error =\u003e sub {\n        my $error = shift;\n        warn \"Error: $error-\u003e{message}\";\n    }\n);\nmy $user = $bot-\u003egetMe();\n```\n\n### Perlgram::CLI\nImplements polling mode for receiving updates via getUpdates.\n\n**Key Methods:**\n- `new(bot =\u003e $bot, [offset =\u003e $n, timeout =\u003e $sec, limit =\u003e $n, handlers =\u003e \\%handlers])`\n- `run()` - Starts the polling loop\n\n**Example:**\n```perl\nmy $cli = Perlgram::CLI-\u003enew(\n    bot =\u003e $bot,\n    timeout =\u003e 10,\n    handlers =\u003e {\n        message =\u003e \\\u0026handle_message,\n        callback_query =\u003e \\\u0026handle_callback\n    }\n);\n$cli-\u003erun();\n```\n\n### Perlgram::Webhook\nMojolicious-based webhook server for receiving updates via HTTPS.\n\n**Usage:**\n```bash\nperl perlgram-webhook.pl\n```\n\n**Configuration:**\nCreate a `webhook.conf` file:\n```perl\n{\n    token =\u003e 'YOUR_BOT_TOKEN',\n    webhook_url =\u003e 'https://yourdomain.com/webhook'\n}\n```\n\n### Perlgram::Update\nProcesses incoming updates and routes them to appropriate handlers.\n\n**Key Methods:**\n- `new(bot =\u003e $bot, update =\u003e $update, [handlers =\u003e \\%handlers])`\n- `register_handler($type, $callback)`\n- `process()`\n\n**Handler Types:**\n- message\n- edited_message\n- channel_post\n- callback_query\n- inline_query\n- shipping_query\n- and more...\n\n### Perlgram::Error\nError handling class for API and HTTP errors.\n\n**Example:**\n```perl\neval { $bot-\u003esendMessage(...) };\nif ($@) {\n    if ($@ =~ /Perlgram::Error/) {\n        warn \"API error occurred\";\n    }\n}\n```\n\n### Perlgram::Types\nDefines data structures for all Telegram API objects (User, Chat, Message, etc.).\n\n**Example:**\n```perl\nmy $message = {\n    %{ $Perlgram::Types::Message },\n    message_id =\u003e 123,\n    text =\u003e 'Hello',\n    chat =\u003e { %{ $Perlgram::Types::Chat }, id =\u003e 456 }\n};\n```\n\n## Examples\n\n### Simple Bot\n```perl\n#!/usr/bin/env perl\nuse strict;\nuse warnings;\nuse Perlgram;\nuse Perlgram::CLI;\n\nmy $bot = Perlgram-\u003enew(token =\u003e 'YOUR_BOT_TOKEN');\n\nmy $cli = Perlgram::CLI-\u003enew(\n    bot =\u003e $bot,\n    handlers =\u003e {\n        message =\u003e sub {\n            my ($self, $msg) = @_;\n            my $text = $msg-\u003e{text} || '';\n            \n            if ($text =~ /^\\/start/) {\n                $self-\u003e{bot}-\u003esendMessage(\n                    chat_id =\u003e $msg-\u003e{chat}{id},\n                    text =\u003e \"Welcome! Send /help for commands.\",\n                    reply_markup =\u003e {\n                        keyboard =\u003e [\n                            [{ text =\u003e \"Button 1\" }],\n                            [{ text =\u003e \"Button 2\" }]\n                        ],\n                        resize_keyboard =\u003e \\1\n                    }\n                );\n            }\n            elsif ($text =~ /^\\/help/) {\n                $self-\u003e{bot}-\u003esendMessage(\n                    chat_id =\u003e $msg-\u003e{chat}{id},\n                    text =\u003e \"Available commands:\\n/start - Start bot\\n/help - This help\"\n                );\n            }\n            else {\n                $self-\u003e{bot}-\u003esendMessage(\n                    chat_id =\u003e $msg-\u003e{chat}{id},\n                    text =\u003e \"You said: $text\"\n                );\n            }\n        },\n        callback_query =\u003e sub {\n            my ($self, $cb) = @_;\n            $self-\u003e{bot}-\u003eanswerCallbackQuery(\n                callback_query_id =\u003e $cb-\u003e{id},\n                text =\u003e \"You clicked: \" . ($cb-\u003e{data} || '')\n            );\n        }\n    }\n);\n\n$cli-\u003erun();\n```\n\n### Webhook Bot\n```perl\n#!/usr/bin/env perl\nuse Mojolicious::Lite;\nuse Perlgram;\n\nplugin 'Config';\n\nmy $bot = Perlgram-\u003enew(token =\u003e app-\u003econfig-\u003e{token});\n\n# Set webhook on startup\napp-\u003ehook(after_startup =\u003e sub {\n    my ($app) = @_;\n    $bot-\u003esetWebhook(url =\u003e $app-\u003econfig-\u003e{webhook_url});\n});\n\npost '/webhook' =\u003e sub {\n    my $c = shift;\n    my $update = $c-\u003ereq-\u003ejson;\n    \n    my $handler = Perlgram::Update-\u003enew(\n        bot =\u003e $bot,\n        update =\u003e $update,\n        handlers =\u003e {\n            message =\u003e sub {\n                my ($self, $msg) = @_;\n                $self-\u003e{bot}-\u003esendMessage(\n                    chat_id =\u003e $msg-\u003e{chat}{id},\n                    text =\u003e \"Received: \" . ($msg-\u003e{text} || '')\n                );\n            }\n        }\n    );\n    \n    $handler-\u003eprocess();\n    $c-\u003erender(json =\u003e { ok =\u003e \\1 });\n};\n\napp-\u003estart;\n\n__DATA__\n@@ webhook.conf\n{\n    token =\u003e \"YOUR_BOT_TOKEN\",\n    webhook_url =\u003e \"https://yourdomain.com/webhook\"\n}\n```\n\n## API Reference\n\nPerlgram implements all methods from the Telegram Bot API. For detailed parameter information, refer to the [Telegram Bot API documentation](https://core.telegram.org/bots/api).\n\n### Message Methods\n- `sendMessage(%params)`\n- `sendPhoto(%params)`\n- `sendAudio(%params)`\n- `sendDocument(%params)`\n- `sendVideo(%params)`\n- `sendVoice(%params)`\n- `sendLocation(%params)`\n- `sendChatAction(%params)`\n\n### Update Methods\n- `getUpdates(%params)`\n- `setWebhook(%params)`\n- `deleteWebhook()`\n- `getWebhookInfo()`\n\n### Chat Management\n- `getChat(%params)`\n- `getChatAdministrators(%params)`\n- `banChatMember(%params)`\n- `unbanChatMember(%params)`\n- `restrictChatMember(%params)`\n- `promoteChatMember(%params)`\n\n### Inline Mode\n- `answerInlineQuery(%params)`\n- `answerWebAppQuery(%params)`\n\n### Payments\n- `sendInvoice(%params)`\n- `answerShippingQuery(%params)`\n- `answerPreCheckoutQuery(%params)`\n\n### Stickers\n- `sendSticker(%params)`\n- `getStickerSet(%params)`\n- `uploadStickerFile(%params)`\n\n## Best Practices\n\n1. **Error Handling**: Always wrap API calls in eval blocks and implement the `on_error` callback.\n\n2. **Webhook Security**:\n   - Use HTTPS for webhooks\n   - Validate the incoming token\n   - Implement IP whitelisting if possible\n\n3. **Rate Limiting**: Respect Telegram's rate limits (about 30 messages/second).\n\n4. **Logging**: Configure Log4perl for production logging.\n\n5. **Persistence**: For production bots, store the last update_id to avoid processing duplicates after restarts.\n\n6. **Webhook Setup**:\n```perl\n# Set webhook with a self-signed certificate\n$bot-\u003esetWebhook(\n    url =\u003e 'https://yourdomain.com/webhook',\n    certificate =\u003e { file =\u003e '/path/to/cert.pem' }\n);\n\n# Remove webhook when shutting down\n$bot-\u003edeleteWebhook();\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"Token required\" error**\n   - Verify your token is correct\n   - Ensure it's passed to the constructor\n\n2. **Webhook not receiving updates**\n   - Check if webhook is set correctly with `getWebhookInfo`\n   - Verify your server is accessible from the internet\n   - Check your firewall settings\n\n3. **\"Can't decode JSON\" errors**\n   - Ensure your Perl JSON module is up to date\n   - Verify the API response format\n\n4. **High memory usage in polling mode**\n   - Reduce the `limit` parameter in Perlgram::CLI\n   - Increase the `timeout` to reduce request frequency\n\n### Debugging Tips\n\nEnable debug logging:\n```perl\nuse Log::Log4perl qw(:easy);\nLog::Log4perl-\u003eeasy_init($DEBUG);\n```\n\nCheck API responses:\n```perl\nmy $response = $bot-\u003eapi_request('getMe');\nuse Data::Dumper;\nprint Dumper($response);\n```\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Submit a pull request\n\nReport bugs at: https://github.com/AmiRCandy/Perlgram/issues\n\n## License\n\nPerlgram is released under the Artistic License 2.0.\n\n## Additional Resources\n\n- [Telegram Bot API Documentation](https://core.telegram.org/bots/api)\n- [Perlgram GitHub Repository](https://github.com/AmiRCandy/Perlgram)\n- [CPAN Module Page](https://metacpan.org/pod/Perlgram)\n\n---\n\nThis documentation provides comprehensive coverage of the Perlgram module. For inclusion on the Telegram website, you may want to:\n1. Add more real-world examples\n2. Include screenshots of bots built with Perlgram\n3. Add a comparison with other Telegram bot libraries\n4. Include performance benchmarks if available\n\nWould you like me to expand any particular section or add more examples?","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famircandy%2Fperlgram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famircandy%2Fperlgram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famircandy%2Fperlgram/lists"}