Conecte a moderação do Telegram à sua própria stack: API e webhooks

1Moderação que conversa com o resto da sua stack

Um bot de moderação que vive inteiramente dentro do Telegram é útil, mas também é uma ilha. As decisões que ele toma — cada mensagem que remove, cada usuário que tria, cada ataque que repele — ficam trancadas em uma janela de chat, a menos que alguém abra o Telegram para olhar. Para uma única comunidade, tudo bem. Para uma equipe que administra a moderação como parte de uma operação maior, isso significa que o único sistema que mais sabe sobre quem abusa dos seus espaços é justamente o único sistema que não consegue conversar com nada mais que você usa.

A API REST pública e os webhooks fecham essa lacuna. Eles transformam o Telm de um bot autossuficiente em um componente que você pode conectar às ferramentas que já tem: seu monitoramento e plantão, seu arquivo de conformidade, seu próprio produto, seus painéis internos. O mesmo motor que protege seus grupos passa a ser algo que seus outros sistemas podem consultar, escutar e comandar.

Este guia percorre o que a API e os webhooks realmente expõem — os endpoints, os eventos, o modelo de segurança — e as coisas concretas que as equipes constroem com eles. Tudo abaixo é uma capacidade real disponível hoje; não há SDK para esperar nem nada descrito aqui que o produto apenas pretenda fazer.

2A API REST e suas chaves

A API fica em `https://api.telm.com/api/public/v1`. É uma interface REST simples — você a chama com requisições HTTPS comuns e JSON, a partir de qualquer linguagem, sem biblioteca cliente especial. Se o seu código consegue fazer uma requisição HTTP, ele consegue conversar com o Telm.

A autenticação é por chave de API. Você cria as chaves no painel, em Configurações → API & Webhooks, e cada uma é mostrada a você exatamente uma vez, na criação — copie-a para o seu cofre de segredos ali mesmo, porque ela não pode ser recuperada depois. As chaves têm o prefixo `tk_live_`, então são fáceis de reconhecer em logs e configurações. Cada chave carrega um escopo — leitura ou escrita — para que um serviço que só precisa puxar o registro de decisões possa ter uma chave somente leitura, enquanto uma automação que altera configurações recebe uma chave de escrita. Crie uma chave por sistema, e revogar uma chave vazada ou aposentada nunca perturba as outras.

O uso é governado por uma cota diária de requisições atrelada ao seu plano, então a vazão é previsível e um script descontrolado não consegue esgotar tudo. A verificação mais leve — a análise de spam em texto — está disponível em todos os planos dentro dessa cota; a superfície mais completa, do registro de decisões à gestão de configurações e aos webhooks, faz parte dos planos Pro e Business. Os números exatos estão detalhados no final.

3Triagem de textos e usuários sob demanda

Dois endpoints permitem rodar o julgamento do Telm sob demanda, a partir do seu próprio código, sem que uma mensagem sequer passe por um grupo do Telegram.

`POST /spam/check` envia um trecho de texto pelo exato motor de produção que protege suas comunidades — os sinais compartilhados de spammers, as regras de padrões, os classificadores — e devolve um veredito. Esta é a única chamada disponível em todos os planos, o que a torna um filtro de spam natural para o seu próprio produto: triagem de comentários, bios de cadastro, tickets de suporte ou anúncios de marketplace com a mesma detecção que protege seus espaços do Telegram. Adicione `include_ai` para incorporar um veredito de IA nos casos mais difíceis e ambíguos (disponível no Pro e no Business), e nesses planos você pode enviar em lote até vinte textos em uma única requisição, em vez de chamar uma vez por item.

`POST /users/check` tria uma pessoa, em vez de uma mensagem. Ele combina a lista global de bloqueio CAS e a base de dados própria do Telm, construída a partir da moderação em muitas comunidades, e devolve um nível de risco (no Pro e no Business) para você decidir quanto atrito aplicar — libere direto uma conta limpa, retenha uma arriscada para revisão. Conectá-lo ao seu próprio onboarding permite pegar um mau ator conhecido já na porta do seu site ou app, não só depois que ele entra em um grupo do Telegram.

Ambas as chamadas respondem na hora: você envia o texto ou o usuário e recebe a avaliação de volta na resposta. Não há fila a consultar nem callback a esperar — a decisão vem junto com a resposta.

4Ser avisado no momento em que acontece

Consultar o registro é ótimo para arquivamento, mas quando você quer *reagir* a algo no instante em que ocorre, você quer ser avisado, não perguntar. Os webhooks (no Pro e no Business) fazem exatamente isso: você registra um endpoint e o Telm lhe envia uma requisição HTTP no momento em que um evento relevante dispara. Os eventos cobrem os momentos que importam — `spam.detected` e `message.suspicious` para conteúdo, e `user.banned`, `user.kicked`, `user.muted`, `user.joined` e `user.left` para participação.

O uso óbvio é transformar uma onda de spam em um alerta. Aponte `spam.detected` para o seu sistema de monitoramento ou plantão e um surto repentino vira um chamado para quem estiver de serviço, no mesmo lugar em que caem seus outros incidentes — ninguém precisa estar de olho no Telegram para notar um ataque começando. O mesmo fluxo alimenta painéis em tempo real, mantém um sistema externo sincronizado com os banimentos ou dispara qualquer fluxo de trabalho que você quiser.

