telegram

Telegram

Telegram Bot API（https://api.telegram.org/bot<token>/<method>）を利用する Telegram ボット用スクリプトです。テキスト、メディア、位置情報、連絡先、アンケートを送信し、メッセージの編集、削除、転送、コピー、ピン留めを行えます。また、ボットがやり取りするチャット、メンバー、ファイルを特定できます。すべてのスクリプトはボットとして動作します。ボットがメッセージを送るチャットには、ボットがメンバーとして参加している必要があります。また、ボットからユーザーにダイレクトメッセージを送るには、ユーザーが先にボットへメッセージを送っている必要があります。

Telegram 用の独立した非公式コネクターです。Telegram との提携、推奨、後援を受けていません。「Telegram」はその所有者の商標であり、このコネクターが対応するサービスを特定する目的でのみ使用しています。

使用する場面

• エージェントが Telegram ボットを使って、チャットにメッセージ、写真、ドキュメント、動画、音声、位置情報、連絡先、またはアンケートを送信する必要がある場合。
• エージェントがボットから送信したメッセージを管理する必要がある場合（編集、削除、転送、コピー、ピン留め、ピン留め解除）。
• エージェントがチャットやメンバーを特定する必要がある場合（listRecentChats で chat_id を検索、getChat でチャットを確認、getChatMember でメンバーの役割を確認、または管理者の一覧を取得）。

セットアップ

これは agentskills.io のスキルです。

コネクターがまだスキルとしてインストールされていない場合は、まず npx skills add zapier/connectors --skill telegram（または、お使いのハーネス独自のスキルインストール方法）でインストールしてから、ここに戻ってください。スキルのインストールでコピーされるのはこれらのファイルであり、依存関係ではありません。CLI、ローカル MCP サーバー、または zapier-sdk の認証コマンドを実行する前に、ここで一度 npm install --omit=dev を実行してください。このパッケージを依存関係として自分のプロジェクトにインポートする場合は、npm install によって必要なものがすでにすべて解決されています。詳しくは references/use-as-sdk.md をご覧ください。

references/ を参照したり、このコネクターのテストを実行したり、コードを変更したりするために、リポジトリの実際のソースが必要ですか？範囲を絞った git clone については README.md をご覧ください。

このコネクターの実行には Node.js 22.18+ が必要です。実行方法に合ったリファレンスを選び、ほかの作業を始める前に読み込んでください。

環境	読み込むリファレンス
MCP 対応クライアントを使用している（ツールがすでに読み込まれている場合があります（例：mcp__telegram__<tool>）。または、自分でローカルサーバーを登録するか、ユーザーに登録を案内できます）	references/use-as-mcp.md
ターミナル／サブプロセスにアクセスできる（node を実行できる）	references/use-as-cli.md
自分のコードのみを使用し、このパッケージを依存関係としてインポートする	references/use-as-sdk.md
ツールやターミナルにアクセスできず、このパッケージをインポートすることもできないため、自分でコードを書いて Telegram API を直接呼び出す（例：コード実行サンドボックス）	references/use-as-recipe.md

スクリプト

すべてのスクリプトは、単一の telegram 接続を使用します。

スクリプト	スクリプト名	接続	説明
scripts/sendMessage.ts	sendMessage	単一（telegram）	チャットにテキストメッセージを送信します。
scripts/sendPhoto.ts	sendPhoto	単一（telegram）	URL または file_id を指定して写真を送信します。
scripts/sendDocument.ts	sendDocument	単一（telegram）	URL または file_id を指定してファイル／ドキュメントを送信します。
scripts/sendVideo.ts	sendVideo	単一（telegram）	URL または file_id を指定して動画を送信します。
scripts/sendAudio.ts	sendAudio	単一（telegram）	URL または file_id を指定して音声ファイル（音楽）を送信します。
scripts/sendLocation.ts	sendLocation	単一（telegram）	地図上の地点を送信します。
scripts/sendContact.ts	sendContact	単一（telegram）	電話連絡先を送信します。
scripts/sendPoll.ts	sendPoll	単一（telegram）	投票またはクイズを送信します。
scripts/editMessageText.ts	editMessageText	単一（telegram）	ボットが送信したメッセージのテキストを編集します。
scripts/deleteMessage.ts	deleteMessage	単一（telegram）	チャットからメッセージを削除します。
scripts/forwardMessage.ts	forwardMessage	単一（telegram）	出典を表示したままメッセージを転送します。
scripts/copyMessage.ts	copyMessage	単一（telegram）	出典を表示せずにメッセージの内容をコピーします。
scripts/pinChatMessage.ts	pinChatMessage	単一（telegram）	チャットにメッセージをピン留めします。
scripts/unpinChatMessage.ts	unpinChatMessage	単一（telegram）	メッセージ（または最新のピン留め）を解除します。
scripts/getMe.ts	getMe	単一（telegram）	ボットの身元を取得し、トークンを検証します。
scripts/getChat.ts	getChat	単一（telegram）	ID または @username でチャットの情報を取得します。
scripts/listRecentChats.ts	listRecentChats	単一（telegram）	ボットが最近やり取りしたチャットを一覧表示します（chat_id リゾルバー）。
scripts/getChatMember.ts	getChatMember	単一（telegram）	チャット内のメンバーのステータスと役割を取得します。
scripts/getChatAdministrators.ts	getChatAdministrators	単一（telegram）	チャットの管理者を一覧表示します。
scripts/getChatMemberCount.ts	getChatMemberCount	単一（telegram）	チャットのメンバー数を取得します。
scripts/getFile.ts	getFile	単一（telegram）	ファイルのメタデータとダウンロードパスを取得します。

