TelegramとGoogle Sheetsで支出管理ボットを作る

コーヒー、バスのチケット、ノート。シートを開くころには、小さな買い物を忘れてしまいがちです。記録に必要なのがTelegramのメッセージ1通で、月の合計ももう1通で確認できたらどうでしょう。

このチュートリアルでは、TelegramとGoogle Sheetsによる支出管理ボット Pocket Ledger を作ります。買い物の内容を送り、提案された詳細を確認して確定したら、月の合計を質問できます。行の保存と計算はシートが担当し、ボットは会話を担当します。こちらが完成した姿です。

最初の目標はコーヒー1杯の保存。次の目標はシートで確認できる合計の取得です。チャットの「保存しました」という返答だけでは、確認が半分しか終わっていない理由も学びます。

Pocket Ledger設定キットをダウンロードすると、書式設定済みのスターターワークブック、アバター、プロンプト、Action設定、テスト用シートが手に入ります。Quickchat AIが作成したシートにワークブックをインポートし、以下の手順を進めてください。スクリーンショットと結果を比較できるよう、コピー用の例は英語と2026年11月で統一しています。

Telegramの支出管理ボットを作るには何が必要ですか？

Telegram、Googleアカウント、Quickchat AIアカウントが必要です。ダッシュボードの設定と表計算の数式を使うため、プログラムをホストする必要はありません。

1. Quickchat AIアカウントを作成し、認証を完了して、Pocket LedgerというAgentを作ります。
2. 新しいシート用にGoogleアカウントを用意します。まずは下記の架空の記録を使います。
3. この演習には新しいTelegramボットを使います。最後のアクセス確認に使う、信頼できる2つ目のTelegramアカウントも用意してください。

Quickchat AIのFreeプランは個人の非商用学習向けで、利用枠に上限があります。AIの会話とSimulation Testingはクレジットを消費します。継続利用のプランを選ぶ前に、現在のプランと利用枠を確認してください。

2つの方向に2つのActionsを使います。行を保存できるだけでは、Agentは過去の合計を読み取れません。

ステップ1：自分用のTelegramボットを接続するには？

BotFatherがボットの名義を作り、Quickchat AIがメッセージに回答するAgentを提供します。

公式の@BotFatherを開き、/newbotを送信します。ボットの名前をPocket Ledgerにして、末尾がbotの未使用のユーザー名を選びます。/setuserpicでキット内のアバターをアップロードしてください。トークンは秘密にしておきます。あとでQuickchat AIに直接貼り付けます。

Quickchat AIでExternal Apps → Telegram → Your own botを開きます。Connect to TelegramダイアログのBot Tokenに認証情報を貼り付けます。Enable your own botをオンにしてSaveを選択します。BotFatherの手順ガイドでは画面を詳しく説明しています。

Telegramで新しいボットのリンクを開き、個別チャットで/startを送ってからHelloを送ります。/startはウェルカムメッセージを送信し、通常のメッセージは以降の手順で必要なInboxの会話と送信者メタデータを作成します。個人データを扱うActionsは、設定中は無効のままにします。

Quickchat AIのInbox → Details → Visitorでこの会話を開きます。Telegram User IdとTelegram Chat Typeを探してください。メタデータのキーはtelegram_user_idとtelegram_chat_typeです。カーソルを合わせると表示される操作で数値のユーザーIDをコピーし、チャット種別がprivateであることを確認します。

このIDはTelegramの送信者メタデータに由来します。ユーザー名、メッセージに書き込んだ数字、ボット自身のIDとは別の値です。次の手順では送信者IDを使って両方のActionsを制限します。

ステップ2：Google Sheetsを準備するには？

Google Sheets連携はスプレッドシートと初期Actionを作成します。同じファイルを使い、ActionとGoogleの権限が同じ対象を指すようにします。

1. Actions & MCPs → Add Action → Google Sheetsを開き、Googleアカウントを認可します。Google Sheets接続ガイドに同意画面と初期設定の説明があります。
2. 初期Actionは直ちにオフにします。 作成時は有効です。再接続時に名前で検索されるため、log_lead_to_google_sheetという名前は変えません。用途を支出保存に変更します。
3. 作成されたスプレッドシートを開き、Pocket Ledger demoという名前にします。この新しいデモ用ファイルでFile → Import → Uploadを選び、キット内のpocket-ledger-starter.xlsxを指定します。Replace spreadsheetを選んでImport dataをクリックしてください。Quickchat AIがアクセスできるファイル内にExpensesとSummaryが用意されます。このオプションは新しいデモ用スプレッドシートでのみ使ってください。
4. 以下の初期データ3行を確認します。Summaryの初期合計は7.70 EURと6.00 USDになるはずです。ステップ6で数式を説明し、読み取り用Actionを接続します。

