Atende Direito · Docs

Tema

Google Sheets · google_sheets ​

Para que serve

Pensa numa planilha de controle que a equipe já usa no dia a dia — leads, atendimentos, agendamentos — e que o fluxo precisa alimentar ou consultar automaticamente. O nó Google Sheets é um único bloco que faz isso: dentro dele, você escolhe a Ação (adicionar linha, atualizar, ler, limpar, excluir ou criar aba) e o fluxo executa a operação direto na planilha conectada, sem interpretação de IA — determinístico, como um script.

Quando usar
  • Registrar leads, atendimentos ou eventos numa planilha de controle
  • Manter um cadastro atualizado (upsert por uma coluna-chave, como CPF ou telefone)
  • Consultar dados de uma planilha para decidir o próximo passo do fluxo
  • Limpar ou reorganizar uma planilha entre execuções (ex.: relatório periódico)
  • Criar uma aba nova por período (ex.: uma aba por mês, duplicando o modelo)
Dica

Se você precisa que a IA decida quando e o que fazer na planilha (em vez de um ponto fixo do fluxo), use a integração Google Sheets como ferramenta de um Agente de IA em vez deste nó dedicado.

Pré-requisitos ​

O workspace precisa ter uma conta do Google Workspace conectada (via OAuth), com a integração Google Sheets liberada. Veja como conectar em Conectar Google Workspace.

Passo a passo
  1. Na aba **Ferramentas** da paleta, arraste o item **Google Sheets** para o canvas e conecte-o ao bloco anterior. O nó já nasce configurado com a ação **Adicionar linha**.
    Paleta de nós aberta no canvas do Flow Builder, com as categorias disponíveis para localizar e arrastar o nó desejado

    Paleta de nós aberta no canvas do Flow Builder, com as categorias disponíveis para localizar e arrastar o nó desejado

  2. No painel, escolha a **Ação** desejada entre as 7 operações disponíveis. Trocar a ação atualiza os campos abaixo conforme a operação escolhida, preservando os valores em comum (Planilha, Aba, etc.).
  3. Escolha a **Planilha** na lista de planilhas acessíveis pela conta Google conectada.
  4. Escolha a **Aba** dentro da planilha selecionada. Trocar a Planilha recarrega automaticamente a lista de abas disponíveis.
  5. Preencha os demais campos, específicos de cada ação (veja a tabela abaixo).
  6. Salve e conecte a saída ao próximo nó.

As 7 ações ​

Todas as ações rodam sobre o mesmo servidor MCP google-sheets do workspace, resolvido automaticamente — você não escolhe servidor nem ferramenta manualmente, só a Ação.

Adicionar linha · google_sheets.append_row ​

Adiciona uma nova linha ao final da aba escolhida.

CampoO que faz
PlanilhaA planilha de destino
AbaA aba dentro da planilha onde a linha será adicionada
ColunasMapa coluna → valor: uma entrada por coluna do cabeçalho, cada uma recebendo uma variável do fluxo ou um texto fixo

Saídas: updated_range (intervalo A1 escrito), row_number (linha gravada), is_error.

Atualizar linha · google_sheets.update_row ​

Localiza a linha pela Coluna-chave + Valor da chave e atualiza os valores mapeados.

CampoO que faz
Planilha / AbaDestino da atualização
Coluna-chaveColuna usada para localizar a linha (ex.: CPF, Telefone)
Valor da chaveExpressão do fluxo comparada com a coluna-chave
ColunasMapa coluna → valor. Colunas não mapeadas preservam o valor atual da linha

Saídas: updated_range, row_number, found (booleano), is_error.

Adicionar ou atualizar linha · google_sheets.append_or_update ​

Upsert pela coluna-chave: atualiza a linha que casa com a chave, ou adiciona uma nova linha no final quando nenhuma casar.

CampoO que faz
Planilha / AbaDestino da operação
Coluna-chaveColuna usada para localizar a linha existente
Valor da chaveExpressão do fluxo comparada com a coluna-chave
ColunasMapa coluna → valor

