# Combot Automation Compact v3: instruções para LLMs e referência do formato

Forneça este arquivo inteiro ao modelo junto com o pedido da regra. Ele descreve o formato importado pelo editor de Automação. A linguagem das regras é JSON Compact v3, não Python, YAML, JavaScript, o antigo Triggers v2 nem um pseudocódigo livre de “se → então”.
Os rótulos da interface são traduzidos; os valores JSON não. Por exemplo, `Known Combot links` corresponde a “Links de convite Combot” e `Combot custom admins` a “Administradores Combot” no editor. Não substitua esses valores JSON pelos rótulos da interface.

Revisão do documento: 9 de setembro de 2026. A referência foi conferida com o editor e o processador de Automação. As verificações de importação e Telegram concluídas estão listadas separadamente no final: inspecionar o código-fonte não comprova a versão de um serviço em execução.

## 1. Instruções para o modelo

Transforme o pedido da pessoa em uma regra de Automação sem mudar seu significado.

1. Defina o evento, as condições, as exclusões, a ação, o destinatário da ação e o destino da resposta. Para horários, defina o fuso; para comandos, defina se são enviados sozinhos ou como resposta. Não adicione moderação, recompensas, aleatoriedade ou exclusões de mensagens sem que isso tenha sido pedido.
2. Não adivinhe IDs de usuários, tópicos, endereços de chats, convites, níveis nem recursos ativados. O nome de um tópico não é seu ID. Faça perguntas quando faltar informação essencial. Você pode sugerir separadamente uma redação para a resposta, mas não deve apresentar uma regra incompleta como solução exata.
3. Sempre gere novas regras com `en: false`. Esta é uma convenção de preparação segura, não uma limitação da Automação. Omitir `en` significa ativada.
4. Use apenas os campos documentados. Para filtros aninhados marcados com “use uma exportação”, peça uma exportação real de uma configuração parecida; não invente a estrutura. Se um cenário não tiver suporte, explique a limitação em vez de escondê-la removendo condições.
5. Responda com uma explicação breve → um bloco JSON importável → configurações e verificações manuais. O JSON não deve conter comentários, reticências, IDs fictícios, explicações fora dos campos, vírgulas finais nem chaves inventadas como `when`, `if`, `then`, `conditions`, `actions` ou `event`.
6. Antes de devolver o resultado, analise um caso correspondente e um não correspondente. Para um comando em resposta, confira quem envia o comando separadamente do autor da mensagem original. Não diga que testou a regra no Combot se isso não aconteceu.

O JSON Schema que acompanha esta referência ajuda a gerar novas regras desativadas. Seus campos obrigatórios são intencionalmente mais restritos que a importação, e ele não aceita todas as exportações antigas. Filtros aninhados complexos são verificados apenas como objetos. Passar pelo esquema não comprova compatibilidade das condições, disponibilidade de recursos, respeito ao plano nem sucesso das ações no Telegram.

## 2. O que colar em Import

A raiz é um objeto com `v: 3` numérico e um array de regras `t`. Normalmente, devolva uma regra. Não devolva um array sozinho nem `{"triggers": [...]}`: esses não são os formatos da janela de importação.

Um exemplo mínimo completo:

```json
{
  "v": 3,
  "t": [
    {
      "n": "Comando de informações do curso",
      "en": false,
      "k": "c",
      "ctm": "p",
      "cm": ["/course_info"],
      "a": {
        "m": "a",
        "r": [
          {
            "i": "course_reply",
            "t": "s",
            "v": {
              "tx": "As gravações das aulas estão na mensagem fixada do chat.",
              "rp": "r"
            }
          }
        ]
      }
    }
  ]
}
```

`dv: "t3.compact.3"` é um marcador de esquema opcional. Novos resultados precisam apenas de `v` e `t`. A importação existente reconhece um invólucro `bundle`, mas ele não é necessário na geração.

Não adicione um `id` do servidor, `revision`, `chat_id`, `ck` calculado nem `$schema` dentro do pacote de importação. O servidor atribui um novo ID à regra. O `i` da ação é diferente: é um identificador local da linha, como `course_reply`. Ele deve ser único entre as ações da regra e conter de 1 a 80 letras latinas, dígitos, `_` ou `-`.

A mesma chave curta significa coisas diferentes em níveis diferentes: `t` na raiz é a lista de regras, `a.r[].t` é o tipo de ação e `a.r[].v` contém os parâmetros da ação. Não misture os níveis.

## 3. Campos principais da regra

