Como enviar alertas do Google Sheets para o Telegram com Google Apps Script

Sim. Você pode usar o Google Apps Script para observar uma planilha e enviar um alerta para o Telegram sempre que uma linha mudar de status. O script funciona como uma ponte: lê os dados do Google Sheets, faz uma requisição HTTPS para a API do Telegram e entrega a mensagem no chat escolhido.

O exemplo abaixo serve para pedidos, chamados, leads ou tarefas. Quando a coluna “Status” receber o valor Urgente, a pessoa responsável recebe uma mensagem no Telegram sem precisar ficar atualizando a planilha. O método usa recursos oficiais do Apps Script e da Bot API, mas exige cuidado com o token do bot.

O que você precisa antes de começar

• Uma conta Google com acesso ao Google Sheets e ao Apps Script;
• uma planilha com uma coluna de status;
• um bot criado no Telegram;
• o token do bot e o chat_id do destinatário.

O Apps Script não é um servidor que fica rodando em um computador. Ele executa uma função quando um gatilho acontece, como uma edição na planilha. Para chamar um serviço externo, usamos UrlFetchApp, classe oficial que faz requisições HTTP e HTTPS e retorna um HTTPResponse.

1. Crie o bot e descubra o chat que receberá o alerta

No Telegram, abra o BotFather, envie /newbot e siga as instruções. Ao final, ele fornecerá um token parecido com 123456789:AA.... Esse valor funciona como uma senha: não coloque o token em artigo, print, repositório público ou planilha compartilhada.

Depois, abra a conversa com o bot e envie /start. Em seguida, abra no navegador o endereço abaixo, trocando SEU_TOKEN pelo token real:

https://api.telegram.org/botSEU_TOKEN/getUpdates

Procure no retorno JSON o trecho message.chat.id. Esse número é o chat_id da conversa. A documentação da Telegram Bot API informa que as chamadas devem ser feitas por HTTPS no formato https://api.telegram.org/bot<token>/<método>. O método sendMessage precisa, entre outros campos, de chat_id e text.

Se o alerta for para um grupo, adicione o bot ao grupo e obtenha o identificador daquela conversa. Em grupos, o ID pode ser negativo; não transforme o número nem retire o sinal.

2. Organize a planilha

Crie uma aba chamada Pedidos com estas colunas na primeira linha:

A	B	C	D
Pedido	Cliente	Valor	Status
1042	Marina	R$ 280	Em análise

Neste tutorial, o gatilho será acionado quando alguém editar a coluna D e digitar exatamente Urgente. Se sua coluna de status estiver em outra posição, altere o número indicado no código.

3. Guarde token e chat_id nas propriedades do script

No editor do Apps Script, abra Configurações do projeto e adicione duas propriedades do script:

• TELEGRAM_TOKEN: o token fornecido pelo BotFather;
• TELEGRAM_CHAT_ID: o identificador encontrado no retorno de getUpdates.

O PropertiesService armazena valores simples em pares chave-valor vinculados ao script. Assim, o segredo não fica repetido em cada função. Isso não transforma o projeto em um cofre: quem tiver acesso de edição ao Apps Script ainda poderá ler as propriedades, então compartilhe o projeto com cuidado.

4. Cole o código no Apps Script

Na planilha, acesse Extensões > Apps Script, apague o conteúdo inicial e cole:

function enviarMensagemTelegram(texto) {
  const propriedades = PropertiesService.getScriptProperties();
  const token = propriedades.getProperty('TELEGRAM_TOKEN');
  const chatId = propriedades.getProperty('TELEGRAM_CHAT_ID');

  if (!token || !chatId) {
    throw new Error('Configure TELEGRAM_TOKEN e TELEGRAM_CHAT_ID nas propriedades do script.');
  }

  const resposta = UrlFetchApp.fetch(
    'https://api.telegram.org/bot' + token + '/sendMessage',
    {
      method: 'post',
      contentType: 'application/json',
      payload: JSON.stringify({
        chat_id: chatId,
        text: texto,
        disable_web_page_preview: true
      }),
      muteHttpExceptions: true
    }
  );

  const codigo = resposta.getResponseCode();
  const resultado = JSON.parse(resposta.getContentText());

  if (codigo !== 200 || !resultado.ok) {
    throw new Error('Telegram recusou a mensagem: ' + resposta.getContentText());
  }

  return resultado;
}