Como essas requisições vêm do mundo externo para a sua infraestrutura, toda entrega é assinada. Cada requisição carrega um cabeçalho `X-Telm-Signature` no formato `v1=hex(hmac_sha256(secret, "timestamp.body"))` — um HMAC-SHA256 sobre o timestamp e o corpo bruto, com chave em um segredo que só você e o Telm compartilham. Recalcular essa assinatura no seu lado prova que a requisição veio mesmo do Telm e não foi forjada nem adulterada em trânsito; o timestamp permite rejeitar replays antigos. Verifique a assinatura antes de confiar no payload — são poucas linhas de código e o passo mais importante em um receptor de webhook seguro.

5Uma entrega em que você pode confiar

Um modelo push só é confiável se ele lida com os momentos em que seu endpoint está lento, reiniciando ou brevemente fora do ar — e o do Telm lida. A entrega é ao menos uma vez: todo evento carrega um `id` estável, e o Telm continua tentando até seu endpoint reconhecê-lo. Como "ao menos uma vez" significa que o mesmo evento pode legitimamente chegar duas vezes, deduplique por esse `id` — registre os que você já processou e ignore repetições — e seu tratamento permanece correto, não importa quantas vezes uma entrega seja repetida.

As novas tentativas seguem uma programação que se alarga, em vez de martelar um endpoint com dificuldades: imediatamente, depois após um minuto, cinco minutos, trinta minutos, duas horas e seis horas — seis tentativas ao todo, espaçadas para dar espaço a um serviço em recuperação. Se um endpoint continuar quebrado — vinte falhas consecutivas e setenta e duas horas sem nenhuma entrega bem-sucedida — o Telm para de enviar para ele automaticamente e avisa você no Telegram, para que uma URL morta vire um aviso claro para consertar seu receptor, em vez de uma enxurrada silenciosa de falhas se acumulando.

Para acertar uma nova integração, você não precisa provocar eventos reais para testá-la. Um ping de teste permite disparar uma entrega de exemplo no seu endpoint sob demanda e confirmar que sua verificação de assinatura e seu handler funcionam, e um histórico de entrega mostra o que foi enviado e como cada tentativa se saiu — para você depurar um receptor problemático a partir do registro, em vez de adivinhar.

6Um registro consultável de cada decisão

Tudo o que o motor decide é registrado, e `GET journal` entrega esse registro ao seu código. Cada entrada é uma decisão: o veredito, a pontuação por trás dele, quais regras dispararam e a ação que se seguiu. Como é paginado por cursor, você pode percorrer todo o histórico de forma confiável — página após página, sem lacunas nem duplicatas — e puxá-lo para onde quer que você guarde seus registros.

É isso que faz do registro a espinha dorsal de um arquivo de conformidade. Equipes que precisam mostrar por que um membro foi removido — por uma política de plataforma, um contrato de cliente ou um regulador — exportam o registro para seu próprio armazenamento de longo prazo de forma programada, obtendo um relato independente e consultável de cada ação de aplicação que não depende de rolar de volta pelo Telegram. É a mesma evidência que o registro de auditoria do painel apresenta às pessoas, disponibilizada aos seus sistemas.

Ao lado dele, um endpoint de analytics devolve séries dia a dia — volumes e tendências ao longo do tempo — para você mapear a carga de moderação nas suas próprias ferramentas de business intelligence, junto de tudo o mais que acompanha, em vez de lê-la em uma tela. Tanto o registro quanto o analytics fazem parte dos planos Pro e Business.

7Gerenciando muitos grupos por código

A API não só lê e escuta — ela escreve. No Pro e no Business você pode aplicar `PATCH` às configurações de um grupo e executar create/read/update/delete completo nas suas regras e na sua lista branca, tudo programaticamente. Qualquer coisa que você configuraria à mão no painel, você pode configurar a partir de um script.

É isso que torna prática a moderação em escala. Uma agência ou um grande operador que gerencia dezenas de comunidades não quer abrir cada uma e clicar pelas mesmas mudanças; quer definir a política uma vez e aplicá-la em todos os lugares. Com a API você implanta uma nova regra, ajusta um limiar ou adiciona um endereço a cada lista branca em toda a frota em uma única passagem automatizada, e mantém os grupos em sincronia à medida que seus padrões evoluem.

Ela também permite que a política de moderação viva no seu próprio controle de versão. Mantenha a configuração desejada como código, aplique-a pela API, e cada mudança em como seus grupos são governados é revisada e versionada como o resto da sua infraestrutura — bem diferente de lembrar quais configurações você alternou em qual chat.

8O que cada plano inclui

A linha divisória é simples. A verificação de spam em texto está disponível em todos os planos, então até o nível gratuito pode usar a detecção do Telm como filtro no seu próprio produto. A superfície completa — triagem de usuários com níveis de risco, o registro de decisões e o analytics, a gestão de configurações e regras, e os webhooks — faz parte dos planos Pro e Business.

Todo plano recebe uma cota diária de requisições, dimensionada para que integrações mais pesadas fiquem em planos mais pesados:

• **Free** — 100 requisições de API por dia, apenas verificação de spam.
• **Basic** — 1.000 requisições de API por dia, apenas verificação de spam.
• **Pro** — 10.000 requisições de API por dia, além da superfície completa da API e dos webhooks.
• **Business** — 50.000 requisições de API por dia, além da superfície completa da API e dos webhooks.
• Crie suas chaves em Configurações → API & Webhooks, guarde-as no seu cofre de segredos, verifique a assinatura de cada webhook, e o mesmo motor que protege seus grupos passa a fazer parte da sua própria stack.