| Campo | Significado |
| --- | --- |
| `n` | Nome não vazio, com até 80 caracteres no editor |
| `d` | Descrição opcional, com até 280 caracteres no editor |
| `en` | `false` para uma nova regra desativada |
| `e` | Array de códigos de evento, exceto em comandos |
| `k`, `cm`, `ctm` | Modo de comando; veja abaixo |
| `a` | Plano de ações: `{"m":"a","r":[...]}` ou `{"m":"r","r":[...]}` |
| `s`, `ti` | Onde verificar o evento: chat de origem, Geral ou tópicos selecionados |
| `at` | Quando a correspondência é permitida; filtro de horário, não temporizador |
| `wh`, `wx`, `wm` | Autor do evento: grupos incluídos, exclusões e como combinar grupos |
| `cgr` | Condições numéricas: tempo no chat, mensagens, advertências, XP e reputação |
| `ua`, `ux`, `uar`, `ul`, `ulx` | Características do participante, valores de campos e idioma |
| `twh`, `twx`, `tcg`, `tua`, `tux`, `tur`, `tlg`, `tlx` | Verificações do outro usuário do evento, como autor da mensagem respondida ou participante que entra |
| `tv`, `tr`, `ty`, `cs`, `lmin`, `lmax` | Condições de texto |
| `mti`, `mtx`, `me`, `mex` | Tipos de mensagem e entidades de texto |
| `il`, `ilc`, `ilx` | Links de convite para solicitações de entrada |
| `rct`, `rnt`, `rnx`, `rcy`, `rcx`, `rcn`, `rcm` | Condições de reações |
| `chl` | Link direto para uma lista de tarefas específica em seus eventos de alteração |
| `cl` | Limpeza padrão da resposta anterior: `n` ou `ps` |
| `ov` | Conjuntos alternativos de condições OU; use uma exportação para casos complexos |

Não preencha todos os campos. Adicione apenas as condições pedidas que sejam relevantes para o evento escolhido. Uma entrada, por exemplo, não precisa de palavras-chave de mensagem; um contador agregado de reações não tem um usuário específico para recompensar automaticamente.

## 4. Eventos

| `e` | Quando é executado |
| --- | --- |
| `["m"]` | Nova mensagem no chat |
| `["em"]` | Edição de mensagem |
| `["m","em"]` | Nova mensagem ou edição |
| `["lc"]`, `["el"]`, `["lc","el"]` | Comentário do canal vinculado, edição ou ambos |
| `["cp"]`, `["ec"]`, `["cp","ec"]` | Publicação no contexto do canal vinculado, edição ou ambos |
| `["jr"]` | Solicitação de entrada |
| `["nm"]` | Participante entrou |
| `["ml"]` | Participante saiu ou foi removido |
| `["cb"]`, `["rb"]` | Impulso adicionado ou removido |
| `["mr"]` | Reações de um usuário específico mudaram |
| `["rc"]` | Contadores agregados de reações anônimas atualizados no contexto do canal vinculado |
| `["ck"]` | Nova lista de tarefas |
| `["cd"]` | Tarefas da lista marcadas como concluídas |
| `["ca"]` | Tarefas adicionadas à lista |

Não combine tipos de evento sem relação, como `["m","nm"]`; use regras separadas. Os pares de novo e editado listados são permitidos. Não gere o modo oculto de bot convidado `gm`.

Uma edição é um acionamento separado. Não a adicione automaticamente a XP, reputação, advertências ou qualquer ação que a pessoa espere acontecer uma única vez.

## 5. Comandos simples e comandos em resposta

Um comando simples, como uma resposta informativa:

```json
{"k":"c","ctm":"p","cm":["/course_info"]}
```

Um comando que um moderador envia como resposta à mensagem de um participante:

```json
{"k":"c","cm":["/team_pause"]}
```

Estes são fragmentos de campos da regra, não pacotes de importação independentes.

Não adicione `e` a um comando. Forneça em `cm` uma lista não vazia de comandos personalizados em minúsculas, começando com barra e usando letras latinas, dígitos e `_`. Não apresente um comando inventado como se fosse integrado ao Combot. Para comandos em resposta, omita `ctm`; não escreva `reply_target`, `r` nem o nome de uma pessoa ali.

Um comando simples não tem destinatário para ações sobre usuários. Use um envio de mensagem e, apenas se for pedido explicitamente, a exclusão da mensagem do comando. Silêncios, advertências, XP e outras ações sobre uma pessoa exigem um comando em resposta.

Em um comando em resposta, `wh` verifica quem enviou o comando, enquanto `twh` e os outros campos `t...` verificam o autor da mensagem respondida. Use `v.tg: "t"` para agir sobre este último. Se Anna responde `/team_pause` a Ilya, restrinja Ilya, não Anna.

Verificar apenas `twh` não limita quem pode chamar o comando. Um comando de moderação deve incluir `wh` conforme o pedido. A ação `d` exclui o próprio comando, não a mensagem de Ilya.

Não substitua o modo de comando por uma busca da string `/team_pause` em `tv`. Não adicione condições de comando ocultas pelo editor, como horários, sem uma exportação verificada.

## 6. Participantes e exclusões

`wh` e `wx` usam estas strings exatas, não rótulos traduzidos:

