ボット開発

Bot API リファレンス

Pabal の HTTP Bot API が受け付けるメソッド、やり取りするオブジェクト、エラーを漏れなくまとめました。Telegram Bot API と互換性があります。

Pabal の HTTP Bot API は、Telegram Bot API と同じアドレス形式・リクエスト・レスポンス・エラーを使います。このドキュメントには、Pabal が実際に受け付けるものだけを記載しています。ここにないメソッドは 404 Not Found: method not found を返します。はじめての方は、ボット作成チュートリアルから読んでください。

リクエストの送信

https://pabal.me/bot<トークン>/<メソッド>

• HTTP メソッド：GET と POST のどちらも使えます。
• パラメーターを送る 4 つの方法 — クエリ文字列（?chat_id=1&text=hi）、application/x-www-form-urlencoded、application/json、ファイルをアップロードするときの multipart/form-data。組み合わせて使ってもかまいません。
• オブジェクト型のパラメーター（reply_markup、commands、allowed_updates）は、JSON 本文ではオブジェクト・配列のまま、フォーム・クエリでは JSON 文字列として入れます。
• メソッド名は大文字と小文字を区別しません（sendMessage = sendmessage）。
• 本文のサイズは 12MB までです（超えると 413）。
• ファイルのダウンロードは、別のアドレス https://pabal.me/file/bot<トークン>/<file_path> です（getFile）。

レスポンスとエラー

レスポンスは常に JSON です。成功なら HTTP 200 と result、失敗ならその HTTP ステータスと同じ error_code と、人が読むための description が返ります。

{"ok": true, "result": { … }}

{"ok": false, "error_code": 400, "description": "Bad Request: chat not found"}

Pabal はまだリクエストのレート制限（429 Too Many Requests）を設けていませんが、今後導入される可能性があるため、429 を受け取ったら parameters.retry_after 秒待ってから再送するように実装しておいてください。

アップデートの受信

2 つの方法のどちらかを使います。同時には使えません。

getUpdates

POST/bot<トークン>/getUpdates

待機中のアップデートを取得します（ロングポーリング）。Webhook が設定されていると 409。

戻り値：Array of Update

setWebhook

POST/bot<トークン>/setWebhook

アップデートを HTTPS アドレスで受け取ります。詳しい説明は Webhook のドキュメントにあります。

戻り値：True

deleteWebhook

POST/bot<トークン>/deleteWebhook

Webhook を削除して getUpdates に戻ります。Webhook がなくても成功します。

戻り値：True

getWebhookInfo

GET/bot<トークン>/getWebhookInfo

Webhook の状態。パラメーターなし。Webhook がなければ url は空文字列です。

戻り値：WebhookInfo

メソッド

getMe

GET/bot<トークン>/getMe

トークンが正しいかを確認するときに使います。パラメーターなし。

戻り値：User — ボットの場合は、can_join_groups（true）、can_read_all_group_messages（true）、supports_inline_queries（false）、can_connect_to_business（false）、has_main_web_app（false）が追加されます。

sendMessage

POST/bot<トークン>/sendMessage

戻り値：送信した Message

人に送るには、その人が先にボットに話しかけている必要があります（403 Forbidden: bot can't initiate conversation with a user）。グループに送るには、ボットがそのグループのメンバーである必要があります。

sendPhoto

POST/bot<トークン>/sendPhoto

戻り値：送信した Message（photo に新しい file_id）

editMessageText

POST/bot<トークン>/editMessageText

戻り値：編集後の Message。アプリにはすぐ反映され、人が編集したメッセージはボットに edited_message として届きます。

テキストとボタンが以前とまったく同じなら 400 Bad Request: message is not modified: …、他人のメッセージを編集しようとすると 400 Bad Request: message can't be edited になります。

editMessageCaption

POST/bot<トークン>/editMessageCaption

パラメーターは chat_id、message_id、caption（0〜1,024 文字、省略するとキャプションを削除）、reply_markup。戻り値：編集後の Message。

editMessageReplyMarkup

POST/bot<トークン>/editMessageReplyMarkup

テキストはそのままで、ボタンだけを変更します。パラメーターは chat_id、message_id、reply_markup（省略するとボタンを削除）。戻り値：編集後の Message。

deleteMessage

POST/bot<トークン>/deleteMessage

パラメーターは chat_id、message_id。メッセージを会話の双方から削除します。存在しないメッセージなら 400 Bad Request: message to delete not found。戻り値：True。

answerCallbackQuery

