ボット開発

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 はまだリクエスト全体のレート制限を設けていませんが、音声のメソッドには 1 時間あたりの上限があり、429 Too Many Requests: retry after N が返ります（音声通話）。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）

sendDocument

POST/bot<トークン>/sendDocument

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

形式（mime_type）は、ファイル名の拡張子から決めます。アプリから送るファイルは 2GB までですが、ボットが HTTP でアップロード・ダウンロードできるのは、Telegram と同じく 20MB までです。

sendLocation

POST/bot<トークン>/sendLocation

戻り値：送信した Message（location に Location）

sendVenue

POST/bot<トークン>/sendVenue

戻り値：送信した Message（venue に Venue、location にも同じ位置）

title または address がなければ 400 Bad Request: title and address are required になります。

sendContact

POST/bot<トークン>/sendContact

戻り値：送信した Message（contact に Contact）

ボットが送った連絡先カードには user_id が付きません。番号が Pabal のアカウントのものでも同じです — ボットには連絡先がなく、付けてしまうと番号ごとにカードを 1 枚ずつ送って、その番号が誰のものかを調べられるからです。phone_number または first_name がなければ 400 Bad Request: phone_number and first_name are required になります。

editMessageLiveLocation

POST/bot<トークン>/editMessageLiveLocation

戻り値：編集後の Message

すでに終わったライブ位置情報 — 停止したもの、または期間が切れたもの — は、移動することも、期間を延ばして復活させることもできません（400 Bad Request: message can't be edited）。ライブ位置情報でないメッセージも同じです。

最後に反映された移動から 10 秒たっていない移動や、10m も動いていない移動は、サーバーが保存せずに見送ります。停止と、期間・通知半径の変更は常に反映されます。見送った場合に返される Message は最後に反映された位置を示すので、数秒ごとに送っても問題ありません。

stopMessageLiveLocation

POST/bot<トークン>/stopMessageLiveLocation

パラメーターは chat_id、message_id、reply_markup（任意）。ライブ位置情報を最後の位置で止めます。共有期間が実際に経過した時間に縮まるので、すべてのアプリが終了した位置情報として表示します。すでに停止または終了していれば 400 Bad Request: message is not modified: … になります。戻り値：編集後の Message。

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（コマンド）、BOT_COMMAND_DESCRIPTION_INVALID（説明が空か 256 文字超）、BOT_COMMANDS_TOO_MUCH（100 個超）。

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 と、下のうち1 つが含まれます。

User

Chat

Message

MessageEntity

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

PhotoSize

Document

Location

人が共有するライブ位置情報は、サーバーが移動を反映するたびに edited_message としてもう一度届きます。

Venue

Contact

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

音声通話

Pabal にだけあるメソッドです。音声ボットは、アプリから人が電話をかけると AI 音声モデルが応答するボットで、これらのメソッドでそのモデルの設定を決め、通話を扱います。何が有効になっている必要があるか、有効にする方法と例は、音声ボットの案内にあります。メソッドは音声が無効なサーバーにもあって設定を読めますが、音声が無効か、運営者がまだ許可していないボットは、無効にする操作と削除以外に設定を変えられません（403 VOICE_NOT_AVAILABLE）。

setVoiceCallSettings

POST/bot<トークン>/setVoiceCallSettings

ボットの音声の設定を変えます。送った項目だけが変わり、全体を検査してから一度に書き込むか、すべてを拒否します。ボットごとに 1 時間 30 回（@BotFather と合わせて）。

戻り値：True

getVoiceCallSettings

GET/bot<トークン>/getVoiceCallSettings

パラメーターなし。現在の設定と、ボットがいま電話を受けられるか（available、unavailable_reason）、サーバーの上限、声と言語の一覧、ツール問い合わせ・文字起こしの届け先、自前のキー・ストリームモード・MCP サーバーの状態。キーとシークレットは表示されず、フィンガープリントだけが表示されます。フィールドは音声ボット — 現在の設定を見るにあります。

戻り値：VoiceCallSettings（オブジェクト）

endVoiceCall

POST/bot<トークン>/endVoiceCall

戻り値：True。このボットの進行中の通話でなければ 400 VOICE_CALL_NOT_FOUND。

sendVoiceCallContext

POST/bot<トークン>/sendVoiceCallContext

戻り値：True。つながる前は VOICE_CALL_NOT_ACTIVE、ストリーム通話は VOICE_CONTEXT_NOT_SUPPORTED、長すぎれば VOICE_CONTEXT_TOO_LONG、通話ごとに 1 分に 10 件を超えると 429。

getVoiceCallUsage

GET/bot<トークン>/getVoiceCallUsage

戻り値：period、from_date、to_date、calls、seconds、missed、refused（busy・budget・unavailable）、platform_seconds、own_key_seconds、remaining_seconds_today（bot・owner）、発信を有効にしたことのあるボットなら outbound（today・limits）— 日付の区切りはサーバーのタイムゾーン

startVoiceCall

POST/bot<トークン>/startVoiceCall

ボットが人に電話をかけます。ボットオーナーが @BotFather で有効にし、運営者が審査したボットが、そのボットに電話を許可した人にだけかけられます。答えと判定は音声ボット — かけるにあります。

