REST API: automatize o Telm a partir do seu próprio código

1O que a API permite fazer

A REST API do Telm dá ao seu próprio código o mesmo alcance do painel: passar qualquer texto pelo fluxo antispam, consultar um usuário do Telegram antes de deixá-lo entrar, ler e alterar as configurações de proteção de um grupo, gerenciar regras personalizadas e listas de permissões, obter o registro de moderação e as análises, e registrar webhooks para eventos em tempo real.

Com isso, o Telm deixa de ser um bot que vive dentro dos seus grupos e vira uma infraestrutura que você pode conectar em qualquer lugar: um formulário de cadastro em um site, um bot de CRM, os seus próprios bots do Telegram ou um script que configura cem grupos de uma vez.

• URL base: api.telm.com/api/public/v1, um caminho estável e versionado (o v1 é a versão do contrato).
• Todas as requisições e respostas são JSON sobre HTTPS.
• A documentação interativa e a especificação OpenAPI 3.1 legível por máquina ficam na página para desenvolvedores: carregue a especificação no Postman, em um gerador de código ou em um agente de IA para montar a base de uma integração em minutos.
• As chamadas tarifadas retornam os cabeçalhos X-Quota-Limit, X-Quota-Used e X-Quota-Reset em todas as respostas.

2Como uma requisição passa pelo Telm

A API pública tem o próprio prefixo de caminho, /api/public/, separado do painel. Cada chamada é autenticada por uma chave de API em vez de uma sessão do navegador, verificada em relação ao seu plano e à sua cota, executada no mesmo mecanismo em produção que modera os seus grupos e retornada em JSON.

Como a API alcança o mesmo mecanismo e os mesmos dados do bot, tudo o que você pode ver ou alterar no painel também pode fazer pelo código, e qualquer alteração feita pelo código aparece no painel na hora.

• As requisições não têm estado: cada uma leva a própria chave e é independente.
• Uma chave age em nome da sua conta e só pode mexer em grupos onde a sua conta é administradora.
• O endpoint de verificação de spam usa exatamente o mesmo fluxo de regras de produção, então o veredito da API coincide com o que o bot faria no grupo.

3Autenticação com chaves de API

Toda requisição é autenticada com uma chave de API no formato tk_live_ seguido de caracteres aleatórios, e não com o login do seu painel. Você cria as chaves na sua conta e envia a chave no cabeçalho Authorization como token Bearer, ou em um cabeçalho X-API-Key.

O segredo completo é exibido uma única vez, no momento da criação. Depois disso, o painel lista cada chave apenas pelo prefixo curto, para que você a reconheça sem nunca guardar o valor completo. Se uma chave vazar, revogue-a e emita uma nova: a revogação vale na hora.

• Envie a chave como Authorization: Bearer tk_live_your_key_here (um cabeçalho X-API-Key também funciona).
• As chaves têm escopo de leitura ou de escrita: leitura para requisições GET e escrita para tudo o que altera dados. Uma chave somente leitura não pode criar nem editar.
• Você pode ter até dez chaves ativas ao mesmo tempo, então dá para usar uma chave separada para cada script ou serviço.
• Uma chave ausente ou inválida retorna 401; uma chave sem o escopo necessário retorna 403 insufficient_scope.

4Endpoints disponíveis

A API é organizada em torno das verificações de spam e de usuários, da gestão de grupos e do autoatendimento da conta. O endpoint de verificação de spam individual está aberto a todos os planos; o restante faz parte do Pro e do Business.