まずGoogle Sheetsを接続します。その承認によって、両方のActionsが使うスプレッドシートが作成されます。

タブを自分で作りたい場合は、最初のタブをExpensesに変更します。英語の例に合わせて、File → Settings → Locale → United Statesを設定してください。A:DとF:HはPlain text、Eは小数点以下2桁のNumberに設定し、以下のブロックをA1に貼り付けます。見出し行を固定し、列幅を広げます。ステップ6に従ってSummaryを追加してください。GoogleにもExcelワークブックを既存のシートにインポートする手順があります。

date	month	item	category	amount	currency	note	conversation_url
2026-11-01	2026-11	coffee	food	4.50	EUR	synthetic example
2026-11-02	2026-11	bus ticket	transport	3.20	EUR	synthetic example
2026-11-03	2026-11	notebook	stationery	6.00	USD	synthetic example

conversation_url列は、新しい支出とその会話を結び付けます。手動入力した3つの例では空欄にしてください。Googleのdrive.file権限は、アプリが作成したファイルや明示的に許可されたファイルを対象にします。この手順では連携が作成したシートを使い、Drive全体へのアクセスは許可しません。

ステップ3：自分のチャットだけが支出にアクセスできるようにするには？

記録を読み書きするすべてのActionにRun only whenを設定します。2つの条件を両方満たす必要があるため、グループチャットでは本人のIDだけでは足りません。

1. 無効状態のlog_lead_to_google_sheet Actionを開き、Run only whenを探します。
2. 上記の条件を両方追加します。メタデータのキーとIDの数字を正確に使い、ユーザー名や@は付けません。
3. 無効のままActionを保存します。ステップ6で読み取りActionを作る際にも、同じ条件を設定します。

ローカルデモの保存Actionの条件です。架空のIDを実際の送信者IDに置き換え、読み取りActionにも両方の条件を設定します。

両方の条件を両方のActionsに設定します。別の送信者やグループチャットは、Google SheetsへHTTPリクエストが届く前に条件判定で拒否される必要があります。

これはサーバー側で適用されるAction条件です。プロンプトに「私だけに答えて」と書いてもアクセス制御にはなりません。シートの共有設定とQuickchat AIアカウントへのアクセスも制限してください。

ステップ4：確認済みの支出をボットに保存させるには？

初期Actionを変更し、シートの列順に1行を追加するようにします。確認を待てるよう、When to run → AI decidesを設定します。その後、有効にする前にAgentへ確認のルールを与えます。

支出の入力項目を設定する

What to ask the user firstで、リード用の項目を次のパラメータに置き換えます。パラメータ名は表のとおりにしてください。

既存のAPI Endpointにある実際のスプレッドシートIDを保持します。範囲をExpenses!A:Hに変更し、メソッドはPOSTのままにします。Query ParamsにvalueInputOption=RAWとinsertDataOption=INSERT_ROWSを設定します。URLに同じ設定がある場合は重複を除きます。

POST https://sheets.googleapis.com/v4/spreadsheets/YOUR_CREATED_SHEET_ID/values/Expenses!A:H:append
Query Params:
valueInputOption = RAW
insertDataOption = INSERT_ROWS
Headers:
Authorization = Bearer {{google_sheets_access_token}}
Content-Type = application/json

YOUR_CREATED_SHEET_IDは説明用の仮表記です。初期URLに入っている実際のIDを残し、この文字列で上書きしないでください。Authorizationの値には既存のGoogle Sheets System Tokenを選び、本文には組み込みの会話URL変数を使います。

Bodyタブに次を入力します。

{"values":[["{{date}}","{{month}}","{{item}}","{{category}}","{{amount}}","{{currency}}","{{note}}","{{conversation_url}}"]]}

ローカルの支出Action設定です。本文がセルの順番を定め、金額パラメータの形式が数値型を定めます。

エディターでは{{amount}}を囲む引用符を残します。 この完全一致のプレースホルダーはDecimal Numberパラメータを参照するため、置換後は4.5のようなJSON数値になります。引用符を除くと、エディターのJSONが不正になります。実際のシートでE列が数値であり、数式の計算対象になることを確認してください。

