ブログに戻る
Guides

Pythonで始めるTelegramボット開発：完全ガイド

Pythonを使って強力なTelegramボットを無料で作成する方法を学びましょう。API設定からデプロイまで、カスタムTelegramボット開発の全工程をステップバイステップで解説します。

Pythonで始めるTelegramボット開発：完全ガイド

Pythonを使って独自のTelegramボットを構築することは、計り知れないほどの柔軟性とパワーをもたらします。タスクの自動化、インタラクティブなサービスの作成、あるいは単にTelegramの堅牢なAPIを試してみたい場合でも、Pythonはそのシンプルさと豊富なライブラリのおかげで優れた選択肢です。この包括的なガイドでは、開発環境のセットアップから機能するコードの記述、そしてボットのデプロイまで、初めてのTelegramボットPythonプロジェクトを作成する全プロセスを順を追って説明します。

Pythonの読みやすさと、python-telegram-botライブラリをサポートする活発なコミュニティは、初心者から経験豊富な開発者まで、素晴らしい出発点となります。このチュートリアルを終える頃には、ユーザーと対話できる完全に機能するTelegramボットが完成しているでしょう。

この記事で学べること

  • BotFatherでボットを登録し、APIトークンを取得する方法を学びます。
  • Python開発環境のセットアップと必要なライブラリのインストールについて説明します。
  • 基本的なコマンドとメッセージを処理するコードを記述します。
  • ボットにさらに高度な機能を追加する方法を探ります。
  • TelegramボットPythonアプリケーションをデプロイする基本を理解します。

1. Telegramボットと開発環境のセットアップ

コードを書き始める前に、Telegramでボットをセットアップし、Python環境を準備する必要があります。

1.1 BotFatherでボットを作成する

すべてのTelegramボットの最初のステップは、Telegramの公式ボット管理ツールであるBotFatherに登録することです。

  1. Telegramを開き、@BotFatherを検索: Telegramアプリで「@BotFather」を検索し、チャットを開始します。青い認証バッジが付いている公式アカウントであることを確認してください。
  2. ボット作成プロセスを開始: /newbotと入力してメッセージを送信します。
  3. 名前を選択: BotFatherがボットの名前を尋ねてきます。これはユーザーが見る人間が読めるタイトルです（例：「私の素晴らしいボット」）。
  4. ユーザー名を選択: 次に、ボットの一意のユーザー名を選択します。これは「bot」で終わる必要があります（例：my_awesome_bot）。ユーザー名が既に使用されている場合、BotFatherは別のものを試すように求めます。
  5. APIトークンを受け取る: 成功すると、BotFatherはHTTP APIトークンを提供します。このトークンはボットのパスワードのようなもので、非常に重要です。安全に保管し、決して公開しないでください。 123456:ABC-DEF1234ghIkl-zyx57W23L1qR_456のような形式です。

1.2 Pythonとpipのインストール

Pythonがまだインストールされていない場合は、公式Pythonウェブサイト（https://www.python.org/downloads/）から最新の安定版をダウンロードしてください。インストール中に、「Add Python to PATH」のチェックボックスをオンにして、コマンドラインからのアクセスを容易にしてください。

pipはPythonのパッケージインストーラーで、通常Pythonと一緒にプリインストールされています。ターミナルまたはコマンドプロンプトを開き、以下を入力してPythonとpipのインストールを確認できます。

python --version
pip --version

1.3 python-telegram-botライブラリのインストール

python-telegram-botライブラリは、Telegram Bot API用の人気があり堅牢なラッパーです。APIとのやり取りを簡素化し、ボットの開発をはるかに容易にします。

pipを使用してインストールします。

pip install python-telegram-bot

これで、ボットと開発環境のセットアップが完了しました。次に、コードを書き始めましょう！

2. 初めてのTelegramボットPythonコード：エコーボット

まずは定番のエコーボットから始めましょう。このボットは、受信したメッセージをそのまま返します。このシンプルな例を通して、メッセージ処理の核心を学びます。

2.1 必要なモジュールのインポート

新しいPythonファイル（例：my_telegram_bot.py）を作成し、telegramライブラリから必要なコンポーネントをインポートすることから始めます。