function avisarStatusUrgente(e) {
  if (!e || !e.range) {
    throw new Error('Esta função deve ser executada por um gatilho de edição.');
  }

  const intervalo = e.range;
  const planilha = intervalo.getSheet();

  if (planilha.getName() !== 'Pedidos') return;
  if (intervalo.getColumn() !== 4) return;
  if (intervalo.getRow() === 1) return;

  const status = intervalo.getDisplayValue().trim();
  if (status.toLowerCase() !== 'urgente') return;

  const linha = planilha
    .getRange(intervalo.getRow(), 1, 1, 4)
    .getDisplayValues()[0];

  const mensagem = [
    '🚨 Pedido marcado como URGENTE',
    'Pedido: ' + linha[0],
    'Cliente: ' + linha[1],
    'Valor: ' + linha[2],
    'Linha: ' + intervalo.getRow()
  ].join('\\n');

  enviarMensagemTelegram(mensagem);
}

O primeiro bloco monta uma requisição POST em JSON para sendMessage. O segundo recebe o objeto de evento da edição, confere aba, coluna e valor e só então monta o alerta. O teste resultado.ok é importante: uma resposta HTTP não deve ser tratada como sucesso sem conferir o JSON devolvido pela API.

5. Crie o gatilho correto

No editor do Apps Script, clique no ícone de Gatilhos, escolha Adicionar gatilho e configure:

1. função: avisarStatusUrgente;
2. origem do evento: Da planilha;
3. tipo de evento: Ao editar.

Salve e autorize o projeto quando o Google solicitar acesso à planilha e a conexão externa. Os gatilhos instaláveis oferecem mais possibilidades que os gatilhos simples e podem chamar serviços que exigem autorização. A própria documentação do Google explica que eles podem responder a eventos como edição, abertura ou envio de formulário.

Não clique no botão Executar para testar avisarStatusUrgente: fora de uma edição, o objeto e não existe. Para testar, edite uma célula da coluna D em uma linha de dados e escreva Urgente. A mensagem deve chegar ao chat configurado.

Como testar sem esperar uma edição real

Você pode criar uma função de teste separada:

function testarTelegram() {
  enviarMensagemTelegram('Teste enviado pelo Google Apps Script.');
}

Execute testarTelegram uma vez pelo editor e confira o Telegram. Se nada chegar, abra Execuções no Apps Script e leia o erro registrado. Não copie o token para o relatório de erro nem para um print.

Erros comuns e como corrigir

O bot não responde

Confira se você enviou /start na conversa correta e se o chat_id pertence a ela. Para grupos, verifique se o bot está presente e se o identificador foi copiado completo.

A API retorna erro 401

Normalmente o token está errado, incompleto ou foi revogado no BotFather. Gere outro token se ele vazou e atualize a propriedade TELEGRAM_TOKEN.

A mensagem chega duplicada

Veja se existem dois gatilhos instalados para a mesma função. Também evite editar várias vezes a célula de status: cada mudança para Urgente é um novo evento.

O script acusa limite ou falha intermitente

Uma planilha muito movimentada pode produzir muitas chamadas. Use uma condição mais específica, reduza alertas repetidos e considere registrar o último envio em uma propriedade ou coluna auxiliar. O Apps Script e o Telegram têm limites próprios; este exemplo não foi desenhado para disparar centenas de mensagens por minuto.

Vale a pena usar esse fluxo?

Para uma pequena operação, sim. Ele elimina a conferência manual e usa serviços que muitas equipes já têm. É adequado para avisos de pedido, lead novo, tarefa vencida ou mudança de prioridade.

Mas há limites. O código depende de um gatilho, de autorização do Google, de uma conexão externa e do funcionamento da API do Telegram. Ele também não substitui um sistema de atendimento: não há fila, histórico estruturado, reprocessamento automático ou controle avançado de permissões. Para um fluxo maior, use uma ferramenta de automação com logs e retentativas ou um backend próprio.

Se você ainda precisa criar o bot, veja o guia do JSMS sobre como criar um bot no Telegram com BotFather e Python. A lógica de criação é complementar; neste tutorial, a parte importante é ligar a planilha a um evento útil.

Perguntas frequentes

Posso enviar alertas para mais de uma pessoa?

Sim. Faça uma chamada para cada chat_id autorizado ou envie a mensagem para um grupo. Mantenha esses identificadores em uma lista e controle quem pode receber dados da operação.

Preciso deixar o computador ligado?

Não. O Apps Script executa na infraestrutura do Google quando o gatilho é acionado. Ainda assim, a execução está sujeita às autorizações e aos limites do serviço.

Posso usar o mesmo código com um formulário?

Sim, mas o gatilho e o objeto de evento mudam. Em respostas de Google Forms, prefira um gatilho instalável “Ao enviar formulário” e adapte a leitura dos valores recebidos.

É seguro deixar o token no Apps Script?

É mais seguro guardá-lo nas propriedades do script do que publicá-lo no código, mas não é seguro compartilhar o projeto sem critério. Se o token for exposto, revogue-o e crie outro no BotFather.