Crie um controle de gastos no Telegram com Google Sheets

Um café, uma passagem de ônibus, um caderno. É fácil esquecer pequenas compras antes de abrir uma planilha. E se bastasse uma mensagem no Telegram para registrar cada uma e outra para conferir o total do mês?

Neste tutorial, você cria o Pocket Ledger, um controle de gastos no Telegram com Google Sheets. Envie uma compra, confirme os dados propostos e pergunte pelo total mensal. A planilha guarda as linhas e faz as contas; o bot conduz a conversa. Este é o resultado final.

O primeiro marco é um café salvo. O segundo é um total que você pode conferir na planilha. Você também entenderá por que uma resposta dizendo “salvo” é apenas metade da evidência.

Baixe o kit de configuração do Pocket Ledger com a planilha inicial formatada, avatar, prompt, configurações de Actions e roteiro de testes. Importe a planilha para o arquivo criado pelo Quickchat AI e siga os passos abaixo. Os exemplos para copiar usam inglês e novembro de 2026 em todo o tutorial, permitindo comparar seus resultados com as capturas.

O que você precisa para criar um controle de gastos no Telegram?

Você precisa do Telegram, de uma conta Google e de uma conta Quickchat AI. A configuração usa ajustes do painel e uma fórmula de planilha; não há programa para hospedar.

1. Crie uma conta Quickchat AI, conclua a verificação e crie um Agent chamado Pocket Ledger.
2. Tenha uma conta Google pronta para a nova planilha. Comece com os registros fictícios abaixo.
3. Use um bot novo do Telegram neste exercício. Tenha uma segunda conta confiável do Telegram disponível para o teste final de acesso.

O plano Free do Quickchat AI é voltado ao aprendizado pessoal, não comercial, e inclui uma franquia limitada. Conversas de AI e Simulation Testing consomem créditos. Confira os planos e limites atuais antes de escolher um plano para uso contínuo.

Duas direções, duas Actions. Salvar uma linha não permite ao Agent consultar totais anteriores.

Passo 1: Como conectar seu bot privado do Telegram?

O BotFather cria a identidade do bot. O Quickchat AI fornece o Agent que responde às mensagens.

Abra o @BotFather oficial, envie /newbot, dê ao bot o nome Pocket Ledger e escolha um nome de usuário disponível terminado em bot. Use /setuserpic para enviar o avatar do kit. Mantenha o token em segredo; você vai colá-lo diretamente no Quickchat AI.

No Quickchat AI, abra External Apps → Telegram → Your own bot. Na janela Connect to Telegram, cole a credencial em Bot Token. Ative Enable your own bot e clique em Save. O guia do BotFather explica as telas em detalhes.

Abra o link do novo bot no Telegram, envie /start e depois Hello na conversa privada. /start envia a mensagem de boas-vindas; a mensagem comum cria a conversa no Inbox e os metadados do remetente necessários nas etapas seguintes. Mantenha inativas as Actions com dados pessoais enquanto as configura.

Abra essa conversa no Quickchat AI em Inbox → Details → Visitor. Localize Telegram User Id e Telegram Chat Type (as chaves de metadados são telegram_user_id e telegram_chat_type). Copie o ID numérico usando o controle que aparece ao passar o cursor e confirme que o tipo de conversa é private.

O ID vem dos metadados do remetente no Telegram. Seu nome de usuário, um número digitado em uma mensagem e o ID do próprio bot são valores distintos. Nos próximos passos, você usará o ID do remetente para restringir ambas as Actions.

Passo 2: Como preparar a planilha do Google Sheets?

A integração do Google Sheets cria uma planilha e uma Action inicial. Reutilize esse arquivo para que a Action e a permissão do Google se refiram ao mesmo recurso.

1. Abra Actions & MCPs → Add Action → Google Sheets e autorize sua conta Google. O guia de conexão com Google Sheets explica o consentimento e a configuração inicial.
2. Desative a Action inicial imediatamente. Ela é criada ativa. Mantenha o nome log_lead_to_google_sheet, pois a reconexão usa esse nome para encontrá-la. Vamos alterar sua finalidade para registrar gastos.
3. Abra a planilha criada e dê a ela o nome Pocket Ledger demo. Nesse novo arquivo de demonstração, escolha File → Import → Upload, selecione pocket-ledger-starter.xlsx do kit escolha Replace spreadsheet e clique em Import data. Isso prepara Expenses e Summary dentro do arquivo que o Quickchat AI pode acessar. Use essa opção apenas na nova planilha de demonstração.
4. Confira as três linhas iniciais abaixo. Em Summary, os totais iniciais devem ser EUR 7,70 e USD 6,00. O passo 6 explica a fórmula e conecta a Action de leitura.