`New members`, `Regular members`, `Ex-members`, `Whitelisted users`, `Admins`, `Telegram admins`, `Combot custom admins`, `Owner`.

Uma lista de inclusão vazia não impõe restrição por grupo. Normalmente você pode omitir `Anyone`. `wm: "o"` exige um grupo correspondente; `wm: "a"` exige todos os grupos selecionados. Exclusões em `wx` impedem a correspondência independentemente dos grupos positivos.

Exemplo: qualquer pessoa, exceto administradores, pode enviar a mensagem correspondente:

```json
{"wx":["Telegram admins","Combot custom admins","Owner"]}
```

Exemplo: somente um administrador do Telegram ou o dono pode chamar o comando:

```json
{"wh":["Telegram admins","Owner"],"wm":"o"}
```

Não confunda os papéis. `Combot custom admins` descreve permissões do Combot, não administradores do Telegram. No processador, `Admins`, assim como `Telegram admins`, verifica administradores do Telegram incluindo o dono; não acrescenta administradores do Combot. Para permitir os dois grupos, liste `Telegram admins` e `Combot custom admins` com `wm: "o"`. `Regular members` significa membros atuais conhecidos, não pessoas com muito tempo de participação ou muitas mensagens. `New members` usa as configurações e exceções de novatos do chat; não são “os primeiros sete dias” fixos. Use `cgr` para uma duração exata.

Não gere `Core members` nem `Non-members`: não há definições confiáveis fornecidas para novas regras. A ausência de informações de participação não comprova que alguém nunca pertenceu ao chat.

Para o alvo, use `twh`, `twx` e `twm`. Obtenha valores contextuais adicionais, como `Target self`, `Target bots`, `Target Combot` e `Target linked channel post`, de uma exportação adequada; não os adivinhe nos filtros do remetente.

Para `nm` e `ml`, `wh`/`wx` descrevem quem iniciou a entrada ou remoção; `twh`/`twx` descrevem o participante cujo status mudou. Se Anna adiciona Ilya, as condições de novato pertencem a Ilya pelos campos `t...`, não a Anna. Escolher `v.tg` em uma ação não troca essas condições.

`am: "o"` verifica se é administrador do Telegram; `am: "n"` exclui administradores. Isso não substitui a combinação de papéis em `wh`/`wx`. Prefira grupos explícitos para novas regras.

## 7. Tempo no chat, atividade, XP e reputação

Condições numéricas ficam em `cgr`, ou `tcg` para o alvo. Este fragmento significa que o participante está no chat há no máximo uma hora e tem no máximo cinco mensagens registradas:

```json
{
  "cgr": {
    "logic": "All",
    "statistics": {
      "rules": [
        {"metric":"joinedDays","unit":"h","op":"lte","value":"1"},
        {"metric":"messageCount","unit":"c","join":"and","op":"lte","value":"5"}
      ]
    }
  }
}
```

Operadores: `eq` significa igual, `gte` pelo menos e `lte` no máximo. Sempre declare o operador explicitamente. Não traduza “menos de cinco” como `lte: 5`: para um contador inteiro, é `lte: 4`. Não use uma comparação de duração exata `eq` quando a pessoa quer dizer “pelo menos”: o tempo continua passando.

Métricas de estatísticas:

- `joinedDays`: tempo desde a entrada neste chat, não a idade da conta nem da pessoa. Unidades: `s`, `m`, `h`, `d`, `w`, `mo`. Um dia tem 24 horas, uma semana tem 7 dias e um mês aqui tem 30 dias. Novas regras sempre devem incluir uma unidade.
- `messageCount`: mensagens registradas neste chat; unidade `c`.
- `warns`: advertências ativas; unidade `c`.

“Uma mensagem registrada” é `{"metric":"messageCount","unit":"c","op":"eq","value":"1"}`. Isso não garante execução única: as atualizações do contador e o processamento do evento podem acontecer separadamente.

Outras seções:

```json
{
  "cgr": {
    "logic": "All",
    "xp": {
      "xp": {"rules":[{"op":"gte","value":"100"}]}
    },
    "reputation": {
      "reputation": {"rules":[{"op":"gte","value":"5"}]}
    }
  }
}
```

Limites por nível usam `cgr.xp.rank.rules`, mas os valores devem vir dos níveis reais do chat, não de nomes inventados. As linhas aceitam `join: "and" | "or"` e `mode: "include" | "exclude"`. Use E explícito para condições simples e uma exportação real para encadeamentos E/OU complexos. `cgr.logic: "All" | "Any"` combina as seções. Uma linha numérica de exclusão é uma proibição: uma correspondência positiva em outra seção da mesma variante de condição não pode contorná-la.

Não crie verificações de tempo desde a primeira mensagem ou outra primeira atividade: `firstMessageAge` e `firstOtherActivityAge` estão indisponíveis. Não prometa “atividade da semana passada” usando o total de `messageCount`. Dados indisponíveis não devem virar zero automaticamente.

