【ITニュース解説】Manage Telegram Callback Queries and Inline Keyboards in PHP

この記事は、システムエンジニアを目指す初心者がTelegramボットをPHPで開発する際に役立つ、インラインキーボードとコールバッククエリの具体的な扱い方を解説している。特に、フレームワークに頼らず、PHPの標準機能を使ってTelegram Bot APIと直接HTTP通信を行う「低レベル」な方法に焦点を当てている点が特徴だ。

まず、TelegramボットAPIとの連携において重要なのが「64バイトのペイロード制約」である。これは、インラインキーボードのボタンが押されたときにサーバーに送られるcallback_dataというデータが、最大で64バイトまでという厳格な制限があることを意味する。この制約のため、ボタンに複雑なデータ構造（例えば、JSON形式の大きなオブジェクトなど）を直接含めることはできない。もし試みると、APIエラーになったり、データが途中で切れてしまったりする可能性がある。効率的にデータを渡すには、例えば「act:id」（アクションタイプ:エンティティID）のように短いプレフィックスと識別子を組み合わせた形式を使う方法が推奨されている。また、複数のステップにわたる複雑な状態は、ボットのサーバー側（データベースやキャッシュシステム）に保存し、ボタンにはその状態を識別するためのIDや一時的なトークンだけを渡すのが賢明である。これにより、64バイトの制限を回避しつつ、セキュアで効率的なデータ管理が可能となる。

次に、Telegram Bot APIへリクエストを送信する際の「堅牢なHTTPチェック」の重要性を説明している。PHPでcURLライブラリを使ってAPIを呼び出す場合、単にリクエストを送信するだけでなく、様々なエラーケースを考慮する必要がある。具体的には、ネットワーク接続の失敗、HTTPステータスコードが200番台以外（例えば404エラーや500エラー）の場合、受信したレスポンスが正しいJSON形式ではない場合、そしてTelegram API自体がエラーを返した場合（レスポンス内のokフィールドがfalseの場合）などが考えられる。記事では、これらの可能性を網羅的にチェックし、エラーが発生した際には適切な例外をスローするcallTelegramApi関数を提示している。このような徹底したエラーハンドリングは、予期せぬ問題からアプリケーションを保護し、安定したボット運用に不可欠なものとなる。cURLの各種オプション（CURLOPT_RETURNTRANSFERでレスポンスを文字列として取得、CURLOPT_POSTでPOSTリクエスト、CURLOPT_POSTFIELDSで送信データを指定するなど）も、その設定がAPI通信の挙動にどう影響するかを理解する上で役立つだろう。

インラインキーボード付きのメッセージを送信する手順も解説されている。ユーザーに承認/却下などの選択を促すメッセージを送るsendApprovalRequest関数が良い例だ。この関数では、inline_keyboardという構造体を使ってボタンを定義する。各ボタンにはユーザーに表示されるtextと、ボタンが押されたときにボットに送り返されるcallback_dataを設定する。このcallback_dataには前述の64バイト制限が適用されるため、例えば"app:{$entityId}"（承認:エンティティID）のようなコンパクトな形式が使われている。このキーボード情報をsendMessageメソッドのreply_markupパラメータに含めて送信することで、ボタン付きのメッセージがユーザーのチャットに表示される。

ユーザーがインラインボタンをタップした際の「コールバッククエリの処理とUIの更新」は、ボット開発の核心部分だ。ユーザーがボタンを押すと、TelegramはボットのWebフックにupdate情報の一部としてcallback_queryを送信する。このイベントを処理する際には、2つのフェーズがある。まず第一に、answerCallbackQueryメソッドをすぐに呼び出すことだ。これにより、ユーザーのTelegramクライアント上で表示される「処理中」のスピナーが消え、ユーザー体験が向上する。次に、callback_queryに含まれるcallback_dataを解析し、それに応じたビジネスロジックを実行する。例えば、「app」なら承認処理、「rej」なら却下処理を実行するといった具合だ。処理が完了したら、editMessageTextメソッドを使って、元のメッセージの内容を更新する。これにより、ボタンが押された結果（例：「リクエストは承認されました」）が元のメッセージに反映され、ボタン自体を消すことも可能になる。

最後に、本番環境での運用を考慮したいくつかの注意点が挙げられている。PHPのstrlen()関数は文字列のバイト長を測定するが、これがTelegramの64バイト制限と合致するため、特にマルチバイト文字（日本語など）を扱う際にはこの特性を理解しておくことが重要だ。また、editMessageTextで更新を試みる際、送信しようとするテキストが既存のメッセージと全く同じ内容だと、Telegram APIから「メッセージが変更されていない」というエラーが返される場合がある。これを避けるためには、サーバー側で現在のメッセージ状態を確認し、実際に変更が必要な場合にのみ更新リクエストを送るべきである。さらに、callback_dataはユーザー側で簡単に改ざんできる可能性があるため、セキュリティの観点から、このデータだけで承認などの重要なアクションを決定してはならない。必ずcallback_queryに含まれるユーザーのID（$callbackQuery['from']['id']）を使って、ボットのサーバー側でそのユーザーに適切な権限があるかを確認する「権限チェック」を行う必要がある。

このように、この記事はTelegramボット開発におけるインラインキーボードとコールバッククエリの低レベルな扱い方を、具体的なPHPコード例を交えながら、エラーハンドリングやセキュリティ面にも配慮して解説しており、システムエンジニアを目指す初心者にとって実践的な知識を提供している。