Base de conhecimento GetMyBot

Coleções e dados

Guarde solicitações, pedidos e inscrições no GetMyBot: crie uma tabela, acrescente registros e use os dados nas reações.

Nesta página

Uma coleção funciona como uma tabela: cada linha pode representar uma solicitação, um pedido ou uma inscrição em uma aula. O bot pode adicionar linhas a partir das respostas das pessoas. Você também pode consultar e editar os registros em Dados → Coleções.

Por exemplo, para agendar consultorias, crie a coleção leads com os campos name, phone e topic. Depois de fazer as perguntas, o bot salva nome, telefone e assunto na mesma linha. Mais tarde, uma reação pode encontrar e usar esses dados.

O que é uma coleção

Os campos são as colunas, como «Telefone» e «Assunto». Um registro guarda os valores de uma linha. A lista de campos e tipos forma a estrutura da coleção. Tecnicamente, cada registro é guardado como um documento JSON: você pode acrescentar novos campos sem recriar as linhas existentes.

O nome da coleção é exclusivo dentro do bot e identifica a tabela nas ações das reações, por exemplo, leads, orders ou scores.

Tipos de campo

Ao criar a coleção, escolha os campos e o tipo de cada um:

TipoO que guardaExemplo
textTextoNome, email ou comentário
numberNúmeroValor, quantidade ou pontos
boolSim ou não: true / falseSe o pedido foi pago
datetimeData e horaHorário de uma aula
jsonObjeto ou listaProdutos e características de um pedido

O tipo define como o campo é editado e como o valor é convertido ao salvar. A estrutura é flexível: se um registro tiver um campo que ainda não está na lista, o GetMyBot também o salvará e mostrará em uma coluna separada.

Criar uma coleção

  1. Abra Dados → Coleções e clique em Adicionar.
  2. Informe o nome com letras latinas e sem espaços, para facilitar o uso nas reações.
  3. Clique em Campo para adicionar as colunas e escolher seus tipos.
  4. Se necessário, configure o prazo de armazenamento descrito abaixo e salve.

Consultar e editar registros

No cartão da coleção, o botão com ícone de tabela abre a janela Dados:

  • Consultar: mostra as linhas, com um valor por célula, começando pelas mais recentes.
  • Adicionar registro: abre um formulário baseado nos tipos dos campos, como uma opção para bool e um campo JSON para json.
  • Editar, com o ícone de lápis: altera uma linha existente.
  • Excluir, com o ícone de lixeira: remove uma linha.

As ações do bot também podem acrescentar registros automaticamente. A edição manual e a automática trabalham com a mesma coleção.

Prazo de armazenamento (retention)

Para evitar crescimento sem limite, escolha regras de limpeza automática:

  • Número máximo de registros: ao ultrapassar o limite, as linhas mais antigas são removidas.
  • Guardar por no máximo (dias): as linhas mais antigas que o prazo são removidas.

Um prazo de 30 dias pode servir para um registro temporário. A limpeza é feita periodicamente, não no segundo exato em que o prazo termina. Você pode combinar as duas regras. Não defina um prazo curto para pedidos de que ainda precisa.

Usar os dados nas reações

O editor de reações oferece estas ações para coleções:

  • Criar registro: adiciona uma linha com valores de substituições, como {{user_id}} e {{text}}. Uma chave para evitar duplicatas faz com que uma nova execução com a mesma chave atualize a linha existente. Uma chave baseada no ID da pessoa, por exemplo, mantém uma solicitação atual por cliente.
  • Atualizar registros: altera as linhas que atendem a uma condição.
  • Buscar registros: carrega linhas em uma lista nos dados temporários (ctx) para uso nas próximas ações.
  • Ler página da coleção (record_page): carrega os registros em partes, por exemplo, dois cartões por vez com um botão para a próxima página.
  • Totais da coleção inteira (record_aggregate): calcula quantidade e soma de todos os registros correspondentes dentro das regras de armazenamento. Carregar apenas a primeira página não limita esse cálculo.
  • Transação atômica de coleções (collection_transaction): verifica condições e grava várias mudanças juntas, como ocupar uma vaga e criar uma inscrição. Se houver conflito, as mudanças anteriores da mesma transação também são desfeitas.
  • Excluir registros: remove as linhas que atendem à condição.
  • Loop por lista: percorre uma lista em ctx e executa ações para cada item, como atualizar linhas, calcular um total ou enviar cada registro a outro serviço.

Com isso, o bot pode organizar clientes, guardar solicitações, atribuir pontos e criar relatórios sem um banco de dados externo.

Os exercícios com coleções mostram como continuar um catálogo, calcular o total de todos os pedidos correspondentes e reservar a última vaga. Uma página de uma lista já carregada, uma página da coleção e o total da coleção são resultados diferentes; os exercícios explicam o que a próxima ação recebe.

Não use um loop para fazer envios em massa. Ele percorre até 500 itens por execução, mas um evento inteiro pode enviar no máximo 50 mensagens. Se cada item tentar enviar uma mensagem, as primeiras 50 poderão sair e as demais receberão erro. Para escrever às pessoas da coleção, crie um segmento e use um envio, que controla velocidade, pausas e resultados. Veja Ações → Limites de um evento.

Catálogo: buscar, escolher e mostrar detalhes

Comece pelo exercício de busca de aulas. Ele mostra quais coleções preparar, a ordem das ações e como testar uma busca vazia, vários resultados e o clique em um botão antigo.