Googleのappend APIが行を追加します。RAWは、=で始まるメモなどを数式として評価せず、そのまま文字列として保持します。金額の型は数値パラメータによって指定されます。

Save one personal expense to the configured Google Sheet. Call only after the owner explicitly confirms the proposed date, item, category, amount and currency. Ask for missing or ambiguous fields before saving. After confirmation, append one row once. Report success only after a successful API response. If the outcome is uncertain, tell the owner to inspect the Sheet before submitting again.

Pocket Ledgerに指示を与える

Identity → Main Promptを開き、以下を貼り付けます。両方のActionsを名前で指定しているので、集計の読み取りを追加すれば2つ目の目標にも対応できます。

Main PromptはIdentityにあります。このローカル画面で入力欄の場所を確認し、以下のコピー用ブロック全体を使ってください。

確認ルールがあると、一度立ち止まって見直せます。購入を承認する前に「4.50 EUR」を「5.00 EUR」に修正できます。その場合、Agentは提案を更新し、もう一度確認を求める必要があります。

You are Pocket Ledger, a personal expense notebook.

For an expense, collect its date, item, positive amount and ISO currency code. Suggest a simple category and include an optional note only when supplied. Ask for an explicit YYYY-MM-DD date if it is missing or relative; do not guess today's date or the owner's timezone. Clarify ambiguous currency symbols. Derive month as YYYY-MM from the confirmed date.

Show the proposed date, item, category, amount and currency. Wait for explicit confirmation. Apply corrections and ask for confirmation again. Only then call log_lead_to_google_sheet once for that expense. Do not claim it was saved unless the Action succeeds. If a request fails or its outcome is uncertain, explain that and ask the owner to inspect the Sheet before retrying.

For monthly totals, ask for an explicit month and currency when unclear, then call read_expense_summary. Quote the matching month, currency and total returned from the Sheet. Keep currencies separate. A missing summary row is unavailable, not zero. Never calculate totals from remembered conversation messages.

Personal-data Actions are restricted to the owner's private Telegram chat. If a condition blocks an Action, do not claim success or suggest changing identity values in chat. This notebook handles typed expenses, not bank accounts, voice transcription or PDF receipts.

プロンプトを保存し、両方の実行条件を再確認してから、支出Actionを有効にします。名前はlog_lead_to_google_sheetのままですが、新しいパラメータ、説明、本文が支出記録の動作を定めます。

ステップ5：最初の支出を保存するには？

ここでノートに最初の新しい記録を追加しましょう。Telegram、Inbox、シートを開いたままにします。同じコーヒーが3か所を通っていく様子を確認します。

1. 個別のTelegramチャットでCoffee, 4.50 euros on 2026-11-04を送ります。
2. 提案を確認します。日付は2026-11-04、品目はCoffee、カテゴリはFood、金額は4.50、通貨はEURです。行を保存するときに、Actionがmonthを2026-11として求めます。
3. 確認を返す前にExpensesを調べます。最初の3行だけが存在するはずです。

Save itを1回送信し、Quickchat AIのInboxで会話を開きます。保存を知らせる返答には、展開できる1 action calledの表示があります。開くと、短いTelegramの返答の裏で何が起きたかを確認できます。

Result → Show fullを展開します。日付、日付から求めた月、数値の金額、通貨、HTTPステータスを確認してください。この実環境での実行では、GoogleがHTTP 200、updatedRows: 1、updatedRange: Expenses!A5:H5を返しました。

最後にExpensesを開きます。5行目には同じコーヒーが入り、月の列は2026-11、金額は4.50、通貨はEURになるはずです。最後の列にはInboxの会話へのリンクが入るので、その記録を作ったメッセージまでたどれます。

ここまでで「送る、確認する、確かめる」という日常で使える習慣ができました。次は、月のお金の行き先を尋ねたときに、ボットが信頼できる情報源を読めるようにします。

ステップ6：月別合計を質問するには？

Google Sheetsに合計を計算させ、読み取りActionで取得します。計算をシートに置くことで、会話終了後でも回答を検証できます。

Summaryタブを追加する

スターターワークブックをインポートした場合、Summaryと数式はすでに用意されています。初期値は7.70 EURと6.00 USDで、コーヒーを保存するとEURの行だけが変わります。シートを手作業で作成する場合は、以下の手順を進めてください。