Comece pela conexão do Google Sheets. A autorização cria a planilha usada pelas duas Actions.

Prefere criar as abas manualmente? Renomeie a aba inicial para Expenses. Para estes exemplos em inglês, selecione File → Settings → Locale → United States. Formate A:D e F:H como Plain text e E como Number com duas casas decimais; depois cole o bloco abaixo em A1. Congele o cabeçalho e aumente a largura das colunas. Adicione Summary conforme o passo 6. O Google também explica como importar uma pasta de trabalho do Excel para uma planilha existente.

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

A coluna conversation_url vinculará cada nova despesa à sua conversa. Deixe-a vazia nos três exemplos inseridos manualmente. A permissão drive.file do Google abrange arquivos criados pelo aplicativo ou explicitamente autorizados; esta receita usa a planilha criada pela integração e não concede acesso ao Drive inteiro.

Passo 3: Como restringir as despesas à sua própria conversa?

Configure Run only when em cada Action que leia ou escreva no registro. As duas condições precisam ser atendidas, portanto seu ID sozinho não basta em um grupo.

1. Abra a Action inativa log_lead_to_google_sheet e encontre Run only when.
2. Adicione as duas condições acima. Use as chaves exatas e os dígitos do seu ID, sem nome de usuário nem prefixo @.
3. Salve a Action, mantendo-a inativa. Aplique as mesmas condições à Action de leitura quando a criar no passo 6.

As condições da Action de gravação na demonstração local. Troque o ID fictício pelo seu ID real de remetente e repita ambas as condições na Action de leitura.

As duas condições devem estar nas duas Actions. Outro remetente ou uma conversa em grupo deve ser bloqueado antes de uma requisição HTTP chegar ao Google Sheets.

Essas são condições de Actions aplicadas pelo servidor. Escrever “responda somente a mim” no prompt não é controle de acesso. Restrinja também o compartilhamento da planilha e o acesso à sua conta Quickchat AI.

Passo 4: Como fazer o bot salvar uma despesa confirmada?

Adapte a Action inicial para acrescentar uma linha na ordem das colunas da planilha. Defina When to run → AI decides para que ela possa aguardar a confirmação. Depois, dê ao Agent uma regra de confirmação antes de ativá-la.

Configure os campos da despesa

Em What to ask the user first, substitua os campos de leads por estes parâmetros. Mantenha os nomes exatamente como aparecem.

Mantenha o ID real da planilha presente no API Endpoint. Altere o intervalo para Expenses!A:H, preserve o método POST e configure Query Params com valueInputOption=RAW e insertDataOption=INSERT_ROWS. Remova parâmetros duplicados se já estiverem na 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 é um marcador explicativo. Preserve o ID real já presente na URL inicial; não o substitua por esse marcador. Selecione o System Token existente do Google Sheets no valor Authorization e a variável integrada de URL da conversa no corpo.

Na aba Body, insira:

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

Configuração local da Action de despesas. O corpo define a ordem das células; o formato do parâmetro de valor define seu tipo numérico.

Mantenha as aspas ao redor de {{amount}} no editor. Como esse marcador exato se refere a um parâmetro Decimal Number, a substituição produz um número JSON, como 4.5. Remover as aspas deixa o JSON do editor inválido. Na planilha resultante, verifique se E é numérica e participa da fórmula.

A API append do Google adiciona a linha. RAW mantém textos como uma nota iniciada por = de forma literal, sem avaliá-los como fórmula. O parâmetro numérico fornece o tipo do valor.

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.

Dê instruções ao Pocket Ledger

Abra Identity → Main Prompt e cole o texto a seguir. Ele nomeia ambas as Actions para que o segundo marco funcione quando você adicionar a leitura do resumo.

O Main Prompt fica em Identity. Esta captura local mostra onde está o campo; use o bloco completo para copiar abaixo.

A regra de confirmação oferece uma pausa útil para revisar os dados. Você pode corrigir “EUR 4.50” para “EUR 5.00” antes de aprovar a compra; o Agent deve atualizar a proposta e pedir confirmação novamente.

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.

Salve o prompt, confira novamente as duas condições de execução e ative a Action de despesas. O nome continua log_lead_to_google_sheet; seus novos parâmetros, descrição e corpo agora definem o fluxo de gastos.

Passo 5: Como salvar sua primeira despesa?

Agora registre a primeira nova despesa. Mantenha Telegram, Inbox e a planilha abertos: você verá o mesmo café passar pelos três.