Saídas: updated_range, row_number, appended (booleano — true quando a linha foi adicionada em vez de atualizada), is_error.

Ler linhas · google_sheets.get_rows ​

Lê linhas da aba como objetos coluna → valor, usando o cabeçalho como chave.

CampoO que faz
Planilha / AbaOrigem da leitura
Filtrar por coluna (opcional)Coluna usada para filtrar as linhas retornadas
Valor do filtro (opcional)Expressão do fluxo comparada com a coluna de filtro
Limite de linhasQuantidade máxima de linhas retornadas — padrão 100, máximo 1.000

Saídas: rows (lista de objetos coluna → valor, na ordem da planilha), row_count, is_error.

Limpar intervalo · google_sheets.clear ​

Limpa os valores de um intervalo (ou de toda a aba).

CampoO que faz
Planilha / AbaOnde limpar
Intervalo (A1) (opcional)Intervalo em notação A1 dentro da aba (ex.: A2:D10). Vazio limpa a aba inteira

Saídas: cleared_range (intervalo A1 efetivamente limpo), is_error.

Excluir linhas ou colunas · google_sheets.delete_rows_or_columns ​

Exclui linhas ou colunas da aba.

CampoO que faz
Planilha / AbaOnde excluir
Linhas (opcional)Lista de números de linha (base 1) a excluir, para linhas não contíguas
Intervalo de linhas (opcional)Intervalo contíguo início:fim (base 1), ex.: 5:10
Colunas (opcional)Letras das colunas a excluir, ex.: C, D

Saídas: is_error.

Criar aba · google_sheets.create_sheet ​

Cria uma nova aba na planilha, opcionalmente duplicando uma aba existente.

CampoO que faz
PlanilhaPlanilha onde a aba será criada
Nome da nova abaNome da aba a ser criada
Duplicar da aba (opcional)Nome de uma aba existente a duplicar. Vazio cria uma aba em branco
Posição (opcional)Posição (base 0) onde a nova aba será inserida

Saídas: sheet_title (nome efetivo da aba criada), is_error.

Comportamento comum a todas as ações
  • Os seletores de Planilha, Aba e Coluna são carregados dinamicamente a partir da conta Google conectada ao workspace.
  • Erros retornados pela planilha (ex.: intervalo inválido, aba inexistente) não derrubam a execução do fluxo — eles viram is_error=true na saída da ação, e a decisão de como reagir fica com você (ex.: um nó Se/Então logo depois).
  • Todas as ações aceitam configuração de retry (retry_config) para tentar novamente automaticamente em caso de falha transitória de rede ou da API do Google.

Erros comuns ​

Google não conectado (ou conexão expirada) O nó retorna erro indicando que não há uma conta Google conectada e válida para o workspace. Acesse Conexões → Integrações e conecte (ou reconecte) o Google Workspace — veja Conectar Google Workspace.

Seletor de Planilha vazio ou sem carregar Costuma indicar que a conexão do workspace ainda não tem o escopo do Google Drive. Reconecte o Google Workspace (veja o aviso em Pré-requisitos).

Planilha ou aba excluída Se a planilha ou a aba configurada no nó for excluída (ou o acesso a ela for removido) depois de o nó estar configurado, a execução falha ao tentar localizar o destino. Abra o nó, escolha novamente a Planilha e a Aba corretas e salve.

Exemplo

Cenário: ao final de um atendimento, registrar ou atualizar o lead numa planilha de controle, usando o telefone como chave.

Configuração:

  • Ação: Adicionar ou atualizar linha
  • Planilha: Controle de Leads
  • Aba: Leads 2026
  • Coluna-chave: Telefone
  • Valor da chave: {{contact.phone}}
  • Colunas:
    • Nome: {{contact.name}}
    • Interesse: {{extrair_parametros.interesse}}

Uso da saída: No nó seguinte, acesse {{google_sheets.appended}} para saber se o lead era novo (true) ou já existia (false) — por exemplo, para enviar uma mensagem de boas-vindas só na primeira vez.

Saiba mais ​