戻り値：{"voice_call_id": "…"} — 受け付けたという意味だけで、鳴ったか・出たかは voice_call アップデートで届きます。拒否は 403 VOICE_OUTBOUND_OFF: <理由>、403 USER_UNAVAILABLE（いつも同じ本文）、429、503 VOICE_UNAVAILABLE。Webhook の応答からは呼べません。

answerVoiceCallToolQuery

POST/bot<トークン>/answerVoiceCallToolQuery

戻り値：True。最初の答えが最後です。遅れると 400 TOOL_QUERY_EXPIRED: answered|timeout|cancelled|call_ended|unreachable、知らない id は TOOL_QUERY_ID_INVALID、答えが拒否されると TOOL_RESULT_EMPTY・TOOL_RESULT_INVALID・TOOL_RESULT_TOO_LONG・TOOL_ERROR_TOO_LONG・TOOL_RESULT_REFUSED: <コード>。Webhook のツール問い合わせの POST には、レスポンス本文でも答えられます。

setVoiceCallApiKey · deleteVoiceCallApiKey

POST/bot<トークン>/setVoiceCallApiKey

戻り値：True — ゲートウェイのテストセッションを通ったあとでだけ保管します。API_KEY_INVALID、API_KEY_NO_REALTIME_ACCESS、503 API_KEY_CHECK_UNAVAILABLE（保管しない）、403 VOICE_OWN_KEY_NOT_AVAILABLE（このサーバーは自前のキーを受け付けない）。deleteVoiceCallApiKey はパラメーターなしで、いつでも True。どちらのメソッドも bots.sendCustomRequest では呼べず、setVoiceCallApiKey は Webhook のレスポンスでも呼べません。詳しくは自前のモデルキー。

MCP サーバーのメソッド

auth とシークレットはリクエスト本文でのみ送ります。MCP が無効なサーバーでは 403 VOICE_NOT_AVAILABLE: MCP tools are not available on this server。詳しくは音声ボット — MCP サーバー。

音声のアップデートを受け取るには

voice_call、voice_call_tool_query、voice_call_transcript は名前で求めた場合にだけ届きます — getUpdates か setWebhook の allowed_updates に書いてください。空のリストでは届かず、求める前に起きたものはためられません。ツール問い合わせは、Webhook があれば別に送る POST で、直近 15 秒以内に getUpdates を呼んでいれば次の getUpdates の先頭に届きます。

VoiceCall

VoiceCall には、発信者が会話を残すことを選んだかどうかを知らせるフィールドはありません。意図したものです — その文章は発信者自身のもので、ボットには送られません。そのため、会話を残す機能が有効なサーバーでは、ストリームモード以外のすべての通話の ended が同じだけ待ち、通話記録の次のメッセージ番号も、すべての通話で記録より 31 以上大きくなります（番号をあらかじめ確保するため）。

VoiceCallToolQuery

VoiceCallTranscript

HTTP Bot API でだけ届きます。通話全体は、終わった voice_call の transcript にあります。

ストリームモード（mode=stream）

ストリームモードでは、通話の音声が Pabal の AI モデルの代わりにボットのオーナーのサーバーに送られます。setVoiceCallSettings に mode=stream、stream_url=wss://…、stream_secret=…（32〜128 文字の表示可能な ASCII、リクエスト本文でのみ）を送ると、Pabal のゲートウェイがそのアドレスに 1 回接続してみて（プローブ）、成功すれば有効になります。ボットオーナー規約と、ストリーム用の確認画面を含むアプリのビルドが必要です。設定・プローブの結果・例は音声ボット — ストリームモードにあります。

• 接続：TLS 1.2 以上、URL の名前に合う公的な証明書、サブプロトコル pabal.voice.v1、圧縮なし、1 メッセージ 64KiB・テキスト 4KiB まで、リダイレクトなし。
• 署名：X-Pabal-Voice-Signature: t=…,nonce=…,call=…,v1=HMAC-SHA256(stream_secret, "pabal-voice-stream/1\n<t>\n<nonce>\n<call>\n<host>\n<path?query>")。host は自分が伝えた URL のホスト。300 秒・nonce は 1 回だけ・バイトどうしの比較・start.call_id が call と同じかを確認（詳しく）。
• 音声：テキストメッセージは JSON のイベント、バイナリは PCM16 リトルエンディアン・モノラル・24 kHz。発信者の音声は 20 ms（960 バイト）単位。
• Pabal → ボット：start（1 回） · live（AI の案内が終わった） · 音声 · mark · cleared · buffer_full · stop（→ 1000 で閉じる）。
• ボット → Pabal：ready（start のあと 3 秒以内、いちばん最初に） · 音声（live のあと） · clear · mark · hangup。

メッセージ 1 つずつの形は、音声ボット — 仕様の表にあります。

音声のメソッドのエラー

音声のメソッドのエラーコードと意味は、音声ボット — エラーにまとめてあります。403 は Forbidden: <コード>: <説明> の形で（VOICE_RULES_NOT_ACCEPTED、VOICE_NOT_AVAILABLE、VOICE_SUSPENDED、VOICE_OWNER_TERMS_NOT_ACCEPTED、VOICE_OWN_KEY_NOT_AVAILABLE、VOICE_STREAM_NOT_AVAILABLE、VOICE_OUTBOUND_OFF）、USER_UNAVAILABLE だけは説明なしでいつも Forbidden: USER_UNAVAILABLE です。1 時間の上限を超えると 429 と retry_after です。

Telegram Bot API との違い

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