Telegram Bot APIチュートリアル：初めてのボットを開発しよう

Telegram Bot APIの最速チュートリアルは、たった3つのコマンドで完結します。BotFatherからトークンを取得し、getUpdatesを呼び出してメッセージを読み込み、sendMessageを呼び出して返信するだけです。ボット開発のすべては、このループの上に成り立っています。このガイドでは、最初のcURLリクエストから、Webhookとライブラリを備えた動作中のボットまで、その全過程を解説します。

Bot APIはHTTPインターフェースなので、アプリケーションコードを1行も書く前にcurlでテストできます。これは、学習しやすいAPIの一つと言えるでしょう。もしあなたが、今日中に動くボットが欲しい開発者、あるいはTeleClawのようなノーコードプラットフォームとコードを比較検討しているビルダーなら、まさにぴったりの場所です。

この記事を読み終える頃には、APIがどのようにリクエストを認証するのか、メッセージの送受信方法、ロングポーリングとWebhookの違い、そしてほとんどの最初のボットが陥りがちなレート制限について理解できるようになるでしょう。

主なポイント

• ボットは単なるHTTPクライアントです。 すべてのメソッドはhttps://api.telegram.org/bot<TOKEN>/METHOD_NAMEへのリクエストなので、cURLだけで始めることができます。
• 3つのコアメソッドで動作します。 トークンを確認するためのgetMe、メッセージを読み取るためのgetUpdates、返信するsendMessageです。
• ロングポーリングとWebhookは排他的です。 ローカルテストにはポーリングを使用し、本番環境ではWebhookに切り替えます。
• APIは無料ですが、 Telegramは異なるユーザーへの一括送信を毎秒約30メッセージ、チャットごとに毎秒1メッセージに制限しています。
• スクリプト以上のボットに成長したら、ライブラリを使うと時間を節約できます。 python-telegram-bot、aiogram、またはTelegrafを使用しましょう。

Telegram Bot APIとは？

Telegram Bot APIは、コードをボットを通じてTelegramに接続するためのHTTPベースのインターフェースです。Telegramの開発者向け紹介によると、ボットは電話番号を必要としない特別なアカウントであり、サーバー上で実行されるコードのインターフェースとして機能します。

あなたが行うすべてのリクエストは、ユーザーアカウントではなくボットトークンで認証されます。トークンはボットを識別するため、パスワードのように扱い、公開リポジトリにコミットしてはいけません。Telegramのドキュメントには、「トークンは安全な場所に保存し、共有しないでください」と明記されています。

API自体は無料です。TelegramはBot APIをリリース以来無料で提供しており、メッセージごとの料金や作成できるボットの数に上限はありません。そのため、多くのコミュニティツール、サポートアシスタント、自動化がこのAPI上で動作しています。プラットフォームを初めて利用する場合は、Telegramボットの作成方法に関するガイドで、アカウント設定について詳しく説明しています。

ステップ1：BotFatherからボットトークンを取得する

Telegramを開き、他のボットを作成・管理するための公式ボットである**@BotFather**を検索します。チャットを開始し、/newbotコマンドを送信します。

BotFatherは次に、以下の2つのことを順に尋ねます。

1. ボットの表示名（例：「First API Bot」）
2. botで終わるユーザー名（例：first_api_demo_bot）

完了すると、BotFatherは123456789:AAExampleTokenStringHereのようなAPIトークンを返します。このトークンが、このチュートリアルの残りの部分で必要となる唯一の認証情報です。

注意点： あなたのトークンを持っている人は誰でもあなたのボットを制御できます。ソースコードではなく、環境変数に保存してください。もし漏洩した場合は、BotFatherに/revokeを送信して新しいものを取得しましょう。

ステップ2：最初のBot APIメソッドを呼び出す

プログラムを書き始める前に、トークンが機能することを確認しましょう。getMeメソッドはボットの基本情報を返し、標準的なヘルスチェックとして機能します。<YOUR_TOKEN>をBotFatherから取得した値に置き換えてください。

curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