from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, filters
import logging
import os
  • Update: Telegramからの受信更新（新しいメッセージ、コマンドなど）を表します。
  • Application: ボットのライフサイクルを管理する主要なクラスです。
  • CommandHandler: 特定のコマンド（例：/start、/help）のハンドラーを登録するために使用されます。
  • MessageHandler: さまざまな種類のメッセージ（テキスト、写真など）のハンドラーを登録するために使用されます。
  • filters: MessageHandlerが応答すべきメッセージの種類を指定するための便利なフィルターを提供します。
  • logging: デバッグやボットの動作理解に役立つ良い習慣です。
  • os: 環境変数からAPIトークンを安全に読み込むために使用します。

2.2 ロギングのセットアップ

ロギングはトラブルシューティングに不可欠です。スクリプトに以下の行を追加します。

# ロギングを有効にする
logging.basicConfig(
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", level=logging.INFO
)
logger = logging.getLogger(__name__)

2.3 ハンドラーの定義

ハンドラーは、受信した更新を処理する関数です。

startコマンドハンドラー:

この関数は、ユーザーが/startコマンドを送信したときに呼び出されます。

async def start(update: Update, context):
    """/startコマンドが発行されたときにウェルカムメッセージを送信します。"""
    user = update.effective_user
    await update.message.reply_html(
        f"こんにちは、{user.mention_html()}！私はエコーボットです。何か送ってみてください！",
        # reply_markup=ForceReply(selective=True), # オプション：このメッセージへの返信を強制する
    )

echoメッセージハンドラー:

この関数は、受信したテキストメッセージをそのまま返します。

async def echo(update: Update, context):
    """ユーザーメッセージをエコーします。"""
    await update.message.reply_text(update.message.text)

help_commandハンドラー:

シンプルなヘルプコマンドです。

async def help_command(update: Update, context):
    """ヘルプメッセージを送信します。"""
    await update.message.reply_text("何かメッセージを送ってください。私がそれをエコーバックします！")

2.4 main関数：すべてをまとめる

main関数は、ボットを初期化し、ハンドラーを登録し、更新のポーリングを開始する場所です。

def main() -> None:
    """ボットを開始します。"""
    # 環境変数からAPIトークンを取得します（ベストプラクティス！）
    # または、迅速なテストのためにここにハードコードすることもできます：TOKEN = "YOUR_TELEGRAM_BOT_TOKEN"
    TOKEN = os.environ.get("TELEGRAM_BOT_TOKEN")

    if not TOKEN:
        raise ValueError("TELEGRAM_BOT_TOKEN環境変数が設定されていません。")

    # Applicationを作成し、ボットのトークンを渡します。
    application = Application.builder().token(TOKEN).build()

    # ハンドラーを登録します
    application.add_handler(CommandHandler("start", start))
    application.add_handler(CommandHandler("help", help_command))
    application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))

    # ユーザーがCtrl-Cを押すまでボットを実行します
    application.run_polling(allowed_updates=Update.ALL_TYPES)


if __name__ == "__main__":
    main()

2.5 ボットをローカルで実行する

  1. APIトークンを環境変数として設定:

    • Linux/macOS: export TELEGRAM_BOT_TOKEN="YOUR_API_TOKEN_HERE"
    • Windows (コマンドプロンプト): set TELEGRAM_BOT_TOKEN="YOUR_API_TOKEN_HERE"
    • Windows (PowerShell): $env:TELEGRAM_BOT_TOKEN="YOUR_API_TOKEN_HERE" または、迅速なローカルテストのために、os.environ.get("TELEGRAM_BOT_TOKEN")を実際のトークン文字列に直接置き換えることもできます（例：TOKEN = "123456:ABCDEF..."）。ただし、本番環境では推奨されません。

  2. Pythonスクリプトを実行: ターミナルでmy_telegram_bot.pyを保存したディレクトリに移動し、以下を実行します。

    python my_telegram_bot.py

  3. ボットと対話: Telegramを開き、ボットのユーザー名（例：@my_awesome_bot）を検索してチャットを開始します。/start、/help、または任意のテキストメッセージを送信してみてください。ボットが応答するはずです！

おめでとうございます！これで、初めてのTelegramボットPythonアプリケーションを作成し、実行しました。

Telegramボットが/startに応答し、メッセージをエコーしている様子。

3. より高度な機能を追加する