1. Summaryというタブを作ります。A:B列をPlain textにして、A1:C1にmonth、currency、totalを入力します。
2. A2:B2に2026-11とEUR、A3:B3に2026-11とUSDを入力します。
3. C2に次の数式を入力し、C3まで下にコピーします。C列は小数点以下2桁の数値に設定します。

=SUMIFS(Expenses!$E$2:$E$501,Expenses!$B$2:$B$501,A2,Expenses!$F$2:$F$501,B2)

SUMIFS関数は、月と通貨が集計行に一致する金額を足します。シートの地域設定で引数の区切りにセミコロンが必要なら、数式のカンマをセミコロンへ変更してください。JSONリクエストの数値は引き続き小数点にピリオドを使います。

最初の7.70 EURに新しいコーヒー4.50 EURを足すと12.20 EURです。6.00 USDのノートは別の合計に入ります。

初期の数式は2行目から501行目を対象にしています。今回の記録では、新しい行の挿入後、3つの範囲の終端が502になっています。Sheetsは行の挿入時に参照を調整することがあります。Expensesの3つの範囲が同じ行を対象にしているか確認し、記録が対象範囲から外れる前にまとめて拡張してください。質問したい月と通貨の組み合わせごとに集計行を追加します。

読み取りActionを追加する

Actions & MCPs → Add Action → API Actionを開きます。以下の依頼をGenerateで使います。生成されたActionsは無効状態で作られます。名前をread_expense_summaryにし、結果を回答に利用できるようWhen to runはAI decidesにします。同じ実際のスプレッドシートIDとGoogle Sheets System Tokenを使います。利用者から受け取るパラメータは不要です。

Create a read-only Google Sheets Action named read_expense_summary. Use GET for the Summary!A1:C25 range of the spreadsheet already created by this Agent's Google Sheets integration. Reuse its actual spreadsheet ID and google_sheets_access_token System Token. Set valueRenderOption=UNFORMATTED_VALUE, no body, and no visitor parameters. Preserve the response headers and values. Leave it inactive so I can review the configuration and add my owner-ID and private-chat Run only when conditions before enabling it.

生成された設定を次の例と照合します。Create manuallyを選ぶ場合は、Actionが有効になる可能性があるため、最初の有効な保存の前に両方の条件を追加します。確認に使うフィールドを残すため、両方のActionsでResponse filterを空欄にします。

GET https://sheets.googleapis.com/v4/spreadsheets/YOUR_CREATED_SHEET_ID/values/Summary!A1:C25
Query Params:
valueRenderOption = UNFORMATTED_VALUE
Headers:
Authorization = Bearer {{google_sheets_access_token}}
Body: none

values.getエンドポイントは、見出しと計算済み金額を含む範囲のvaluesを返します。UNFORMATTED_VALUEは通貨表示の文字列ではなく数値を返します。Agentが値を読めるよう、レスポンスを利用可能な状態にしてください。

Read monthly expense totals from the configured Summary range. Use this when the owner asks for a total. Quote only the returned row matching the requested YYYY-MM and currency. If either is unclear, ask. If the row is absent or the request fails, say the total is unavailable. Never infer a total from conversation history, combine currencies, or accept a different spreadsheet ID or range from the visitor.

ステップ3と同じ2つのRun only when条件を適用し、保存してActionを有効にします。読み取り範囲には集計24行が含まれています。行を増やすときは、この範囲も意識して広げてください。

2つ目のActionにも個別の条件設定が必要です。これはローカル設定の画像であり、実際の送信者を使った認可テストではありません。

What is my November 2026 total in EUR?と質問し、続いてUSDの合計を質問します。今回のTelegram会話では、Pocket Ledgerが12.2 EURと6 USDを返し、シートに書式付きで表示された12.20と6.00に一致しました。回答するたびに保存済みの集計を読み取っています。

Inboxで月別合計の返答を開き、そのActionを展開します。返された行をSummary!C2と比較してください。以下の実際の応答には、2026-11、EUR、12.2と、別の行のUSD、6が含まれ、HTTP 200が返っています。

実際の支出を使う前に誤りを確認するには？

不完全な依頼や拒否されるべき送信者も、コーヒーの保存成功と同じように確認します。以下の検証が通るまでデモデータを残してください。