曖昧さの解消と拒否

• 送信前にchat_idを解決してください。推測してはいけません。 chat_idは数値のID（スーパーグループ／チャンネルの場合は-100で始まります）または公開@usernameです。ユーザーがIDを把握していないチャットを指定した場合は、listRecentChats（ボットに最近メッセージを送信したチャット）またはgetChat（既知のID／ユーザー名）で解決してください。listRecentChatsが、ユーザーの説明に一致する同名のチャットを2つ返した場合は、いったん停止してどちらか確認してください。それぞれのtypeとIDを示します。一致するチャットが1つだけの場合は、そのチャットに対して操作し、それ以上確認を求めないでください。
• ボットにアクセスできる必要があります。 ボットがメッセージを送れるのは、参加しているチャットだけです。また、プライベートチャットを開始することはできません。ユーザーが先にボットへメッセージを送る必要があります。送信が「bot can't initiate conversation」または「chat not found」で失敗した場合は、その旨を伝えて停止してください。別のチャットに対して再試行してはいけません。
• 対応していない操作。 このコネクターでは、チャットの作成／管理、メンバーのBANまたは昇格、招待リンクの管理、ローカルファイルのアップロード（代わりにHTTPS URLまたはTelegramのfile_idを指定してください）、ゲーム／支払いの実行には対応していません。これらを依頼された場合は、対応していないことを伝えてください。別のツールで代用したり、実行していない操作を成功したと報告したりしてはいけません。

認証

すべてのシェイプでは、シークレットではなく、1つの接続セレクター（[<resolver>:]<value>形式の文字列）を使って認証します。すべてのコネクターでzapier:<connection-id>（Zapier管理の認証。Zapierの認証、再試行、ガバナンスのレイヤーを経由します）を使用できます。また、一部のコネクターでは1つ以上の直接トークン用リゾルバーも使用できます（名前と数はコネクターによって異なります）。推測せず、このコネクター独自のリゾルバーを確認してください。<resolver>:のプレフィックスは省略できます。プレフィックスなしの値は、最初に該当するリゾルバーに渡されます。UUID形式の値は、常にzapier:に該当します。各スクリプトでは、必要な接続と、受け付けるリゾルバーが宣言されています。接続を渡す正確な構文や、このコネクターのリゾルバー一覧の確認方法は、シェイプによって異なります。上で読み込んだリファレンスを参照してください。

すでに設定済みのものを先に確認しますか？そのために環境変数の値を出力してはいけません。envやenv | grep <name>を実行すると、名前とともに値が出力され、設定されている場合は有効な認証情報がトランスクリプトに漏れる可能性があります。名前だけを確認するには（env | cut -d= -f1 | grep -i <name>）、または既知の名前を直接テストしてください（[ -n "$VAR_NAME" ]）。

接続がまだありませんか？いずれかを選び、その取得には各リファレンス独自の手順に従ってください。ユーザーが接続IDやトークンをすでに覚えているかのように、ただ尋ねてはいけません。

	読み込み
認証情報を直接渡す	references/use-without-zapier.md
Zapier接続経由でルーティングする	references/use-with-zapier.md

出力形式

すべてのスクリプトは { data, meta } エンベロープを返します。

• data — スクリプトの結果（outputSchema が宣言する形式です。スクリプトの正確なスキーマを確認する方法については、上で読み込んだリファレンスを参照してください）。
• meta.outputDataValidation — data の検証結果です。
  • { skipped: false, droppedPaths: null } — 検証済みで、削除された項目はありません。
  • { skipped: false, droppedPaths: [...], instruction } — 検証済みですが、該当するパスは data から除外されました。これらはスクリプトが API から返したものの、outputSchema で宣言されていないフィールドです。必要な場合は、出力検証をスキップして再実行してください。
  • { skipped: true } — 検証がバイパスされ、data はスクリプトの未加工で未検証の出力です。

除外されたフィールドの確認／skipOutputDataValidation。 未加工で未検証の結果を受け取るには、出力検証を無効にしてください（正確な構文はスクリプトの形式によって異なります。上で読み込んだリファレンスを参照してください）。入力検証はスキップされません。

結果の絞り込み／filterOutputData。 大きな結果から必要なフィールドだけを取り出すには、data を後処理する jq 式を渡してください（正確な構文は形式によって異なります）。jq は { data, meta } エンベロープではなく data のみに適用されるため、data をルートとして記述してください（出力スキーマを確認するには、スクリプトの --help（または形式に応じた同等のコマンド）を実行してください）。変換後の値が data に置き換わり、meta は保持されます。また、結果は出力スキーマに対して再検証されません。

リファレンス

該当する領域で作業する前に、対応するリファレンスファイルを読み込んでください。

リファレンス	対象	読み込むタイミング
references/telegram-api-gotchas.md	HTML と MarkdownV2 のエスケープ、ファイル URL のサイズ制限、getFile の 1 時間有効なリンク、コピーと転送の違い、メッセージの削除／ピン留め、投票の作成、ok:false／error_code／retry_after／migrate_to_chat_id のエラーエンベロープ、レート制限	書式付きテキストの送信、ファイルのアップロード／ダウンロード、コピーと転送の使い分け、メッセージの削除／ピン留め、投票の作成、API エラーやレート制限への対処を行う前。