## 8. Características e campos do usuário

`ua` exige características; `ux` as exclui. Valores exatos: `Any username`, `Telegram Premium`, `Bot account`, `Any last name`. Por exemplo, `{"ux":["Bot account"]}` exclui bots.

`ul` e `ulx` incluem e excluem códigos de idioma do usuário, se o Telegram os tiver fornecido. Não se trata do idioma de uma mensagem nem da nacionalidade. Não deduza o idioma pelo nome do participante.

Condições sobre valores específicos ficam em `uar`, ou `tur` para o alvo. Campos aceitos: `user_id`, `name`, `username`, `last_name`, `bio`. A biografia pertence ao contexto de solicitação de entrada; não é um campo de perfil sempre disponível para todos os membros.

Uma condição de nome de usuário tem esta estrutura:

```json
{
  "uar": {
    "username": {
      "rules": [
        {"mode":"include","matchType":"Exact match","values":["example_member"]}
      ]
    }
  }
}
```

Isso demonstra a estrutura, não um membro real. Para um pedido de verdade, use apenas o nome de usuário fornecido pela pessoa, sem `@`; pergunte se estiver faltando. Forneça IDs como strings em `values`. Para controle de acesso, prefira um ID fornecido explicitamente: nomes e nomes de usuário podem mudar.

Aqui, `matchType` usa as strings completas `Exact match`, `Partial match` e `Regular expression`, não os códigos de texto de mensagem `f`, `p` e `r`. Valores em uma linha são alternativas; as linhas têm `join`. Não invente `Starts with` nem `Ends with` para esses campos.

`ual` e `tul`: `a` significa todas as regras; `o`, qualquer grupo. Use uma exportação para as estruturas de grupo `uag` e `tug` neste perfil de geração.

## 9. Texto e tipo de mensagem

Use `tv`, um array de strings, para procurar frases. Basta uma string corresponder. Por exemplo:

```json
{"tv":["onde está a gravação","gravação da aula"],"tr":"p","ty":"p","cs":false}
```

`tr`: `p` significa frases, `w` palavras e `r` expressões regulares. O modo de palavras não exige todas as palavras listadas. A correspondência parcial comum também não garante limites de palavras: “gato” pode corresponder dentro de “gatos”.

`ty`: `f` significa o texto inteiro, `p` parte do texto, `s` o início, `e` o final e `r` uma expressão regular. `cs: true` diferencia maiúsculas de minúsculas; `false` ou a omissão não diferencia. Uma resposta simples de perguntas frequentes precisa apenas de `tv`: a busca de frases sem diferenciar maiúsculas e minúsculas é o padrão.

`lmin` e `lmax` limitam o comprimento do texto. Um limite vazio ou zero não impõe restrição daquele lado. Não confunda comprimento do texto com quantidade de palavras.

Use expressões regulares apenas quando a correspondência simples não bastar. Forneça o padrão como uma string JSON, escapando as barras invertidas; não adicione automaticamente delimitadores JavaScript `/.../i`. Para exigências de palavras exatas ou negações complexas, explique exemplos correspondentes e não correspondentes.

`mti` inclui tipos de mensagem; `mtx` os exclui. Valores principais: `photo`, `video`, `animation`, `audio`, `document`, `sticker`, `voice`, `video_note`, `contact`, `location`, `poll`, `dice`, `game`, `paid_media`. Por exemplo, `{"mti":["voice"]}` significa mensagens de voz; `{"mti":["photo","video"]}` significa foto OU vídeo, não os dois anexos ao mesmo tempo.

O editor também tem `text` e `caption`. Eles participam das configurações de conteúdo textual; não trate `caption` como um tipo independente de anexo do Telegram. Para “apenas legendas de fotos” ou uma distinção rígida entre texto e legendas, obtenha uma exportação dessa configuração. O codec pode omitir padrões, incluindo um `text` sozinho; esse valor apenas no JSON de entrada não comprova que a restrição sobreviva à importação.

`me` e `mex` exigem ou excluem entidades de texto. Valores: `bot_command`, `url`, `text_link`, `mention`, `hashtag`, `cashtag`, `email`, `phone_number`, `emoji`, `custom_emoji`, `bold`, `italic`, `underline`, `strikethrough`, `code`, `pre`, `spoiler`, `blockquote`, `expandable_blockquote`. `mel: "a"` exige todas as entidades incluídas; `"o"` exige pelo menos uma. Para qualquer link visível ou oculto: `{"me":["url","text_link"],"mel":"o"}`.

`mef` restringe links específicos, comandos e outras entidades; `mmo` descreve propriedades de mídia; `mtg` e `mog` são grupos de condições; `csx`/`cse` são conjuntos de caracteres. Gere esses campos complexos a partir de uma exportação real. Não invente substitutos como `max_file_size`, `allowed_domains`, `mime`, `language` ou `contains_all`.

