Coleções e dados

Coleções são as tabelas de dados próprias do seu bot. Nelas você pode guardar solicitações, pedidos, respostas de diálogos, pontuações em jogos, agendamentos — tudo o que o bot coleta dos usuários ou recebe de integrações. A seção fica no menu lateral: Dados → Coleções.

O que é uma coleção

Uma coleção é composta por campos (esquema que descreve as colunas) e registros (linhas com dados). Cada registro é um conjunto de valores pelos campos da coleção; internamente é armazenado como um documento JSON flexível, então a coleção suporta tranquilamente a adição de novos campos.

O nome da coleção é único dentro de um bot e é usado como identificador nas ações das reações (por exemplo, leads, orders, scores).

Tipos de campo

Ao criar uma coleção, você define a lista de campos e o tipo de cada um:

text — string (nome, e-mail, comentário).
number — número (valor, quantidade, pontuação).
bool — sim/não (true / false).
datetime — data e hora.
json — objeto ou array aninhado para valores complexos.

O tipo influencia como o campo é editado na interface e como o valor é convertido ao salvar. O esquema não é rígido: se um registro contiver um campo fora do esquema, ele será salvo e exibido como coluna separada.

Criando uma coleção

Abra Dados → Coleções e clique em Adicionar.
Informe o nome (em caracteres latinos, sem espaços — assim fica mais fácil referenciar nas reações).
Use o botão Campo para adicionar as colunas necessárias e escolher o tipo de cada uma.
Se necessário, defina as regras de retenção (veja abaixo) e salve.

Registros: visualização e edição

No cartão da coleção há um botão com ícone de tabela — ele abre a janela Dados com os registros desta coleção:

Visualização — todas as linhas são listadas, campo por célula, começando pelos mais recentes.
Adicionar registro — abre um formulário baseado no esquema da coleção; cada campo é editado conforme seu tipo (toggle para bool, campo JSON para json etc.).
Editar (lápis) — edita uma linha existente.
Excluir (lixeira) — remove uma linha.

Os registros também são preenchidos automaticamente pelas ações das reações do bot (veja abaixo). A edição manual e o preenchimento automático funcionam na mesma coleção.

Retenção

Para que a coleção não cresça indefinidamente, defina regras de limpeza automática:

Máximo de registros — quando o limite é ultrapassado, os registros mais antigos são excluídos.
Máximo de dias — registros mais antigos que o prazo definido são excluídos.

A limpeza é executada por um processo em segundo plano periodicamente; as regras podem ser combinadas.

Trabalhando com dados a partir das reações

As coleções se integram diretamente ao construtor de reações. Nas ações da reação estão disponíveis:

Criar registro — adiciona uma linha; os valores vêm de templates (por exemplo, {{user.id}}, {{message.text}}). Você pode definir uma chave de deduplicação para que uma chamada repetida atualize a mesma linha em vez de criar duplicatas.
Atualizar registros — altera as linhas que atendem a uma condição.
Buscar registros — lê linhas para o contexto de execução como array, para iterar sobre elas.
Excluir registros — remove linhas por condição.
Loop (for-each) — percorre um array do contexto e executa ações aninhadas para cada elemento (por exemplo, enviar uma mensagem para cada item de uma lista da coleção).

Assim o bot pode manter um CRM, acumular solicitações, adicionar pontos e gerar relatórios sem banco de dados externo.

Acesso a partir do Mini App

Os registros da coleção podem ser lidos a partir do Telegram Mini App do seu bot: o frontend solicita os dados da coleção pelo nome com filtros e limite. Isso permite exibir ao usuário seus pedidos, histórico ou tabela de líderes diretamente dentro do Telegram.

Dicas

Dê aos campos nomes curtos e em inglês (email, total, paid) — são mais fáceis de usar em templates de reações.
Para gravação idempotente (por exemplo, "uma solicitação por usuário"), use a chave de deduplicação.
Ative a retenção para logs e dados temporários, para que a coleção não cresça demais.
O tipo json é ideal quando a estrutura do valor não é conhecida de antemão.