エコーボットも素晴らしいですが、もっと便利にしてみましょう。Telegramボットを拡張するためのアイデアをいくつか紹介します。

3.1 さまざまなメッセージタイプの処理

プレーンテキスト以外にも、Telegramは写真、ビデオ、ドキュメントなど、さまざまなものをサポートしています。filtersを使ってこれらを具体的に処理できます。

例：写真への応答

async def handle_photo(update: Update, context):
    """写真に確認メッセージで応答します。"""
    # update.message.photoを介して写真の詳細にアクセスできます
    # リストには同じ写真の異なるサイズが含まれており、通常は最後のものが最大です。
    photo_file_id = update.message.photo[-1].file_id
    await update.message.reply_text("素敵な写真ですね！受け取りました。")

# このハンドラーをmain関数に追加します
# application.add_handler(MessageHandler(filters.PHOTO, handle_photo))

3.2 インラインキーボードとリプライキーボードの使用

キーボードは、ユーザーに構造化されたインタラクションオプションを提供します。

  • リプライキーボード: メッセージ入力フィールドの上に表示され、標準のキーボードを効果的に置き換えます。事前定義された選択肢に最適です。
  • インラインキーボード: メッセージに直接添付され、コールバックをトリガーしたりURLを開いたりできるボタンがあります。インタラクティブなメニューに最適です。

例：インラインキーボード

/startコマンドを修正してボタンを提供してみましょう。

from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, MessageHandler, CallbackQueryHandler, filters
# ... (その他のインポートとロギング) ...

async def start(update: Update, context):
    """インラインキーボード付きのウェルカムメッセージを送信します。"""
    user = update.effective_user
    keyboard = [
        [InlineKeyboardButton("TeleClawを訪問", url="https://teleclaw.bot")],
        [InlineKeyboardButton("ボットについて", callback_data="about")],
    ]
    reply_markup = InlineKeyboardMarkup(keyboard)
    await update.message.reply_html(
        f"こんにちは、{user.mention_html()}！私のボットへようこそ。何をしたいですか？",
        reply_markup=reply_markup,
    )

async def button_callback(update: Update, context):
    """インラインキーボードボタンからのコールバッククエリを処理します。"""
    query = update.callback_query
    await query.answer() # コールバッククエリには常に応答します

    if query.data == "about":
        await query.edit_message_text(text="これはPythonと`python-telegram-bot`ライブラリで作成されたシンプルなデモボットです。")
    # 他のcallback_data値の条件を追加します

main関数を更新してCallbackQueryHandlerを含める必要があります。

    # ... main()内 ...
    application.add_handler(CommandHandler("start", start))
    application.add_handler(CallbackQueryHandler(button_callback)) # この行を追加
    application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
    # ...

これは、TeleClawのような外部サイトへのリンクと、ボット内でのアクションの実行を示しています。python-telegram-botのドキュメント（https://docs.python-telegram-bot.org/en/stable/telegram.keyboardbutton.html）で、さまざまなキーボードオプションについて詳しく学ぶことができます。

3.3 外部APIとの連携

TelegramボットPython開発の真の力は、サードパーティサービスと連携できることにあります。天気データ、最新ニュースの取得、テキストの翻訳、さらにはAIモデルとの連携も可能です。

例：シンプルなAPI呼び出し（requestsライブラリを使用）

まず、requestsをインストールします：pip install requests。

import requests

async def get_fact(update: Update, context):
    """外部APIからランダムな事実を取得します。"""
    try:
        response = requests.get("https://uselessfacts.jsph.pl/api/v2/facts/random")
        response.raise_for_status() # 不良な応答（4xxまたは5xx）に対してHTTPErrorを発生させます
        fact_data = response.json()
        await update.message.reply_text(f"ご存知でしたか？ {fact_data['text']}")
    except requests.exceptions.RequestException as e:
        logger.error(f"事実の取得エラー: {e}")
        await update.message.reply_text("申し訳ありません、現在事実を取得できませんでした。後でもう一度お試しください。")

# このコマンドハンドラーを追加します：
# application.add_handler(CommandHandler("fact", get_fact))

これは、ボットが外部データソースとどのように対話できるかを示しています。ちょうど@clawがさまざまなサービスと連携して高度な機能を提供しているようにです。より高度なAIインタラクションには、GPT-4やGeminiのようなモデルとの連携の複雑さを抽象化するTeleClawのようなプラットフォームの使用を検討してください。AIツールの連携については、Telegramチャットボットの構築方法に関する記事で詳しく読むことができます。