## 10. Horário e tópicos do chat

`s`: `sc` significa chat de origem, `gn` Geral e `st` tópicos selecionados. Neste último caso, `ti` contém IDs positivos de tópicos.

A importação redefine os tópicos de origem selecionados para todo o chat de origem e os tópicos de envio selecionados para o tópico atual. Isso acontece mesmo com IDs corretos e também vale para alternativas OU. Se o cenário depender de um tópico, cite-o na explicação e nas configurações manuais obrigatórias. Não diga que o resultado está pronto para ativar antes de selecionar os tópicos novamente.

`at` define o horário permitido para o evento; não agenda um envio independente. “Responder a uma pergunta à noite” é possível. “Publicar todos os dias às 19h sem um evento de entrada” precisa de um agendador, não deste gatilho.

O bot verifica o horário atual ao processar o evento, não a data e hora da mensagem original. Uma edição de manhã verifica o horário da manhã, mesmo que a mensagem original tenha sido escrita à noite.

Uma janela semanal, de segunda a sexta-feira, das 09:00 às 18:00 UTC:

```json
{"at":{"m":"w","wd":[0,1,2,3,4],"tw":[{"startMinute":540,"endMinute":1080}]}}
```

`wd`: 0 é segunda-feira e 6 é domingo. Os horários são minutos inteiros desde a meia-noite UTC, de 0 a 1439. As janelas semanais incluem o último minuto. Uma janela que passa da meia-noite pode ter início maior que o fim; o dia da semana usa a data UTC atual, não o dia em que o “turno” começou. Confira os dois lados da meia-noite em vez de adivinhar os dias necessários.

09:00 e 18:00 em Moscou correspondem a 06:00 e 15:00 UTC: minutos 360 e 900. Para parar de corresponder exatamente às 18:00, o último minuto permitido é 14:59 UTC, ou `endMinute: 899`. Para outros fusos, considere a diferença e possíveis mudanças de horário de verão. Não informe o horário local como UTC sem converter.

Um intervalo de datas:

```json
{"at":{"m":"d","s":"2026-10-01T00:00:00Z","e":"2026-10-07T23:59:59Z"}}
```

Esses valores ilustram a estrutura, não as datas da campanha da pessoa. O início deve vir antes do fim. Os dois limites estão incluídos neste modo. `Z` significa UTC.

Horários de fechamento usam as configurações existentes do chat: `{"at":{"m":"c"}}`; fora desses horários: `{"at":{"m":"c","i":true}}`. O modo de fechamento inclui o início e exclui o fim. O gatilho não configura os horários de fechamento do chat. Sem horários válidos, não prometa que a condição direta ou invertida funcione.

## 11. Links de convite, reações e listas de tarefas

### Convites

Para solicitações de entrada `["jr"]`, `il` aceita `Known Combot links`, `External invite link` ou `Any source`. Omita quando nenhuma restrição for necessária.

`Known Combot links` significa links no catálogo desse chat no Combot. `ilc` e `ilx` listam códigos de links incluídos e excluídos dentro do catálogo; obtenha os códigos exatos de uma exportação ou dos dados fornecidos. Listas vazias mantêm a verificação da categoria geral.

`External invite link` significa um link identificado fora de todo o catálogo do Combot, não “tudo menos meus dois links selecionados”. Uma origem desconhecida ou um catálogo indisponível não pode ser tratado como link externo. Não prometa que essa condição capture toda solicitação sem um convite conhecido.

### Reações de usuários

Evento `["mr"]`. `rct` contém `added` e/ou `removed`. `rnt` e `rnx` incluem e excluem reações no novo estado do usuário. Se qualquer um estiver preenchido, `rct` deve incluir `added`.

O processador executa `mr` apenas quando o Telegram fornece `user`. Uma reação enviada como canal ou administrador anônimo com `actor_chat` não aciona esse evento. Isso é diferente da contagem agregada de reações `rc`.

```json
{"e":["mr"],"rct":["added"],"rnt":["👍"]}
```

Os valores de reação são emojis comuns, IDs de emojis personalizados como strings ou `paid`. `rnt` verifica o novo estado completo, não apenas a diferença. Se 👍 já estava presente e o usuário adiciona outra reação, a condição pode corresponder novamente. O destinatário da ação `u` aqui é a pessoa que mudou a reação; ele não recompensa automaticamente o autor da mensagem.

### Contagens agregadas de reações

Evento `["rc"]`. `rcy`/`rcx` escolhem os tipos de reação contados. `rcn`/`rcm` definem os limites inferior e superior da contagem como inteiros não negativos. Zero ou a omissão significa sem limite daquele lado.

```json
{"e":["rc"],"rcy":["👍"],"rcn":10}
```

Isso verifica o valor atual em uma atualização, não “atingiu dez pela primeira vez”. Outra atualização correspondente pode executar a ação novamente. O contador agregado anônimo não tem um usuário específico que reagiu.