Em um catálogo, guarde os dados separados das reações. Por exemplo, products tem name e aliases, enquanto variants tem product_id, name e card. No campo variants.product_id, ative Relação com outra coleção, escolha products, a chave _record_id e o campo name como título. A relação descreve o campo; ela não altera nem exclui registros relacionados automaticamente.

  1. Na reação a um texto recebido, adicione Buscar na coleção (record_search). Escolha products, use {{text}} como consulta, name como campo de busca, aliases como sinônimos e salve o resultado em search. Os sinônimos podem ser texto ou uma lista de textos JSON. A busca ignora maiúsculas, minúsculas e pontuação.
  2. Adicione Escolher a próxima etapa (branch_result) usando search. A primeira condição correspondente define a etapa seguinte. Trate primeiro o resultado incompleto, pedindo mais detalhes; depois Nada encontrado, Correspondência aproximada, Um registro e Vários registros. Quando a correspondência for aproximada, peça confirmação. Resultados vazios ou únicos exigem uma busca completa.
  3. Para vários resultados, use Botões dos registros encontrados na mensagem. Escolha search, o campo name como título e a próxima reação. O assistente configurará buttons_from.over = search.rows, o texto do botão e carry.selected_id = {{item._record_id}}. Confira se name faz parte dos campos retornados. Você ainda poderá editar o botão em detalhes.
  4. Na reação seguinte, adicione Encontrar registros relacionados (record_related): coleção variants, chave product_id, valor {{ctx.selected_id}} e resultado variants. Para ler o produto escolhido, use products e a chave _record_id. Se suas relações usam outra chave do negócio, selecione a mesma chave no assistente de botões e na leitura.
  5. Separe os caminhos pelo resultado. Mostre um único item como cartão com {{ctx.variants.first.card}}; se houver vários, mostre botões. Cada botão passa o ID e os dados atuais são consultados depois do clique. Não guarde em Carry o cartão ou outros campos que podem mudar.

Resultado da leitura

search.rows é a lista simples de registros; search.count informa quantas linhas foram carregadas; search.first é a primeira; search.first.name é um campo dela. Cada linha inclui _record_id, _score e _match_type, nomes reservados. Se não houver resultados, os dados da primeira linha de uma busca anterior são limpos.

search.total conta as correspondências entre os registros examinados. total_exact = false significa que nem toda a coleção foi examinada; truncated = true avisa que houve um limite na resposta. Não trate uma busca incompleta como definitiva. Cada busca examina até 10.000 registros e 16 MiB de dados, e a resposta informa os limites atingidos. Por padrão, retorna até 100 linhas, com máximo de 10.000.

Testar e entender a busca

No editor, abra Testar busca e informe um texto ou ID de exemplo. Esse teste apenas lê dados: não executa reações, mensagens nem outras ações seguintes. Substitua manualmente os valores dos filtros adicionais antes de testar. Você verá as linhas encontradas, o tipo de correspondência, quantos registros foram examinados e os limites. Resultados antigos são ocultados quando você muda de projeto, coleção, configuração ou permissões.

O histórico da execução mostra os campos consultados, o tipo de correspondência, a quantidade de registros examinados e retornados, o limite da resposta e o caminho escolhido. No diagrama da reação, aparecem todas as condições que levam à mesma reação. Ao rever uma execução, a explicação da busca aparece depois que você abre o evento correspondente, se tiver permissão para ver seu conteúdo.

O assistente de botões cria até 20 por padrão. Você pode configurar Máximo de botões entre 1 e 100; isso é um limite, não uma paginação. Uma lista vazia não cria botões. Para muitos resultados, acrescente uma etapa que peça à pessoa para refinar a busca.

Em Cálculo, o assistente Operação sobre a lista carregada cria fórmulas para contar registros, obter o primeiro, somar um campo e listar títulos. O cálculo usa apenas as linhas carregadas; se a busca for incompleta, ele não representa o total da coleção.

API e MCP

As mesmas operações estão disponíveis em POST /api/bots/{botID}/collections/{name}/search e /related, e nas ferramentas MCP search_records e related_records, com a permissão collections:read. As chamadas ficam limitadas ao projeto e à região atuais. Na API REST, o teste usa valores concretos; as substituições de modelo são processadas dentro das ações da reação.

Tratar resultados e alterar sob condição

Você pode passar o resultado de uma coleção para list_transform e filtrar, ordenar, remover duplicatas ou escolher uma página. list_aggregate calcula totais com nome a partir das linhas carregadas, com agrupamento opcional. Essas ações também funcionam com uma lista vinda de uma resposta HTTP, sem coleção.

Para que duas execuções simultâneas não apliquem a mesma mudança duas vezes, use record_update_if: informe o ID, os valores esperados e os novos valores. A conferência e a alteração de uma linha acontecem juntas. Depois, trate o status updated, conflict ou not_found com branch_value. Isso é diferente de alterar sem condição todas as linhas que passam por um filtro.

Veja configuração, limites e exemplos.

O exercício de confirmação sem duplicatas mostra como conferir o estado e o responsável antes de gravar, e como responder a updated, conflict e not_found.

Acesso pela Mini App

Uma Mini App do Telegram pode ler os registros da coleção. O aplicativo pede os dados pelo nome da coleção, com filtros e limite, para mostrar pedidos, histórico ou uma classificação dentro do Telegram.

Dicas

  • Use nomes curtos com letras latinas nos campos, como email, total e paid, para facilitar as substituições nas reações.
  • Se repetir uma ação não pode criar outra linha, configure uma chave para evitar duplicatas. Isso se chama idempotência.
  • Defina um prazo de armazenamento (retention) para registros temporários que não serão mais necessários.
  • Use json quando a estrutura do dado ainda não estiver definida.