1. Na sua conversa privada no Telegram, envie Coffee, 4.50 euros on 2026-11-04.
2. Confira a proposta: data 2026-11-04, item Coffee, categoria Food, valor 4.50, moeda EUR. A Action deriva month como 2026-11 ao salvar a linha.
3. Antes de confirmar, confira Expenses: ainda deve haver somente as três linhas iniciais.

Envie Save it uma única vez e abra a conversa no Inbox do Quickchat AI. A resposta de confirmação do salvamento tem a opção expansível 1 action called. Abra-a para ver o que aconteceu por trás da resposta curta no Telegram.

Expanda Result → Show full. Confira a data, o mês derivado, o valor numérico, a moeda e o status HTTP. Nesta execução real, o Google retornou HTTP 200, updatedRows: 1 e updatedRange: Expenses!A5:H5.

Por fim, abra Expenses. A linha 5 deve conter o mesmo café, com 2026-11 na coluna de mês, 4.50 no valor e EUR na moeda. A última coluna leva à conversa no Inbox, permitindo rastrear uma entrada até a mensagem que a criou.

Agora você tem um hábito útil para o dia a dia: enviar, confirmar e conferir. Em seguida, dê ao bot uma fonte confiável para consultar quando perguntar para onde foi o dinheiro do mês.

Passo 6: Como consultar um total mensal?

Deixe o Google Sheets calcular o total e a Action de leitura buscá-lo. Manter as contas na planilha permite verificar a resposta mesmo depois que a conversa acaba.

Adicione uma aba Summary

Se você importou a planilha inicial, Summary e suas fórmulas já estão prontas. Os valores iniciais são EUR 7,70 e USD 6,00; salvar o café altera apenas a linha em EUR. Se estiver montando a planilha manualmente, siga os passos abaixo.

1. Crie uma aba chamada Summary. Defina A:B como Plain text e insira month, currency, total em A1:C1.
2. Insira 2026-11 e EUR em A2:B2; depois, 2026-11 e USD em A3:B3.
3. Coloque esta fórmula em C2 e preencha até C3. Formate C como número com duas casas decimais.

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

A função SUMIFS soma valores cujo mês e moeda correspondem à linha do resumo. Se a localidade da planilha exigir ponto e vírgula entre argumentos, substitua as vírgulas da fórmula por ponto e vírgula. Números nas requisições JSON continuam usando ponto decimal.

Os EUR 7,70 iniciais mais o novo café de EUR 4,50 resultam em EUR 12,20. O caderno de USD 6,00 pertence a um total próprio.

A fórmula inicial cobre as linhas 2 a 501. Nesta execução capturada, os três intervalos terminam em 502 depois da inserção da nova linha. O Sheets pode ajustar referências durante a inserção; confira se os três intervalos de Expenses continuam alinhados e amplie-os juntos antes que novas entradas fiquem fora do intervalo. Adicione uma linha de resumo para cada combinação de mês e moeda que deseja consultar.

Adicione a Action de leitura

Abra Actions & MCPs → Add Action → API Action. Use Generate com o pedido abaixo; Actions geradas começam inativas. Dê o nome read_expense_summary e mantenha When to run em AI decides para que o resultado possa orientar a resposta. Reutilize o mesmo ID real da planilha e o System Token do Google Sheets. Nenhum parâmetro informado pelo usuário é necessário.

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.

Compare as configurações geradas com a referência a seguir. Se optar por Create manually, adicione ambas as condições antes do primeiro salvamento válido, que pode ativar uma Action. Deixe Response filter vazio nas duas Actions para preservar os campos usados nas verificações.

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

O endpoint values.get retorna os values do intervalo, incluindo o cabeçalho e os valores calculados. UNFORMATTED_VALUE retorna resultados numéricos em vez de textos formatados como moeda. Deixe a resposta disponível ao Agent para que ele possa ler esses valores.

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.

Aplique as mesmas duas condições Run only when do passo 3, salve e ative a Action. O intervalo de leitura inclui 24 linhas de resumo; amplie-o de forma deliberada ao adicionar outras.

A segunda Action precisa de condições próprias. Esta é uma captura de configuração local, não um teste de autorização com um remetente real.

Pergunte What is my November 2026 total in EUR? e depois consulte USD. Na nossa conversa no Telegram, o Pocket Ledger retornou 12.2 EUR e 6 USD, correspondendo aos valores formatados 12.20 e 6.00 da planilha. Ele leu o resumo salvo para cada resposta.