### Listas de tarefas

Para `["cd"]` e `["ca"]`, `chl` limita a regra a uma lista de tarefas. Se a pessoa quiser uma lista específica, peça o link direto da mensagem. Se quiser todas as listas correspondentes em um chat ou tópico, não adicione `chl`.

Links diretos do Telegram, incluindo links com número do tópico, são aceitos; links com `?comment=` não são. Não invente um endereço. Para um link público, o processador do evento deve conhecer o nome de usuário do chat; uma URL aparentemente válida não comprova a correspondência.

## 12. Ações

`a.m: "a"` executa todas as linhas na ordem. `a.m: "r"` executa todas as linhas marcadas com `fr: 1` e exatamente uma linha não marcada escolhida aleatoriamente, se houver alguma. As linhas selecionadas mantêm a ordem original. Use o modo `a` a menos que a aleatoriedade tenha sido pedida; não adicione `fr` fora do modo aleatório.

| Código `a.r[].t` | Ação | Parâmetros `v` |
| --- | --- | --- |
| `s` | Enviar uma mensagem | `tx` e formatação; veja abaixo |
| `d` | Excluir a mensagem que acionou a regra | Sem parâmetros |
| `w` | Adicionar advertências | `tg`, `c` positivo, normalmente 1 |
| `rw` | Remover advertências | `tg`, `c` positivo, normalmente 1 |
| `m` | Restringir o envio de mensagens | `tg`, duração `du` em segundos |
| `b` | Banir | `tg`, duração `du` em segundos |
| `k` | Remover do chat permitindo nova entrada | `tg` |
| `um` | Retirar restrições de envio | `tg` |
| `ub` | Retirar um banimento | `tg` |
| `du` | Excluir mensagens armazenadas do usuário disponíveis ao bot | `tg` |
| `x` | Alterar XP | `tg`, inteiro `v` diferente de zero, de −99999 a 99999 |
| `r` | Alterar reputação | `tg`, inteiro `v` diferente de zero, de −999 a 999 |
| `ja` | Aprovar uma solicitação de entrada | Apenas evento `jr`, sem parâmetros |
| `jd` | Recusar uma solicitação de entrada | Apenas evento `jr`, sem parâmetros |

Não confunda o código de ação `du` com o campo de duração `v.du`. A duração está em segundos, não minutos: uma hora é 3600. Zero em um silêncio ou banimento significa sem fim especificado; nunca o use no lugar de uma duração desconhecida. O motivo pode ser escrito em uma mensagem separada se for pedido; não prometa um motivo personalizável da punição por um campo não documentado.

Destinatário de ações sobre usuários `v.tg`:

- `u`: o participante que causou o evento.
- `t`: o alvo definido pelo contexto, como o autor da mensagem respondida. Não é um ID literal.
- `l`: o criador do link de convite no catálogo do Combot, no contexto de solicitação de entrada.
- `b`: os dois participantes disponíveis no contexto correspondente. Não significa “todos no chat”.

Sempre especifique o destinatário. Comandos simples não aceitam ações sobre usuários. Comandos em resposta aceitam remetente, alvo e ambos. Para uma solicitação de entrada, use ações separadas para o solicitante (`u`) e o criador conhecido do link (`l`) se precisar dos dois: `b` não significa solicitante mais criador do link. O editor oferece o criador do link para solicitações de entrada; não ofereça a mesma escolha em instruções passo a passo para entrada de membro. Para outros eventos, use apenas destinatários disponíveis naquele evento.

Um alvo desconhecido não deve transformar uma ação em punição para quem enviou o comando. Não prometa substituição por outra pessoa. A ação `du` não garante excluir todo o histórico de um participante: o bot está limitado às mensagens disponíveis e às possibilidades do Telegram.

Advertências, níveis e reputação devem estar ativados quando o cenário depender deles, e a moderação precisa das permissões adequadas do bot. Retirar silêncio, retirar banimento e aprovar solicitação de entrada são ações separadas.

Eventos de solicitação de entrada permitem envios de mensagem, ações sobre usuários disponíveis e `ja`/`jd`; a exclusão de mensagem `d` não é adequada. Para eventos sem mensagem, não adicione exclusão nem resposta a uma mensagem inexistente.

## 13. Texto e destino da resposta

Parâmetros da ação `s`:

| Campo | Significado |
| --- | --- |
| `tx` | Texto não vazio com até 4096 caracteres; HTML aceito pelo Telegram é permitido |
| `d` | `sc`: chat de origem; `lg`: canal de registro configurado; padrão `sc` |
| `tp` | `ct`: tópico atual; `gn`: Geral; `st`: tópicos selecionados; padrão `ct` |
| `to` | IDs positivos dos tópicos selecionados; redefinidos pela importação |
| `rp` | `r`: responder à mensagem que acionou a regra; omissão: mensagem independente |
| `cl` | `n`: manter a resposta anterior; `ps`: excluir a resposta anterior desta linha |
| `bt` | Linhas de botões de URL: array de arrays de objetos com `text` e `url` |
| `ph` | Array de URLs de imagens para prévias de links |
| `pa` | `true`: colocar a prévia acima do texto |

