Bot do Telegram

O bot do Telegram vende acesso a um canal ou grupo pago: o interessado conversa com o seu bot, escolhe um plano, paga por Pix e recebe o link de convite automaticamente. Quando o plano vence, o bot remove o membro.

TODO(contrato)

O bot é um app novo da migração (MIGRATION-PLAN.md §5, frente F5) e ainda não existe na base Go. O que está descrito aqui vem do inventário do legado (apps/api/src/http/routes/bot/) e do plano de migração — vale como intenção de produto, não como contrato fechado.

Pendente da frente F0 — Contrato: as rotas de gestão do bot (o legado usava /bot, /bots, /bot/:id/members), o formato dos planos e como o token do bot é armazenado.

Como funciona

1. Você cria um bot no Telegram com o @BotFather e copia o token.

2. Cadastra o bot na Avexus, informando o token, o canal de destino e os planos que quer vender.

3. O comprador conversa com o bot, escolhe um plano e recebe o Pix copia-e-cola.

4. O pagamento confirma (o mesmo webhook transaction de qualquer cobrança) e o bot envia um link de convite para o canal.

5. O plano expira no prazo contratado e o bot remove o membro do canal.

Planos

Cada plano tem uma duração fixa:

Plano	Duração
MONTHLY	30 dias
BIMONTHLY	60 dias
QUARTERLY	90 dias
LIFETIME	Vitalício

Além da duração, o plano carrega nome, preço, lista de benefícios, um emoji e a ordem em que aparece no menu do bot.

Cadastrar o bot

POST /bot TODO(contrato)

Campo	Tipo	Descrição
name	string	Nome do bot no seu painel
token	string	Token dado pelo @BotFather. A Avexus valida chamando getMe no Telegram.
id_channel	string	Id do canal/grupo que o bot administra
plans	object[]	Planos vendidos (id, name, price, features, emoji, order)
language	string	PT_BR ou EN_US

POST /bot — cadastrar (contrato provisório)

curl --request POST \
  --url https://api.avexus.app/bot \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "name": "Mentoria Pro",
    "token": "<TOKEN_DO_BOTFATHER>",
    "id_channel": "-1001234567890",
    "language": "PT_BR",
    "plans": [
      {
        "id": "MONTHLY",
        "name": "Mensal",
        "price": 49.90,
        "features": ["Acesso ao canal", "Lives semanais"],
        "emoji": "📅",
        "order": 0
      },
      {
        "id": "LIFETIME",
        "name": "Vitalício",
        "price": 997.00,
        "features": ["Acesso permanente", "Todas as lives"],
        "emoji": "♾️",
        "order": 1
      }
    ]
  }'

O token do bot é segredo

Quem tem o token do bot controla o bot inteiro — pode ler as conversas, mandar mensagens em nome dele e remover membros. Na Avexus ele é cifrado em repouso e mascarado nas respostas da API.

Essa é uma correção explícita em relação ao legado, onde o botToken ficava gravado em claro e era transmitido num broadcast público de WebSocket (MIGRATION-PLAN.md §8). Nada disso volta.

Consultar bots e membros

Método	Endpoint	Descrição
GET	/bots	Lista os seus bots
GET	/bot/{id}	Detalhes de um bot
GET	/bot/{id}/members	Membros ativos e a data de expiração de cada um
GET	/bot/{id}/membership	Situação de um assinante específico
PUT	/bot/{id}/messages	Personaliza as mensagens do bot (boas-vindas, pagamento pendente, pagamento confirmado)

Todas TODO(contrato).

Polling ou webhook

O bot fala com o Telegram de duas formas, atrás da mesma interface (MIGRATION-PLAN.md §4, decisão D2):

Modo	Onde	Por quê
Long polling	Desenvolvimento	Não exige URL pública nem certificado
Webhook	Produção	Menos latência e sem processo consumindo long poll

Isso é configuração da instalação — não muda nada para quem integra pela API.

Veja também

• Cobranças — as vendas do bot aparecem como cobranças normais.
• Receber webhooks — o evento que confirma o pagamento.
• Saldo e extrato — para onde vai o dinheiro das assinaturas.