Abra a resposta sobre o total mensal no Inbox e expanda sua Action. Compare a linha retornada com Summary!C2. A resposta real abaixo inclui 2026-11, EUR, 12.2 e uma linha separada com USD, 6, com HTTP 200.

Como verificar erros antes de usar gastos reais?

Teste pedidos incompletos e remetentes bloqueados com o mesmo cuidado dedicado ao café salvo corretamente. Mantenha os dados de demonstração até as verificações abaixo passarem.

Para testes de linguagem repetíveis, abra Testing → Create Dataset → Paste messages e use as mensagens e os critérios de avaliação do kit. Execute uma conversa completa separadamente para a sequência de confirmação. Metadados de Preview ou Simulation são dados de teste; não comprovam o bloqueio de um segundo remetente real do Telegram.

O dataset local está preparado para testes. Sua existência não representa uma execução concluída de Simulation nem comprova uma gravação no Google Sheets.

Se um comportamento falhar, altere uma instrução relevante, repita a mesma entrada e inspecione novamente a chamada e a planilha. Um append antecipado, por exemplo, exige revisar a redação da confirmação na Action de gravação. Confirmação é uma instrução, não uma garantia de unicidade no banco. Depois de um tempo limite, conferir a planilha importa mais que enviar de novo.

Quando o percurso funcionar, remova as despesas fictícias, mantenha cabeçalhos e fórmulas e acrescente resumos para os meses e moedas que realmente usa. Sua primeira compra real pode seguir a mesma pequena rotina do café.

Um assistente de AI pode ajudar a configurar o Pocket Ledger?

Um assistente conectado de gerenciamento de conta pode preparar o Agent e revisar as configurações das Actions. Siga Manage with AI usando a página do Quickchat AI no ChatGPT ou a página no Claude. Forneça o kit e este pedido:

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.

O proprietário conclui o consentimento do Google e a conexão do Telegram. Revise as configurações e execute as mesmas verificações acima, independentemente de quem as inseriu.

Perguntas frequentes

Como registrar gastos no Telegram com Google Sheets?

Conecte um bot do Telegram a um Quickchat AI Agent e autorize o Google Sheets. Configure uma Action para acrescentar uma despesa após confirmação e outra para ler um resumo mensal calculado por fórmulas. Restrinja ambas as Actions ao seu ID de usuário do Telegram e a uma conversa privada.

O bot pode dizer quanto gastei neste mês?

Sim, quando o mês e a moeda solicitados tiverem uma linha no intervalo Summary configurado. O Google Sheets calcula o total com SUMIFS e a Action de leitura o busca. Uma Action que apenas acrescenta linhas não consulta totais, e uma linha de resumo ausente não significa zero.

Outra pessoa pode ler meus gastos pelo bot do Telegram?

Ambas as Actions de dados pessoais devem exigir seu telegram_user_id verificado e telegram_chat_type igual a private. Essas condições bloqueiam chamadas de outros remetentes e de grupos. Teste ambos os casos antes de adicionar dados pessoais e restrinja também o acesso à planilha e à conta Quickchat AI.

Este controle de gastos no Telegram é gratuito?

Criar um bot do Telegram é gratuito. O plano Free do Quickchat AI permite aprendizado pessoal e não comercial com uma franquia limitada de créditos de AI. Respostas de AI e Simulation Testing usam créditos; o uso contínuo depende do limite disponível e do plano.

Preciso de Apps Script, Python ou um servidor de automação?

Esta receita usa Quickchat AI Actions e uma fórmula do Google Sheets. Você cola as configurações das requisições, o corpo JSON e o prompt fornecidos no painel; não precisa implantar Apps Script, um bot em Python ou um servidor de automação.

Posso usar minha planilha de gastos existente?

Esta receita usa a planilha criada pela integração do Google Sheets do Quickchat AI. A autorização drive.file não concede acesso irrestrito ao seu Drive. Não substitua o ID da planilha por um arquivo existente qualquer presumindo que esteja acessível.

O bot lê fotos de recibos ou mensagens de voz?

Este tutorial cobre despesas digitadas. A extração de recibos precisa de um teste próprio de entrega de imagem e confirmação no Telegram antes que você dependa dela. Transcrição de voz e leitura de recibos em PDF não fazem parte desta configuração.

Como ele lida com moedas diferentes e entradas duplicadas?

Cada moeda tem seu próprio total mensal; a receita não converte moedas. A confirmação reduz entradas acidentais, mas não oferece prevenção atômica de duplicatas. Se uma gravação exceder o tempo limite, inspecione a planilha antes de enviá-la novamente.