`rp: "r"` é mantido para o chat de origem e o tópico atual. Não prometa o mesmo vínculo de resposta no registro ou em outro tópico. Não coloque chats externos arbitrários, canais nem mensagens privadas em `d`.

Se `cl` estiver ausente na linha, a configuração da regra é herdada. `cl: "ps"` na regra ativa a limpeza da resposta anterior; `cl: "n"` explícito na linha tem prioridade. A limpeza pertence a uma regra, linha de ação e destino específicos. Linhas aleatórias diferentes não se tornam uma única “última mensagem de boas-vindas” compartilhada.

Para uma resposta comum, você pode usar `<b>Informações do curso</b>\nAs gravações estão na mensagem fixada.` Não forneça Markdown como HTML. Escape links e texto corretamente. Adicione botões e imagens apenas com URLs reais fornecidas pela pessoa; `ph` não envia um álbum de fotos.

Variáveis confirmadas no contexto de mensagem: `{name}`, `{uid}`, `{name_link}`, `{from.id}`, `{from.title}`, `{from.username}`, `{chat.id}`, `{chat.title}`, `{chat.username}`, `{message.id}`, `{message.timestamp}`, `{timestamp}`, `{group_name}`, `{reply_to_uid}`, `{reply_to_name}`, `{reply_to_name_link}`. A disponibilidade depende do evento. Não invente `{target.name}`, `{user.first_name}`, `{reaction_count}` nem variáveis parecidas.

Em um comando em resposta, `{from.title}` descreve quem enviou o comando, não o participante punido ou recompensado. Escolher `tg: "t"` não muda o significado das variáveis. Se não tiver certeza de que o evento fornece o nome necessário, use uma redação neutra.

Na entrada, `{from.title}` também não garante o nome do novato: se Anna adiciona Ilya, Anna é a autora da ação. Use boas-vindas genéricas, como “Boas-vindas a {chat.title}!”, sem nome.

As ações não são uma transação. Uma mensagem após um silêncio não comprova que o Telegram aplicou o silêncio. Não redija uma confirmação incondicional de punição como resultado verificado: não há uma condição separada de verificação de sucesso documentada aqui.

## 14. Alternativas, limites e promessas sem suporte

`ov` contém condições alternativas para a mesma regra. Elas compartilham o evento e as ações da regra principal, em vez de definir cenários independentes. Uma exclusão em uma alternativa não é global. Se uma proibição deve valer sempre, mantenha-a em todas as alternativas. Uma alternativa com `en: false` não participa da correspondência.

Use exportações reais do editor para novos `ov`, `mtg`, `mog`, `uag`, `tug`, `mef` e `mmo` complexos. Não crie árvores OU recursivas nem coloque cadeias de ações separadas dentro de alternativas esperando execução independente.

Campos de compatibilidade `mt`, `mtl`, `t`, `rmi` e `rme` podem aparecer em exportações. Não os adicione no lugar das configurações principais documentadas sem motivo. Para restrições simples de resposta, use `rm`: `a` qualquer mensagem, `r` apenas respostas, `rb` respostas a um bot, `rc` respostas ao Combot, `nr` mensagens que não são respostas. Não use `rm: "cr"` no lugar dos novos campos de comando.

Não gere campos antigos ou internos `lf`, `fc`, `lo` nem campos de interface `actions`, `destination`, `topic`, `applyTarget` e `alwaysRun`. O formato Compact os representa de outra maneira, e algumas configurações nem são recursos ativos.

Limites para planejar:

- Free: até 2 regras salvas; Pro: até 50; Business: até 100. Regras desativadas também contam. Considere as regras existentes ao calcular as vagas restantes.
- Alternativas OU adicionais por regra: Free 0, Pro 2, Business 5.
- Até 100 linhas de ações por regra, com um orçamento calculado separado de 20 ações por execução do plano.
- Um envio custa 1 por destino único, ou 2 com limpeza da resposta anterior. Ações do Telegram sobre usuários são contadas por destinatário, então `b` pode reservar o dobro. XP e reputação custam 0 neste cálculo. O modo aleatório conta as linhas obrigatórias mais a escolha aleatória de maior custo.
- Este é um cálculo interno, não a promessa de exatamente vinte requisições de rede incluindo todas as operações auxiliares. Se a próxima linha exceder o orçamento restante, a execução para; ações concluídas não são desfeitas.

