{"id":13809294,"url":"https://github.com/telegex/telegex","last_synced_at":"2025-04-06T09:10:43.336Z","repository":{"id":52482974,"uuid":"273386261","full_name":"telegex/telegex","owner":"telegex","description":"Telegram bot framework and API client written in Elixir","archived":false,"fork":false,"pushed_at":"2024-06-19T11:32:04.000Z","size":580,"stargazers_count":124,"open_issues_count":0,"forks_count":13,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-08-01T02:14:21.441Z","etag":null,"topics":["telegram-bot-api","telegram-bot-framework"],"latest_commit_sha":null,"homepage":"https://hex.pm/packages/telegex","language":"Elixir","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/telegex.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-19T02:29:13.000Z","updated_at":"2024-08-01T02:14:26.804Z","dependencies_parsed_at":"2023-10-11T15:51:57.379Z","dependency_job_id":"91ecfabc-a474-4366-b27c-424380ea79b3","html_url":"https://github.com/telegex/telegex","commit_stats":null,"previous_names":["hentioe/telegex"],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telegex%2Ftelegex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telegex%2Ftelegex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telegex%2Ftelegex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telegex%2Ftelegex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/telegex","download_url":"https://codeload.github.com/telegex/telegex/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247457803,"owners_count":20941906,"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","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":["telegram-bot-api","telegram-bot-framework"],"created_at":"2024-08-04T01:02:15.717Z","updated_at":"2025-04-06T09:10:43.312Z","avatar_url":"https://github.com/telegex.png","language":"Elixir","funding_links":[],"categories":["Third Party APIs"],"sub_categories":[],"readme":"# Telegex\n\n[![.github/workflows/otp-26.yml](https://github.com/telegex/telegex/actions/workflows/otp-26.yml/badge.svg?branch=master)](https://github.com/telegex/telegex/actions/workflows/otp-26.yml)\n[![.github/workflows/otp-27.yml](https://github.com/telegex/telegex/actions/workflows/otp-27.yml/badge.svg?branch=master)](https://github.com/telegex/telegex/actions/workflows/otp-27.yml)\n[![Module Version](https://img.shields.io/hexpm/v/telegex.svg)](https://hex.pm/packages/telegex)\n[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/telegex/)\n[![Total Download](https://img.shields.io/hexpm/dt/telegex.svg)](https://hex.pm/packages/telegex)\n[![Last Updated](https://img.shields.io/github/last-commit/telegex/telegex.svg)](https://github.com/telegex/telegex/commits/master)\n\nA new Telegram bot framework, which is also a perfect Bot API client library.\n\n_All API functions, comments, types (structures and specifications) of Telegex are generated from documents. I parse the documents into structured data and publish it on [telegex/api_doc.json](https://github.com/telegex/api_doc.json)._\n\n## Introduction\n\nTelegex is not only a client for Bot API, but also a framework for building bots. It provides convenient support for receiving updates and implements an advanced processing model based on \"chains\".\n\n\u003e The section regarding chains currently has no documentation available. Join the group for help: [@elixir_telegex](https://t.me/elixir_telegex).\n\n## Installation\n\nAdd Telegex to your mix.exs dependencies:\n\n```elixir\ndef deps do\n  [\n    {:telegex, \"~\u003e 1.9.0-rc.0\"},\n  ]\nend\n```\n\n## ⚠️ Upgrade reminder\n\nSome modules detect `plug` during compilation. After upgrading the version, you need to manually clean up the related dependency builds.\n\n```bash\nrm -rf _build/dev/lib/plug _build/dev/lib/telegex\n```\n\n## Configuration\n\nAdd bot token to the secret configuration file, like this:\n\n```elixir\nconfig :telegex, token: \"\u003cBOT_TOKEN\u003e\"\n```\n\nSpecify the adapter for the HTTP client in the public configuration file:\n\n```elixir\nconfig :telegex, caller_adapter: Finch\n```\n\nPass options to the adapter, such as timeout:\n\n```elixir\nconfig :telegex, caller_adapter: {Finch, [receive_timeout: 5 * 1000]}\n```\n\nYou can also choose `HTTPoison` as the client. If using HTTPoison, set the corresponding adapter and timeout:\n\n```elixir\nconfig :telegex, caller_adapter: {HTTPoison, [recv_timeout: 5 * 1000]}\n```\n\n\u003e Note: There are no standardized values for the `options` parameter here, as they directly relate to the HTTP client being used. The example above passes the raw options for the client library.\n\n**Note: You need to manually add adapter-related libraries to the `deps`:**\n\n- `Finch`: [`finch`](https://hex.pm/packages/finch), [`multipart`](https://hex.pm/packages/multipart) (recommend)\n- `HTTPoison`: [`httpoison`](https://hex.pm/packages/httpoison) (⚠️ sending local files is not supported)\n\n_For complete configuration, please refer to the [`Telegex.Global`](https://hexdocs.pm/telegex/Telegex.Global.html) module documentation._\n\n## API call\n\nAll Bot APIs are located under the `Telegex` module, and these APIs fully comply with the required and optional parameters in the documentation, returning specific types (struct rather than map).\n\n### getMe\n\n```elixir\niex\u003e Telegex.get_me\n{:ok,\n %Telegex.Type.User{\n   supports_inline_queries: false,\n   can_read_all_group_messages: false,\n   can_join_groups: true,\n   added_to_attachment_menu: nil,\n   is_premium: nil,\n   language_code: nil,\n   username: \"telegex_dev_bot\",\n   last_name: nil,\n   first_name: \"Telegex Dev\",\n   is_bot: true,\n   id: 6258629308\n }}\n```\n\n### getUpdates\n\n```elixir\niex\u003e Telegex.get_updates limit: 50\n{:ok,\n [\n   %Telegex.Type.Update{\n     chat_join_request: nil,\n     chat_member: nil,\n     my_chat_member: nil,\n     poll_answer: nil,\n     poll: nil,\n     pre_checkout_query: nil,\n     shipping_query: nil,\n     callback_query: nil,\n     chosen_inline_result: nil,\n     inline_query: nil,\n     edited_channel_post: nil,\n     channel_post: nil,\n     edited_message: nil,\n     message: %Telegex.Type.Message{\n       reply_markup: nil,\n       web_app_data: nil,\n       # omitted part...\n       new_chat_photo: nil,\n       new_chat_title: nil,\n       text: \"Hello\",\n       # omitted part...\n     },\n     update_id: 929396006\n   }\n ]}\n```\n\n### sendMessage\n\n```elixir\niex\u003e Telegex.send_message -1001486769003, \"Hello!\"\n{:ok,\n %Telegex.Type.Message{\n   venue: nil,\n   chat: %Telegex.Type.Chat{\n     # omitted part...\n     title: \"Dev test\",\n     type: \"supergroup\",\n     id: -1001486769003\n   },\n   date: 1686111102,\n   message_id: 12777,\n   text: \"Hello!\",\n   from: %Telegex.Type.User{\n     supports_inline_queries: nil,\n     can_read_all_group_messages: nil,\n     can_join_groups: nil,\n     added_to_attachment_menu: nil,\n     is_premium: nil,\n     language_code: nil,\n     username: \"telegex_dev_bot\",\n     last_name: nil,\n     first_name: \"Telegex Dev\",\n     is_bot: true,\n     id: 6258629308\n  },\n  # omitted part...\n }}\n```\n\n## Polling mode\n\nPolling is a simple and effective pattern that ensures messages within the same group arrive in order. Although it may not be the fastest, it is simple and reliable.\n\nTo work in polling mode:\n\n1. Create a new module, like `YourProject.PollingHandler`\n1. `Use Telegex.Polling.GenHandler`\n1. Implement `on_boot/0` and `on_update/1` callback functions\n1. Add your module to the supervision tree\n\nPolling handler example:\n\n```elixir\ndefmodule YourProject.PollingHandler do\n  use Telegex.Polling.GenHandler\n\n  @impl true\n  def on_boot do\n    # delete any potential webhook\n    {:ok, true} = Telegex.delete_webhook()\n    # create configuration (can be empty, because there are default values)\n    %Telegex.Polling.Config{}\n    # you must return the `Telegex.Polling.Config` struct ↑\n  end\n\n  @impl true\n  def on_update(update) do\n    # consume the update\n\n    :ok\n  end\nend\n\n```\n\n**Don't forget to add your module to the supervision tree.**\n\n## Webhook mode\n\nAdd [`plug`](https://hex.pm/packages/plug) and [`remote_ip`](https://hex.pm/packages/remote_ip) to your application's deps because they are required for webhook mode.\n\nYou also need to configure adapters for hooks, which provide web services.\n\nBased on [`Bandit`](https://hexdocs.pm/telegex/Telegex.Hook.Adapter.Bandit.html) - [`bandit`](https://hex.pm/packages/bandit)\n\n```elixir\n# add `bandit` to your deps.\nconfig :telegex, hook_adapter: Bandit\n```\n\nBased on [`Cowboy`](https://hexdocs.pm/telegex/Telegex.Hook.Adapter.Cowboy.html) - [`plug_cowboy`](https://hex.pm/packages/plug_cowboy)\n\n```elixir\n# add `plug_cowboy` to your deps.\nconfig :telegex, hook_adapter: Cowboy\n```\n\nTo work in webhook mode:\n\n1. Create a new module, like `YourProject.HookHandler`\n1. `Use Telegex.Hook.GenHandler`\n1. Implement `on_boot/0` and `on_update/1` callback functions\n1. Add your module to the supervision tree\n\nHook handler example:\n\n```elixir\ndefmodule YourProject.HookHandler do\n  use Telegex.Hook.GenHandler\n\n  @impl true\n  def on_boot do\n    # read some parameters from your env config\n    env_config = Application.get_env(:your_project, __MODULE__)\n    # delete the webhook and set it again\n    {:ok, true} = Telegex.delete_webhook()\n    # set the webhook (url is required)\n    {:ok, true} = Telegex.set_webhook(env_config[:webhook_url])\n    # specify port for web server\n    # port has a default value of 4000, but it may change with library upgrades\n    %Telegex.Hook.Config{server_port: env_config[:server_port]}\n    # you must return the `Telegex.Hook.Config` struct ↑\n  end\n\n  @impl true\n  def on_update(update) do\n\n    # consume the update\n    :ok\n  end\nend\n```\n\n_For complete configuration, please refer to the [`Telegex.Hook.GenHandler`](https://hexdocs.pm/telegex/Telegex.Hook.GenHandler.html) module documentation._\n\n**Don't forget to add your module to the supervision tree.**\n\n## Compatibility mode\n\nYou can create handlers for two modes and determine which one to start based on the configuration.\n\n```elixir\nupdates_handler =\n  if Application.get_env(:your_project, :work_mode) == :webhook do\n    YourProject.HookHandler\n  else\n    YourProject.PollingHandler\n  end\n\nchildren = [\n  # omit other children\n  updates_handler\n]\n\nopts = [strategy: :one_for_one, name: YourProject.Supervisor]\nSupervisor.start_link(children, opts)\n```\n\n## The end\n\nIs there anything you don't understand about building a Telegram Bot? Have bot development needs? Welcome to contact me.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelegex%2Ftelegex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftelegex%2Ftelegex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelegex%2Ftelegex/lists"}