Telegramボットが外部APIと対話する様子を視覚的に表現したもの。

4. 永続的なデータと状態管理

より複雑なボットの場合、インタラクション間でデータを保存する方法が必要になります。たとえば、ボットがユーザー設定や進行中の会話を記憶する必要がある場合などです。

4.1 context.user_dataとcontext.chat_dataの使用

python-telegram-botライブラリは、ユーザーまたはチャットに関連する一時的なデータを保存できるcontext.user_dataとcontext.chat_data辞書（ハンドラー関数内で利用可能）を提供します。このデータは、ボットの実行期間中持続します。

async def set_favorite_color(update: Update, context):
    """ユーザーがお気に入りの色を設定できるようにします。"""
    if context.args:
        color = " ".join(context.args).strip()
        context.user_data["favorite_color"] = color
        await update.message.reply_text(f"わかりました、お気に入りの色を{color}として記録しました。")
    else:
        await update.message.reply_text("お気に入りの色を教えてください。例：/setcolor blue")

async def get_favorite_color(update: Update, context):
    """ユーザーにお気に入りの色を伝えます。"""
    color = context.user_data.get("favorite_color")
    if color:
        await update.message.reply_text(f"あなたのお気に入りの色は{color}です。")
    else:
        await update.message.reply_text("まだお気に入りの色がわかりません。/setcolorを使用してください。")

# これらのハンドラーを追加します：
# application.add_handler(CommandHandler("setcolor", set_favorite_color))
# application.add_handler(CommandHandler("getcolor", get_favorite_color))

4.2 再起動後もデータを永続化する

ボットスクリプトが再起動してもデータが永続化するためには、より堅牢なソリューションが必要です。例えば、以下のようなものがあります。

  • ファイル（CSV、JSON）： 少量のデータにはシンプルです。
  • データベース（SQLite、PostgreSQL、MongoDB）： 大規模で複雑なデータストレージに推奨されます。SQLiteはファイルベースで個別のサーバーを必要としないため、ローカル開発に適しています。
  • サードパーティのストレージソリューション： FirestoreやDynamoDBのようなクラウドデータベース。

python-telegram-botライブラリは、PicklePersistenceまたはDictPersistenceと共に使用して、user_data、chat_data、bot_dataをファイルに保存できるBasePersistenceクラスも提供しています。永続化の使用方法については、公式のpython-telegram-botの例（https://docs.python-telegram-bot.org/en/stable/telegram.ext.basepersistence.html）を参照してください。

5. デプロイに関する考慮事項

ボットをローカルマシンで実行するのは開発には問題ありませんが、24時間365日アクセス可能にするには、サーバーにデプロイする必要があります。

5.1 ポーリング vs. Webhook

Telegramボットが更新を受信する主な方法は2つあります。

  • ロングポーリング: ボットがTelegramサーバーに新しい更新を繰り返し要求します。これはapplication.run_polling()で使用した方法です。セットアップは簡単ですが、非常にアクティブなボットにとってはリソースを大量に消費する可能性があります。
  • Webhook: TelegramにサーバーのURLを伝えます。更新が発生すると、TelegramはそのURLにHTTP POSTリクエストを送信します。本番環境ではより効率的ですが、公開アクセス可能なサーバーとHTTPSの処理が必要です。

シンプルなボットや初期開発にはロングポーリングで十分です。本番環境では、一般的にWebhookが推奨されます。python-telegram-botライブラリは両方をサポートしています。

5.2 デプロイプラットフォーム

Pythonボットのデプロイに適したプラットフォームがいくつかあります。

  • Heroku: 小規模から中規模のプロジェクトに最適で、無料枠もあります。gitを使ったデプロイが簡単です。
  • Render: Herokuに似ていますが、より寛大な無料枠とモダンな機能を提供することがよくあります。
  • AWS (EC2, Lambda), Google Cloud (Compute Engine, Cloud Functions), Azure (App Service, Functions): 強力でスケーラブルなソリューションを提供しますが、学習曲線は急です。
  • 仮想プライベートサーバー (VPS): DigitalOcean、Linode、Vultrなどのサービスはより多くの制御を提供しますが、サーバー管理は自己責任です。