Não prometa execução apenas por horário sem evento, “no máximo uma vez por hora”, recompensa única por reação, proteção contra abuso de recompensas por eventos repetidos, somente a primeira passagem por um limite, execução exatamente uma vez, processamento de chats externos arbitrários, idade da conta nem estatísticas de atividade de um período passado arbitrário. Se algo disso for essencial, explique que a regra descrita sozinha não basta.

A importação adiciona novas cópias de regras; não migra o antigo Triggers v2. Você pode reescrever o significado de uma regra antiga em Compact v3, mas não apresentar o JSON antigo como uma importação pronta.

## 15. Cenários de aceitação dos exemplos

O diretório `examples` que acompanha o guia contém seis pacotes independentes, cada um com uma regra desativada:

| Arquivo | Caso correspondente | Verificações adicionais |
| --- | --- | --- |
| `01-course-command.json` | Um participante envia `/course_info` | Texto simples sem o comando não deve disparar uma resposta |
| `02-recording-faq.json` | O texto contém “onde está a gravação” | Uma pergunta sem relação não deve disparar resposta; a busca parcial pode corresponder a uma frase maior |
| `03-random-welcome.json` | Um novo participante entra | Uma mensagem de boas-vindas deve ser escolhida, não as três |
| `04-moderator-reply-mute.json` | Um administrador do Telegram ou o dono responde `/team_pause` a um participante | Membros comuns não podem chamar; alvos administradores são excluídos; um comando sem resposta não deve restringir quem o enviou |
| `05-known-link-join-request.json` | Uma solicitação usa um link do catálogo do Combot | Origens externas ou desconhecidas não devem corresponder; todos os links conhecidos correspondem, a menos que alguns sejam selecionados |
| `06-thumbs-up-reaction.json` | Um usuário adiciona uma reação e o novo estado contém 👍 | Remover 👍 não corresponde; mudanças correspondentes repetidas podem enviar outra mensagem |

Estes são cenários de aceitação para seu chat, não uma afirmação de que todos foram executados. As verificações concluídas vêm abaixo. Todo exemplo precisa de uma conferência das configurações e dos recursos no seu chat antes de ser ativado.

## 16. Fontes do formato e verificações concluídas

O formato foi conferido com Rails `0d80ce4788ef5adc5c7c1b79e85c6b8be27cc00e` e bot `ddc1a8a6b6ab99bd2517d783870495990c7058e5`. Essas revisões da branch main incluem as correções coordenadas do editor e da Automação. Os merges do PR #78 de Rails e do PR #56 do bot foram confirmados no Codeberg; as revisões exatas dos processos implantados não foram estabelecidas independentemente.

Fontes principais: `trigger_compact_codec_helpers.js`, `trigger_import_export_helpers.js`, `trigger_validation_helpers.js`, registros de eventos e ações, `user_attribute_model_helpers.js`, `AutomationController`, o contrato detalhado da Automação em `docs/MONGODB.md` e o processamento de condições e ações em `automation.py`.

Os seis exemplos originais foram verificados em memória com o codec do código-fonte do editor: decodificar, reconstruir, decodificar novamente e conferir a estabilidade do resultado normalizado. As ações e o estado desativado foram preservados. O codec omite alguns padrões, então a comparação usou resultados normalizados, não igualdade byte a byte com o JSON de entrada.

Em 8 de setembro, o estado desativado dos seis exemplos originais foi verificado após importação pelo editor de produção em combot.org, salvamento no servidor e recarregamento da página. Isso não substitui a verificação de cada condição e ação no Telegram.

Os casos de comando e perguntas frequentes foram verificados no Telegram: pedidos correspondentes receberam as respostas esperadas e os controles não. Apenas `/course_info` foi alterado para um nome de teste único permitido pelas proteções do testador; as demais configurações dos exemplos foram mantidas. Esses resultados não comprovam automaticamente outros eventos e ações.

Para `06-thumbs-up-reaction.json`, adicionar 👍 de um perfil pessoal gerou uma resposta esperada; remover não gerou nenhuma. A identidade e os conjuntos de reações antigo e novo foram confirmados por um observador separado da Bot API. Boas-vindas aleatórias na entrada, aplicação de silêncio e aprovação de uma solicitação real de entrada não foram testadas nessa rodada; importar não comprova a execução das ações.

As regras de teste criadas foram removidas e a restauração da lista original foi conferida; as mensagens de resultado continuam no grupo de teste. O JSON Schema é documentação complementar, não está conectado ao produto nem é apresentado como um validador integrado existente.

Em 9 de setembro, a referência editorial foi conferida com Rails `0d80ce4788ef5adc5c7c1b79e85c6b8be27cc00e` e bot `0a491a6ee50c57e98c1d9de04819253d15214506`. Os esclarecimentos abrangem o limite de nome no editor, os grupos de administradores, os participantes dos eventos, os destinatários das ações e os links opcionais de listas de tarefas. Esta é uma revisão documental baseada no código-fonte, não uma nova rodada no Telegram. A redação localizada dos exemplos não foi testada ao vivo de forma independente.