• POST /spam/check: passa um texto pelo mesmo mecanismo de regras que modera o tráfego real (todos os planos). No Pro e superiores é possível ativar uma verificação opcional com IA.
• POST /spam/check-batch: verifica até 20 textos em uma única chamada, apenas com regras (Pro+).
• POST /users/check: consulta um usuário do Telegram: status no CAS, sinais das decisões de spam do Telm e reputação nos seus grupos (Pro+).
• GET /groups e GET /groups/{id}: lista e lê os seus grupos (Pro+).
• GET e PATCH /groups/{id}/settings: lê e altera as configurações de proteção de um grupo (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules: gerencia as regras de moderação personalizadas (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist: gerencia a lista de permissões do grupo (Pro+).
• GET /groups/{id}/journal e GET /groups/{id}/analytics: lê o registro de moderação e as análises (Pro+).
• GET/POST/PATCH/DELETE /webhooks: gerencia os webhooks de eventos em tempo real (Pro+).
• GET /usage e GET /me: consulta a sua cota e as informações da chave; nunca consomem cota (todos os planos).

5O endpoint de verificação de spam em detalhes

POST /spam/check é o coração da API e o único endpoint que você pode testar em qualquer plano. Envie um corpo JSON com o texto a verificar; a resposta retorna um veredito, uma pontuação numérica, um valor de confiança e uma ação recomendada que você pode aplicar no seu próprio produto.

Um único texto pode ter até 10.000 caracteres. No Pro e superiores você pode ativar uma verificação com IA para os casos mais difíceis, descontada de uma cota diária separada de verificações com IA. Para grandes volumes, o endpoint em lote verifica até 20 textos em uma única chamada e conta a cota por item.

• Use o veredito e a pontuação para decidir o que o seu produto faz: bloquear o envio de um formulário, sinalizar um lead ou remover automaticamente uma mensagem no seu próprio bot.
• O endpoint em lote usa apenas regras; a escada de IA só está disponível no endpoint de texto individual.
• Os corpos das requisições têm tamanho máximo (cerca de 64 KB para uma verificação individual e 256 KB para um lote); corpos grandes demais retornam 413.

6Planos, limites de taxa e cotas diárias

O acesso é medido de duas formas: um limite de taxa por minuto (um teto para picos) e uma cota diária de chamadas que é zerada à meia-noite UTC. Os dois são contados por conta e compartilhados entre todas as suas chaves de API. Você pode testar o endpoint de verificação de spam individual em qualquer plano, mas uma integração real que mexe em regras, configurações, verificações em lote e webhooks precisa do Pro ou superior.

• Free: 100 chamadas/dia, apenas verificação de spam.
• Pro: 10.000 chamadas/dia, API completa e webhooks, mais 1.000 verificações com IA por dia.
• Business: 50.000 chamadas/dia, API completa e webhooks, mais 10.000 verificações com IA por dia.
• Os limites de taxa por minuto também crescem: 60 requisições por minuto no Free, 600 no Pro e 1.800 no Business.
• GET /usage e GET /me nunca contam para a sua cota, então você pode consultar o saldo restante a qualquer momento.

7Tratamento de erros e códigos de status

A API usa códigos de status HTTP padrão com um código de erro legível por máquina no corpo. Faça o seu cliente ler esses códigos e aguardar ou sugerir um upgrade em vez de tentar de novo às cegas.

Quando você ultrapassa a sua cota diária, uma chamada tarifada retorna 429 com o código daily_quota_exceeded, um cabeçalho Retry-After e um corpo com o seu plano, o limite, o número de chamadas usadas, o horário de renovação e uma sugestão de upgrade. Endpoints que exigem um plano superior retornam 403 plan_required com o plano necessário.

• 401: chave de API ausente ou inválida.
• 403 plan_required: o endpoint exige o Pro ou superior.
• 403 insufficient_scope: a chave não tem escopo de escrita para uma chamada que altera dados.
• 429 daily_quota_exceeded ou rate_limit_exceeded: aguarde o horário de renovação ou faça upgrade; respeite o cabeçalho Retry-After.
• Leia os cabeçalhos de resposta X-Quota-* para se antecipar ao limite.

8Boas práticas para uma integração sólida

Alguns hábitos mantêm uma integração confiável e segura à medida que ela cresce.

• Guarde as chaves em um gerenciador de segredos, nunca em código do lado do cliente nem em um repositório git; use uma chave separada por serviço para poder revogar uma sem quebrar as outras.
• Acompanhe os cabeçalhos X-Quota-Used e X-Quota-Limit (ou consulte GET /usage) e reduza o ritmo antes de chegar ao limite, não depois.
• Em um 429, respeite o Retry-After e aguarde; em um 403 plan_required, mostre uma sugestão de upgrade em vez de tentar de novo.
• Para reagir em tempo real, prefira webhooks a consultas periódicas: deixe o Telm enviar os eventos para você.
• Troque as chaves periodicamente, e imediatamente se alguma puder ter vazado.

9Situações de integração comuns

A API serve para muito mais do que moderar mensagens do Telegram.

• Cadastro em sites e apps: passe o texto enviado ou os nomes de usuário por POST /spam/check antes de aceitar um cadastro ou um comentário.
• Os seus próprios bots do Telegram: reutilize a inteligência do Telm em um bot que o Telm não gerencia chamando o endpoint de verificação a partir do seu handler.
• Configuração em massa: aplique por script as mesmas regras, listas de permissões e configurações em dezenas de grupos com os endpoints de configurações e de regras.
• Dados e alertas: registre webhooks para enviar em tempo real os eventos de moderação a um data warehouse, a um painel ou a um canal de alertas.