成功した場合のレスポンスは、"ok": trueとボットのID、名前、ユーザー名を含むJSONです。"ok": falseが表示された場合、トークンが間違っているか、タイプミスがあります。

この単一のリクエストが、全体のパターンです。すべてのTelegram Bot APIメソッドは同じ形式に従います。https://api.telegram.org/bot<TOKEN>/METHOD_NAMEへのHTTPS呼び出しで、クエリ文字列またはPOSTボディにパラメータを含み、JSONオブジェクトが返されます。完全なリストはBot APIリファレンスにあり、必要なすべてのメソッドとオブジェクトが記載されています。

ステップ3：メッセージの受信と送信

次に、ボットを役立つものにしましょう。初心者が驚くルールが一つあります。ボットは会話を開始できません。ユーザーが最初にボットにメッセージを送る必要があります。なので、Telegramでボットを開き、「hello」のような任意のテキストを送信してください。

次に、getUpdatesでそのメッセージを読み取ります。これはロングポーリングを使用して受信した更新を取得し、更新オブジェクトの配列を返します。

curl https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates

レスポンスでmessage.chat.idを見つけてください。そのchat_idが返信先のアドレスです。それをコピーし、sendMessageを呼び出します。

curl -X POST https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage \
 -d chat_id=<CHAT_ID> \
 -d text="Hello from my first bot"

あなたのボットがチャットで返信します。getUpdatesで読み取り、sendMessageで応答するというこの往復が、ほとんどのTelegramボットの核となるループです。textパラメータはメッセージごとに最大4096文字を受け入れるため、長い返信は分割する必要があります。

このTelegram Bot APIの例を実際のコードにスケールアップする際に覚えておくべき2つの詳細があります。

• オフセットを再計算する。 次のgetUpdates呼び出しで、最後の更新のupdate_idに1を加えた値をoffsetパラメータとして渡さないと、Telegramは同じ更新を返し続けます。
• 一度に1つのメソッド。 Webhookを登録した瞬間、getUpdatesは機能しなくなります。これは次のステップのトピックです。

ステップ4：ロングポーリングかWebhookかを選択する

Telegramは更新を受信する2つの方法を提供しており、ボットごとに一度に1つしか使用できません。

• ロングポーリングとは、コードが繰り返しgetUpdatesを呼び出すことを意味します。公開URLが不要で、実行し続けるプロセスさえあればよいため、学習やローカル開発には最も簡単な方法です。
• Webhookとは、Telegramが各更新を発生した瞬間にPOSTリクエストとしてHTTPSエンドポイントにプッシュすることを意味します。これは本番環境の標準であり、低レイテンシ、アイドルポーリングなし、安定したトラフィック下でのスケーラビリティに優れています。

Webhookに切り替えるには、公開HTTPS URLを一度登録します。

curl "https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook?url=https://yourdomain.com/webhook"

エンドポイントには有効なTLS証明書が必要で、HTTP 200を迅速に返す必要があります。更新が届かなくなった場合、最初に行うべきことは常にエラーの調査です。完全な登録、検証、トラブルシューティングの流れについては、TelegramボットのWebhook設定ガイドをご覧ください。簡単に言えば、構築中はポーリングから始め、リリース前にWebhookに移行しましょう。

ステップ5：APIをライブラリでラップする

生のcURLは学習には最適ですが、本番環境のボットはライブラリを使用します。ライブラリはAPI呼び出し、更新の解析、再試行、会話の状態を処理するため、ボット固有のロジックのみを記述すれば済みます。Telegramは、Bot APIサンプルページで、ほぼすべての言語に対応するコミュニティライブラリをリストアップしています。

すでに知っている言語で選びましょう。

• Python: python-telegram-botは純粋なPythonで、完全に非同期であり、Python 3.10以降をサポートしています。aiogramとpyTelegramBotAPIも人気のある選択肢です。
• Node.js: Telegrafは成熟しており、TypeScriptに優しいです。node-telegram-bot-apiは長年の実績があります。

以下は、Telegram Bot API Pythonチュートリアルで最も一般的な出発点であるPythonでの同じエコーボットです。

from telegram import Update
from telegram.ext import Application, MessageHandler, filters, ContextTypes