POST/bot<トークン>/answerCallbackQuery

人が押したボタン（CallbackQuery）に応答します。10 秒以内に、1 回だけ応答できます。

戻り値：True。遅すぎた場合やすでに応答済みの場合は 400 Bad Request: query is too old and response timeout expired or query ID is invalid。

sendChatAction

POST/bot<トークン>/sendChatAction

互換性のために受け付けて True を返しますが、まだアプリに「入力中…」は表示しません。

getChat

GET/bot<トークン>/getChat?chat_id=…

パラメーターは chat_id（数値）。人ならその人、グループならボットがメンバーであるグループのみ。戻り値：Chat。存在しないか閲覧できない場合は 400 Bad Request: chat not found。

getFile

GET/bot<トークン>/getFile?file_id=…

受け取った写真の file_id から、ダウンロード用のパスを取得します。戻り値：File。その後、次のアドレスからダウンロードします。

https://pabal.me/file/bot<トークン>/<file_path>

file_id は、その写真を取得する権利でもあります。無効な値なら 400 Bad Request: wrong file identifier/HTTP URL specified。

setMyCommands

POST/bot<トークン>/setMyCommands

戻り値：True。コマンドのルールに合わない場合は 400 Bad Request: BOT_COMMAND_INVALID。

getMyCommands

GET/bot<トークン>/getMyCommands

パラメーターは language_code（任意）。戻り値：Array of BotCommand。

deleteMyCommands

POST/bot<トークン>/deleteMyCommands

パラメーターは language_code（任意）。その一覧を空にします。戻り値：True。

logOut · close

Telegram では、ローカルの Bot API サーバーへ移行するときに使うメソッドです。Pabal には移行先がないため、受け付けて True を返すだけです。トークンを無効にするには、BotFather の /revoke を使ってください。

オブジェクト

フィールドの横の 任意 は、含まれない場合があることを示します。ここにない Telegram のほかのフィールドを、Pabal は送りません。

Update

1 件の新着。update_id と、下の 3 つのうち1 つが含まれます。

User

Chat

Message

MessageEntity

サーバーがテキストから自動的に見つけて付けます。太字・斜体のような書式のエンティティはまだありません。

PhotoSize

File

CallbackQuery

InlineKeyboardMarkup

inline_keyboard：Array of Array of InlineKeyboardButton — 外側の配列が行、内側の配列が 1 行分のボタンです。1 つのメッセージに最大 100 行・100 個。

InlineKeyboardButton

switch_inline_query、web_app、login_url、pay のようなほかの種類はまだありません（400）。

ReplyKeyboardMarkup

KeyboardButton

文字列 1 つ、または text と任意のフィールド request_contact（自分の連絡先を送る）・request_location（現在地を送る、Boolean）を持つオブジェクト。

ReplyKeyboardRemove

{"remove_keyboard": true} — ボタンパネルを隠します。selective は任意。

ForceReply

{"force_reply": true} — アプリが、このメッセージへの返信状態で入力欄を開きます。selective、input_field_placeholder は任意。

BotCommand

WebhookInfo

Telegram Bot API との違い

• アップデートの種類：message、edited_message、callback_query のみ届きます。チャンネルの投稿、インラインクエリ、決済、投票、メンバーの変更（my_chat_member）などはありません。
• 書式：parse_mode・entities を無視し、文字どおりに送ります。コマンド・メンション・URL・ハッシュタグだけが自動的に表示されます。
• チャットの種類：1:1 と基本グループのみ。チャンネル・スーパーグループ・フォーラムのトピックはありません。
• メディア：写真のみ。文書・動画・音声・ステッカー・アルバム、URL を指定しての送信はありません。
• グループ内のボット：プライバシーモードがないため、グループのすべてのメッセージを受け取ります。
• キュー：未取得のアップデートはボットごとに直近 1,000 件までメモリに保持し、サーバーの再起動時に消えます（Telegram は 24 時間保持）。
• Webhook：一度に 1 つずつ順番に送り（max_connections は保持のみ）、自己署名証明書は受け付けず、ポートの制限はありません。
• ID：ユーザー・メッセージ・ファイルの ID は、このサーバーの中でのみ意味を持ちます。チャンネル・スーパーグループがないため、-100… 形式の ID もありません。
• 存在しないメソッド：上の一覧にないもの（forwardMessage、copyMessage、sendDocument、sendPoll、getChatMember、banChatMember、answerInlineQuery …）は 404 Not Found: method not found。