デプロイ時には、以下の点に注意してください。

  • APIトークンを安全に保つ: 環境変数を使用します。
  • 依存関係をインストールする: requirements.txtファイルを作成し（pip freeze > requirements.txt）、ホストがそれらをインストールすることを確認します。
  • プロセス管理ツールを設定する: systemdやpm2などのツールは、ボットがクラッシュしても実行を継続できます。

商用アプリケーションや高度にスケーラブルなAI搭載ボットの場合、TeleClawのようなプラットフォームは堅牢で管理された環境を提供します。インフラストラクチャ、セキュリティ、スケーリングを処理するため、ボットのロジックとユーザーエクスペリエンスに集中できます。TeleClawが提供する機能については、ビジネス向けTelegramボットに関する詳細ガイドをご覧ください。

まとめ

これで、TelegramボットPythonアプリケーションを構築するための核心的な原則を学びました。BotFatherでの初期設定と環境設定から、コマンドとメッセージのハンドラーの記述、さまざまなデータタイプの処理、そしてデプロイ戦略の検討まで、しっかりとした基盤ができました。python-telegram-botライブラリは、Telegram APIとのやり取りを驚くほど簡単にしてくれ、自動化とインタラクションの可能性を広げます。

慣れてきたら、次のような高度なトピックを探求できます。

  • ConversationHandlerによる会話処理。
  • エラー処理と堅牢なロギング。
  • 複雑なデータストレージのためのデータベースとの連携。
  • より高度なfiltersの活用。
  • グローバル検索機能のためのインラインモードの実装。

Telegramのオープン性とPythonの汎用性の美しさは、ほとんど何でも構築できる点にあります。もし、重いコーディングの負担なしに、最先端のAI、自然言語理解、またはシームレスな連携でボットを強化したいのであれば、TeleClawのようなプラットフォームがあなたを力づけるために設計されています。

インテリジェントな自動化でTelegramボットを構築、強化、または管理する準備はできましたか？

今すぐTeleClawを探索して、あなたのTelegramボットをスーパーチャージしましょう！ または、Telegramで直接私たちのボットを試してみてください：@claw

FAQ

よくある質問

PythonでTelegramボットを作成するための基本的なステップは何ですか？
基本的なステップとしては、BotFatherで新しいボットを作成してAPIトークンを取得し、`python-telegram-bot`ライブラリをインストールし、メッセージやコマンドを処理するPythonコードを記述して、スクリプトを実行します。より高度な機能やAI連携には、TeleClawのようなプラットフォームがプロセスを大幅に簡素化できます。
このTelegramボットのPythonチュートリアルを理解するために、コーディング経験は必要ですか？
基本的なPythonの知識があれば役立ちますが、このチュートリアルは誰でもアクセスできるように設計されています。各ステップを明確に説明しながら進めます。コードを書かずにTelegramボットを構築したい方には、TeleClawが強力なノーコードツールを提供しています。
TeleClawは私のTelegramボットPythonプロジェクトにどのように役立ちますか？
TeleClawは、高度なAI機能、簡単な連携、堅牢な分析機能を提供することで、TelegramボットPythonプロジェクトを強化できます。Pythonベースのカスタムボットから始めた場合でも、TeleClawを使用して複雑な自然言語理解、ナレッジベース連携、または複数のボットの効率的な管理を行うことができます。
もっと記事を見る

読み続ける

2026年版：ビジネス向けAIエージェント徹底比較ガイド【カテゴリ別】
Guides

2026年版：ビジネス向けAIエージェント徹底比較ガイド【カテゴリ別】

2026年、ビジネス向けAIエージェントを比較するならこのガイド。6つの主要カテゴリと、Telegramネイティブエージェント「TeleClaw」がどこに位置するのかを正直に解説します。

記事を読む
TeleClawのクラウドエージェント：Telegramからコーディングエージェントを動かす
AI Agents

TeleClawのクラウドエージェント：Telegramからコーディングエージェントを動かす

TeleClawはOpenRouterのクラウドエージェントカテゴリに掲載されています。クラウドエージェントとは何か、2026年に何が変わったのか、そしてTelegramからクラウドエージェントを動かす方法を学びましょう。

記事を読む