TOKEN = "YOUR_TOKEN"

async def echo(update: Update, context: ContextTypes. DEFAULT_TYPE):
 await update.message.reply_text(update.message.text)

app = Application.builder().token(TOKEN).build()
app.add_handler(MessageHandler(filters. TEXT & ~filters. COMMAND, echo))
app.run_polling()

そして、Telegrafを使ったNode.jsの同等のコードです。

import { Telegraf } from 'telegraf'

const bot = new Telegraf(process.env. BOT_TOKEN)
bot.on('text', (ctx) => ctx.reply(ctx.message.text))
bot.launch()

どちらもステップ3のcURLループと同じ仕事をしますが、数行で、面倒な部分は処理されています。サポートボットを試作しているバックエンド開発者のマリアは、cURLテストからpython-telegram-botに1日で移行し、同じ日にコマンドハンドラーとインラインボタンを動作させました。ライブラリは同じHTTPメソッドの薄いラッパーであるため、APIの概念は直接引き継がれました。

知っておくべきレート制限とクォータ

APIは無料ですが、無制限ではありません。TelegramのボットFAQには、ボットがスロットリングされないようにするためのガイドラインが記載されています。

• チャットごとに毎秒1メッセージ。 単一の会話では、それよりも速く送信しないようにしましょう。
• 多くの異なるユーザーに送信する場合、合計で毎秒約30メッセージ。 これを超えると、HTTP 429 “Too Many Requests” レスポンスを受け取り始めます。
• 同じグループには毎分約20メッセージ。

ブロードキャストが本当にそれ以上の速度を必要とする場合、@BotFatherで有料ブロードキャストを有効にすることで、上限を毎秒1000メッセージまで引き上げることができます。毎秒30メッセージを超えるメッセージは、Telegram Stars 0.1個分の費用がかかります。ほとんどのボットにはこれは必要ありませんが、通知機能を設計する前に制限があることを知っておくと良いでしょう。

429エラーを受け取った場合は、Telegramが返すretry_afterの値を読み取り、その秒数だけ一時停止して対応しましょう。ライブラリはこれを自動的に処理してくれるため、トラフィックが本格的になったら生のHTTPリクエストから卒業するもう一つの理由となります。

コード不要：サーバーなしのAIボット

すべてのプロジェクトにカスタムコードベースが必要なわけではありません。TelegramグループでAIアシスタントを構築することが目標であれば、Bot APIは自分でメンテナンスしたくないインフラ（特にホスティング、HTTPS、Webhookレイヤー）かもしれません。

TeleClawは、ボットの実行とClaude AIの接続を自動で行うノーコードプラットフォームです。グループに@clawを追加し、BotFatherトークンをダッシュボードに貼り付け、setWebhookやレート制限の処理に触れることなく動作を設定できます。4,000人のメンバーを抱える仮想通貨コミュニティを運営するトーマスは、未完成のカスタムボットをTeleClawに置き換え、同じ日の夜にはAIによるモデレーションとFAQの回答を稼働させました。

基盤となるのは同じBot APIです。サーバーレイヤーを自分で運用するか、プラットフォームに任せるかを選択するだけです。TeleClawの機能ページでその内容を確認し、最高のTelegramボットまとめでオプションを比較検討してください。純粋なダッシュボードでの構築については、ノーコードTelegramチャットボットガイドをご覧ください。

まとめ

これで、Telegram Bot APIの動作モデルを理解できました。BotFatherからのトークン、getMe、getUpdates、sendMessageのようなHTTPメソッド、ロングポーリングとWebhookの選択、そしてボットが成長したときにすべてをラップするライブラリです。APIは無料で、十分に文書化されており、cURLで数分でテストできるほど親しみやすいものです。

最も速い次のステップは、最も小さな一歩です。@BotFatherを開き、/newbotを実行し、最初のgetMeリクエストを送信してトークンを確認しましょう。そこからPythonやNodeで構築することも、サーバーを完全にスキップすることもできます。AI搭載ボットを数日ではなく数分で起動するには、グループに@clawを追加し、TeleClawダッシュボードで設定してください。