言語的な振る舞いを繰り返しテストするには、Testing → Create Dataset → Paste messagesを開き、キットのメッセージと評価基準を使います。確認の流れは別途、会話全体を通して実行してください。PreviewやSimulationのメタデータはテスト用データであり、実際の別のTelegram送信者を拒否できる証拠にはなりません。

ローカルデータセットはテスト用に準備済みです。存在しているだけでは、Simulation実行の完了やGoogle Sheetsへの書き込みを証明しません。

動作に問題があれば、関連する指示を1つ変更し、同じ入力を繰り返して呼び出しとシートを再確認します。例えば確認前に追加されたなら、保存Actionの確認に関する説明を見直します。確認は指示であり、データベースの一意性保証ではありません。 タイムアウト後は再送より先にシートを確かめることが大切です。

一連の動作を確認できたら、架空の支出行を削除し、見出しと数式を残して、実際に使う月と通貨の集計行を追加します。最初の本当の買い物も、コーヒーと同じ小さな手順で記録できます。

AIアシスタントにPocket Ledgerの設定を手伝ってもらえますか？

接続済みのアカウント管理アシスタントは、Agentの準備やAction設定の確認を支援できます。Quickchat AIのChatGPT掲載ページまたはClaude掲載ページを使い、Manage with AIに従ってください。設定キットと次の依頼を渡します。

Help me configure Pocket Ledger from this setup kit. Inspect the available Quickchat AI tools first. Prepare the Main Prompt and the two HTTP Actions using the exact field names, numeric amount type and fixed ranges. Keep log_lead_to_google_sheet as the starter name. Ask me to complete Google OAuth and Telegram Bot Token setup in the dashboard. Apply both owner/private run conditions before enabling either Action. Do not run credit-consuming tests or append expenses until I ask. Report any setting your tools cannot configure so I can complete it in the dashboard.

Googleへの同意とTelegram接続は所有者が完了します。誰が設定を入力した場合でも、内容を確認し、上記と同じ検証を行ってください。

よくある質問

TelegramとGoogle Sheetsで支出を記録するには？

TelegramボットをQuickchat AI Agentに接続してGoogle Sheetsを認可します。確認後に支出を追加するActionと、数式による月別集計を読むActionを設定します。両方を本人のTelegramユーザーIDと個別チャットに制限してください。

ボットは今月いくら使ったか教えてくれますか？

指定した月と通貨の行が設定済みSummary範囲にあれば可能です。Google SheetsがSUMIFSで合計を計算し、読み取りActionが取得します。追加専用のActionでは合計を読めず、集計行がないことはゼロを意味しません。

他の人がTelegramボット経由で私の支出を読めますか？

個人データを扱う両方のActionsに、確認済みのtelegram_user_idと、telegram_chat_typeがprivateであることを要求します。この条件が他の送信者やグループからの呼び出しを拒否します。個人データを入れる前に両方のケースをテストし、シートとQuickchat AIアカウントへのアクセスも制限してください。

このTelegram支出管理ボットは無料ですか？

Telegramボットの作成は無料です。Quickchat AIのFreeプランは、上限のあるAIクレジット枠で個人の非商用学習に利用できます。AIの回答とSimulation Testingはクレジットを消費し、継続利用は利用可能な枠とプランに依存します。

Apps Script、Python、自動化サーバーは必要ですか？

この手順はQuickchat AI ActionsとGoogle Sheetsの数式を使います。提供されたリクエスト設定、JSON本文、プロンプトをダッシュボードに貼り付けるため、Apps Script、Pythonボット、自動化サーバーをデプロイする必要はありません。

既存の家計簿スプレッドシートを使えますか？

この手順はQuickchat AIのGoogle Sheets連携が作成するスプレッドシートを使います。drive.file認可ではDriveへの無制限なアクセスは得られません。任意の既存ファイルのIDに置き換えて、アクセスできると決めつけないでください。

ボットはレシート写真や音声メモを読めますか？

このチュートリアルは文字入力の支出を扱います。レシートの読み取りを使う前には、Telegramでの画像配信と確認の流れを別途テストする必要があります。音声文字起こしとPDFレシートの解析はこの設定に含まれません。

複数の通貨や重複登録はどう扱いますか？

通貨ごとに別の月別合計を作り、この手順では為替換算をしません。確認は誤登録を減らしますが、原子的な重複防止は提供しません。保存がタイムアウトしたら、再送前にシートを調べてください。