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:
| Tipo | O que guarda | Exemplo |
|---|---|---|
text | Texto | Nome, email ou comentário |
number | Número | Valor, quantidade ou pontos |
bool | Sim ou não: true / false | Se o pedido foi pago |
datetime | Data e hora | Horário de uma aula |
json | Objeto ou lista | Produtos 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
- Abra Dados → Coleções e clique em Adicionar.
- Informe o nome com letras latinas e sem espaços, para facilitar o uso nas reações.
- Clique em Campo para adicionar as colunas e escolher seus tipos.
- 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
boole um campo JSON parajson. - 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
ctxe 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.
- Na reação a um texto recebido, adicione Buscar na coleção (
record_search). Escolhaproducts, use{{text}}como consulta,namecomo campo de busca,aliasescomo sinônimos e salve o resultado emsearch. Os sinônimos podem ser texto ou uma lista de textos JSON. A busca ignora maiúsculas, minúsculas e pontuação. - Adicione Escolher a próxima etapa (
branch_result) usandosearch. 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. - Para vários resultados, use Botões dos registros encontrados na mensagem. Escolha
search, o camponamecomo título e a próxima reação. O assistente configurarábuttons_from.over = search.rows, o texto do botão ecarry.selected_id = {{item._record_id}}. Confira senamefaz parte dos campos retornados. Você ainda poderá editar o botão em detalhes. - Na reação seguinte, adicione Encontrar registros relacionados (
record_related): coleçãovariants, chaveproduct_id, valor{{ctx.selected_id}}e resultadovariants. Para ler o produto escolhido, useproductse 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. - 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,totalepaid, 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
jsonquando a estrutura do dado ainda não estiver definida.