Planilha

A caixa Planilha (Google Sheets) integra a conversa a uma planilha do Google Sheets. Ela executa uma de duas operações:

1. Ler dados da planilha — consulta o conteúdo de um intervalo de células e devolve o resultado para um script da própria caixa;
2. Adicionar/atualizar planilha — escreve linhas no intervalo indicado, adicionando ao final do conteúdo existente ou sobrescrevendo o intervalo.

Casos de uso típicos:

• consultar uma tabela de preços, prazos ou status cadastrados em planilha;
• registrar cada atendimento (protocolo, nome, solicitação) em uma nova linha;
• atualizar um painel de acompanhamento mantido em planilha;
• ler listas mantidas pelo cliente (feriados, unidades, planos) sem precisar de outra integração.

A planilha é acessada com credenciais do Google informadas por arquivo JSON (conta de serviço). As credenciais ficam guardadas pela plataforma, vinculadas à caixa, e o acesso à planilha acontece na execução do atendimento.

Onde encontrar

1. Abra Configuração → Fluxos.
2. Crie ou abra uma versão do fluxo no editor.
3. Na lista de caixas (nova caixa), localize Planilha (Google Sheets) — ela aparece diretamente na lista, sem submenu, com o ícone de planilha.
4. Selecione a caixa para abrir o painel de configuração.
5. Preencha as opções e clique em Aplicar. Depois, salve a versão do fluxo.

Como funciona

O comportamento geral é:

Caixa Planilha
      │
      ├── onEnter: dispara a operação na planilha
      │       ├── Ler dados       → aguarda a resposta da planilha
      │       └── Adicionar/atualizar → grava e segue
      │
      └── após a operação, vai para a caixa seguinte

Na leitura, a operação é assíncrona: a caixa dispara a consulta e, quando a planilha responde, o script a executar após a requisição roda com o resultado disponível em input.response. Só depois disso a conversa segue para a caixa seguinte.

Na escrita, a caixa envia os dados e já encaminha a conversa para a caixa seguinte configurada em Após a operação, vai para.

Importante: a caixa acessa a planilha com a conta de serviço das credenciais. Para funcionar, a planilha precisa estar compartilhada com o e-mail dessa conta de serviço (a planilha não precisa ser pública).

Pré-requisito: credenciais de acesso

Antes de salvar a caixa, é obrigatório enviar o arquivo de credenciais:

1. No Google Cloud, crie (ou reutilize) uma conta de serviço e baixe a chave no formato JSON.
2. Compartilhe a planilha desejada com o e-mail da conta de serviço, com permissão de leitura (operações de leitura) ou de edição (operações de escrita).
3. No painel da caixa, envie o arquivo em Credenciais de acesso (arquivo) — clique no link ou arraste o arquivo para a área de upload.
4. Ao remover as credenciais (opção Remover credenciais), a remoção tem efeito imediato.

As credenciais são vinculadas à caixa pelo nome do elemento. Por isso:

• informe o Nome da caixa antes de enviar o arquivo;
• se o nome da caixa mudar depois do upload, é preciso atualizar o arquivo de credenciais — o salvamento bloqueia a alteração sem essa atualização.

Campos da caixa

¹ É obrigatório informar pelo menos um entre aba e intervalo; na prática, informe o intervalo e, havendo mais de uma aba, o nome da aba também.

² O campo aceita o default {"values": [[]]}, mas gravar um valor vazio raramente é a intenção — preencha as linhas desejadas.

Variáveis nos campos

Os campos Identificador, Nome da aba, Intervalo e Dados aceitam a sintaxe {{variavel}}, que é resolvida com o valor da variável de sessão no momento da execução. Isso permite, por exemplo, consultar um intervalo diferente por cliente ou gravar dados coletados antes na conversa.

Também é possível usar {{!expressão}} para interpolar código JavaScript diretamente, no mesmo padrão dos demais campos do sistema.

Operação “Ler dados da planilha”

1. A caixa consulta o intervalo informado na planilha.
2. Quando a resposta chega, o Script a executar após a requisição roda com o conteúdo em input.response.
3. No script, trate os dados, guarde o que for necessário em variáveis com dialog.set(...) e, quando quiser, use dialog.go(...) para direcionar a conversa.
4. Se nada for feito no script, a conversa segue para a caixa configurada em Após a operação, vai para: (o script gerado já inclui esse desvio).

O conteúdo lido corresponde às linhas/células do intervalo consultado. Use o modo de teste/depuração do fluxo para inspecionar input.response e confirmar o formato recebido antes de escrever a lógica final.

Operação “Adicionar/atualizar planilha”

1. A caixa envia os dados JSON para a planilha.
2. O comportamento depende do checkbox Sobrescrever dados existentes:

3. A conversa segue para a caixa configurada em Após a operação, vai para:.

O JSON segue o formato do Google Sheets: values é uma lista de linhas, e cada linha é uma lista de células.

{
  "values": [
    ["valor A1", "valor B1", "valor C1"],
    ["valor A2", "valor B2", "valor C2"]
  ]
}

Exemplos

Exemplo 1 — Registrar cada atendimento em nova linha

Objetivo: ao final da coleta de dados, gravar protocolo, nome e solicitação como uma nova linha da planilha, preservando as linhas anteriores.

Configuração da caixa:

Dados a serem adicionados/atualizados (formato JSON):

{
  "values": [
    ["{{protocolo}}", "{{nomeCliente}}", "{{solicitacao}}"]
  ]
}

Após a operação, vai para: Confirmacao registro.

Como o checkbox fica desmarcado, cada execução acrescenta uma linha abaixo das existentes — a planilha vira um log de atendimentos.

Exemplo 2 — Sobrescrever um painel de status

Objetivo: manter em B1:B3 o status atual de três serviços, substituindo o conteúdo anterior a cada atualização.

Configuração da caixa:

Dados a serem adicionados/atualizados (formato JSON):

{
  "values": [
    ["{{statusPortais}}"],
    ["{{statusApp}}"],
    ["{{statusTelefone}}"]
  ]
}

Com o checkbox marcado, o intervalo B1:B3 passa a conter exatamente os três valores enviados.

Validações e mensagens comuns

O salvamento da caixa verifica as seguintes situações:

Boas práticas

• Compartilhe a planilha diretamente com o e-mail da conta de serviço e dê apenas a permissão necessária: leitura para consultas, edição para gravações.
• Dê nomes funcionais às caixas, como Consultar preco em vez de Planilha 1 — o nome também identifica as credenciais.
• Prefira intervalos delimitados (A1:B200) em vez de colunas inteiras, para reduzir leitura desnecessária.
• Ao escrever sem sobrescrever, use um intervalo de uma linha (A1:C1): as linhas novas são adicionadas abaixo.
• Em operações de leitura, teste o fluxo e inspecione input.response antes de codificar a lógica final.
• Considere o que acontece se a planilha estiver indisponível ou sem a linha esperada — trate o resultado vazio no script da leitura.
• Evite renomear a caixa depois de configurada; se renomear, atualize o arquivo de credenciais.