Como adicionar um sistema de indicações ao seu bot do Telegram em 2 minutos

Um programa de indicações é quando seus usuários trazem novos usuários para você, e você paga por isso. Parece simples. Geralmente termina com um desenvolvedor passando duas semanas escrevendo geração de códigos, uma tabela de saldos, proteção antifraude e um painel de administração de pagamentos — e depois mais um mês consertando tudo isso.

O Graspil já tem tudo isso pronto. Na real são só duas coisas para fazer: conectar seu bot e ativar o programa de indicações. Um minuto para cada — você vai gastar mais tempo lendo este artigo do que configurando.

Por que ter um sistema de indicações

Resumindo: é o canal de aquisição mais barato que existe.

Um indicado chega já com a recomendação de um amigo — a confiança já está embutida, e a conversão em pagamento costuma ser maior.
Você paga por resultado, não por impressão. Nada de «gastei a verba com anúncio e só vieram contas fantasmas».
Indicadores ficam mais tempo: quem trouxe cinco amigos tem uma barreira bem maior para sair do seu bot.
Cresce sozinho. Um usuário feliz → três novos → cada um com seu próprio link.

Óbvio, na real. Vamos em frente.

O que você já tem pronto

Para você ter uma ideia do tamanho da encrenca que não vai precisar programar:

Recurso	O que faz
Códigos e links	Código único e link pronto `t.me/bot?start=...` para cada usuário — gerado pela plataforma
Rastreio de «quem trouxe quem»	O vínculo indicador → indicado é gravado automaticamente no `/start` pelo link
Bots e Mini Apps	Funciona tanto com bots comuns quanto com Telegram Mini Apps — as tags são processadas pelas mesmas regras
Regras de recompensa	Percentual de um pagamento, bônus fixo por indicado, recompensa externa — com condições sobre o valor do evento
Multi-moeda	O saldo é controlado separadamente por moeda, sem conversão forçada
Período de retenção (hold)	O crédito fica «congelado» por N dias — para o caso de reembolsos
Pagamentos	Manual, via webhook, por meios de pagamento populares, ou automaticamente numa agenda
Automação pronta	Uma área do indicador dentro do bot — puxada do catálogo, sem escrever código
Estatísticas	Funil, top indicadores, dinâmica de créditos e pagamentos
Relatórios de indicações	Os dados de indicação ficam disponíveis no criador de relatórios: dá para montar um relatório só dos usuários que vieram do programa de indicações e compará-los com o restante
API flexível	Se os nossos cenários prontos não servirem — códigos, créditos, saldos e pagamentos estão disponíveis via API, para você montar sua própria lógica

E o mais importante: dá para conectar o sistema de indicações do Graspil mesmo que você já tenha o seu. Nesse caso ele roda no modo observação e só fornece análise, sem mexer na sua lógica atual.

Conectando o bot

Se o bot já está no Graspil — pule esta seção.

Existem quatro formas de conectar, mas para o nosso caso a mais simples já resolve:

Conexão automática (MTProto). Cole o token do bot e o sistema cuida do resto. Funciona com qualquer bot ou construtor no-code, nada para mudar no seu código, e coleta um pouco mais de dados que os outros métodos.

Não quer entregar o token? Tem a conexão via API: uma única requisição HTTP do seu bot que nos envia as atualizações. Uns cinco minutos de trabalho de um desenvolvedor, mas o token fica com você.

Primeiro, resolva o parâmetro start

Esse é o único ponto que vale a pena parar para pensar. É a única etapa em que você pode se ferrar e ter que refazer tudo depois.

O que é o parâmetro start

O Telegram dá exatamente uma forma de passar dados para um bot na inicialização — um deep link:

https://t.me/SeuBot?start=SEUS_DADOS_AQUI

Uma string, 64 caracteres no máximo. Só isso. As suas tags UTM e o seu código de indicação precisam passar por essa mesma porta estreita.

Desligue o modo simples

Por padrão, todo bot novo vem com o modo simples ativado para o processamento do start. Ele pega o conteúdo do parâmetro do jeito que está, inteiro, num bloco só:

start=	Parâmetro	Valor
`docs`	nenhum	`docs`

Para um sistema de indicações, isso significa que todo o valor de start é tratado como o código de indicação. Sem UTM, sem origem, sem campanha — só o código. Alguém abre ?start=kT7xQm2p vindo de um canal do Telegram, e você vai saber quem indicou, mas não vai ter ideia de onde essa pessoa veio de verdade.

Então: vá em «Meus bots» → o bot em questão → «Tags UTM» (regras de processamento do start) e desligue o modo simples.

Defina o formato dos links com antecedência

O modo completo interpreta a string usando dois separadores: um separador de parâmetros (divide a string em pares) e um separador de valores (divide cada par em chave e valor).

Por exemplo, com _ como separador de parâmetros e - como separador de valores, a string

?start=ref-kT7xQm2p_source-tgchannel

é interpretada numa tabela limpa:

Parâmetro	Valor
ref	kT7xQm2p
source	tgchannel

Ou seja, um único link carrega tanto o código de indicação quanto uma tag UTM de origem. Depois, nos relatórios, você vai poder dizer não só «o João trouxe 40 pessoas», mas «o João trouxe 40 pessoas, 30 do canal dele e 10 de DM».

Três coisas para decidir antes de lançar o programa, não depois:

Qual parâmetro carrega o código de indicação. ref por padrão — mantenha, a menos que tenha um motivo para mudar. São permitidas letras latinas, números e _.
Quais separadores usar. Lembre-se do limite de 64 caracteres: separadores longos e chiques comem o espaço disponível para os dados de verdade.
Quais tags UTM vão junto com o código de indicação. Geralmente source já basta.

💡 A página de regras tem uma prévia ao vivo: digite exemplos dos seus links e veja na hora como o sistema vai interpretá-los. Não pule essa etapa — você não vai querer redesenhar o formato dos links depois que já estiverem na mão de mil usuários.

Se o modo simples ainda estiver ligado, o Graspil vai avisar bem na tela de ativação do programa de indicações. A gente tentou cobrir isso para você.

Ativando o sistema de indicações

Procure a seção «Programa de indicações» no seu painel. Vem desligado por padrão — clique em ativar.

Escolha um modo

Manage (gestão). A plataforma gera os códigos e links sozinha, calcula os créditos, controla os saldos e roda os pagamentos. Escolha esse modo se você ainda não tem um programa de indicações — ele dá acesso a todos os recursos e não exige código do seu lado.

Observe (observação). A gente só observa quais códigos chegam via ?start=, e registra as transições e o vínculo «quem trouxe quem». Seu bot gera os códigos, e não há créditos. Escolha esse modo se você já tem seu próprio sistema de indicações e só quer análise por cima dele.

O modo pode ser mudado nas configurações a qualquer momento, e o histórico acumulado de transições é preservado. Então, se estiver em dúvida, comece com Observe e mude depois.

Um detalhe: para o sistema conseguir calcular recompensas, ele precisa saber quem é dono de um código. No modo manage isso acontece automaticamente. No modo observe, são três caminhos:

ativar a opção «O valor do parâmetro é o Telegram ID do indicador» e colocar no link o próprio Telegram ID do indicador, em vez de um código — assim o dono da transição é conhecido na hora, sem camada de mapeamento código-para-usuário;
informar a propriedade dos códigos em lote via API POST /v1/referral/set-code-owners — funciona tanto antecipadamente quanto retroativamente (todas as transições passadas daquele código são recalculadas para o indicador);
marcar diretamente um usuário como indicado via POST /v1/referral/mark-referral.

Demais configurações de ativação

Nome do parâmetro start — aquele que definimos acima. Tem uma prévia ao vivo do link de indicação logo ali também.
Quando registrar um indicado — no primeiro lançamento do bot (o caso principal) e/ou em reinícios e retornos após bloqueio.

Clique em «Ativar programa» e o menu se expande em subseções: Visão geral, Configurações, Indicadores, Indicados, Créditos, Pagamentos, Estatísticas.

Bônus: uma área do indicador sem escrever código

O sistema de indicações sabe contar dinheiro direitinho, mas você ainda precisa mostrar isso para os usuários de alguma forma. E é aí que geralmente começa o «vamos programar um comando /me».

Não precisa. Abra o catálogo de automações e pegue o modelo pronto «Área do indicador».

O que ele faz de fábrica:

Dispara em um evento que você escolher — um comando /me ou /balance, por exemplo.
Busca o código e o link do indicador («Obter código e link») — cria um se ainda não existir.
Puxa o saldo («Obter saldo») — disponível, em retenção, pago.
Envia ao usuário uma mensagem mais ou menos assim:

🎁 Sua área do indicador

🔗 Código: kT7xQm2p
Link: https://t.me/SeuBot?start=kT7xQm2p

👥 Indicados: 12
💰 Disponível para saque: 1400

Abaixo da mensagem — um botão «Solicitar saque» que continua o fluxo, chama «Solicitar saque», e responde com uma confirmação.

Depois de importar, só falta uma coisa: escolher o evento gatilho e publicar. O botão de saque se conecta ao seu bot automaticamente.

Daqui para frente, dá para ajustar o modelo como qualquer outra automação: adicionar uma etapa «Registrar indicador» na mensagem de boas-vindas, colocar uma condição para só mostrar o botão de saque quando o saldo estiver acima de zero, conectar textos multi-idioma — o seletor de idioma dentro do bloco de mensagem funciona aqui também.

Por que pagar e como pagar

Essa é a parte mais densa, mas também é feita toda no clique.

Regras de recompensa

Configurações → Regras de recompensa. Existem predefinições — % dos pagamentos, Fixo por indicado, Estender serviço, Campo personalizado — pegue uma pronta e ajuste.

Uma regra se lê como uma frase: para qual evento → quanto creditar → o que mais fazer.

Para qual evento. Qualquer evento do seu bot que a plataforma já conheça: um pagamento, um cadastro, a conclusão de uma etapa. A mesma lista usada nos relatórios.

Condições extras sobre o valor do evento. Um filtro numérico: creditar somente se value ≥ value_min, ≤ value_max, ou = value_eq. O clássico: «10% dos pagamentos, mas só para pedidos acima de 1000».

Quanto creditar — três tipos de recompensa:

Tipo	Como é calculado
Fixo	Um valor fixo na moeda escolhida — 100 moedas por pagamento de indicado
Percentual	Um percentual do valor do evento. A moeda é herdada do próprio evento, não precisa escolher
Externa	A plataforma não calcula nenhum valor, só dispara o seu webhook. Para casos como «estender a assinatura por 7 dias» — nada medido em dinheiro

Janela de retenção (hold), em dias. Quanto tempo um crédito fica «em retenção» antes de ficar disponível para saque. Se você oferece reembolso em 14 dias, coloque 14 e durma tranquilo.

Efeitos — o que mais fazer quando um crédito acontece:

Webhook — um POST para sua URL com corpo em modelo e substituição de variáveis: {{referrer_id}}, {{amount}}, {{event_value}} e outras.
Campo personalizado — incrementar (inc) ou definir (set) um campo personalizado no perfil do indicador. Útil se você quiser manter um saldo acumulado direto no perfil do usuário e usá-lo em segmentos de disparo em massa.

Prioridade. Mais de uma regra pode valer para o mesmo evento — taxas diferentes para tamanhos de pedido diferentes, por exemplo. As regras se aplicam em ordem crescente de prioridade; arraste para reordenar.

Pagamentos

Configurações → Pagamentos.

Manual. Você transfere o dinheiro do jeito que for conveniente, e depois marca o pagamento como «Pago» ou «Falhou» (com um comentário) no sistema. A plataforma mantém o registro, você mantém a carteira.

Webhook. Quando um pagamento é disparado, enviamos um POST para sua URL no estilo «creditar X na moeda Y para o usuário Z». Seu servidor credita e retorna 2xx — o pagamento é marcado como pago. Retorne um external_ref e vamos guardá-lo como seu ID de transação para conciliação. Bom encaixe se você tem uma carteira própria ou seu próprio sistema de pagamento.

Provedores de pagamento. Pagamentos por serviços populares de pagamento e criptomoeda se conectam como um método separado — confira a lista atual nas configurações de pagamento.

🛠 Não achou o provedor que precisa? Escreva para o suporte. A gente adiciona em até 24 horas.

Pagamentos automáticos — um mecanismo à parte, ativado por uma opção: agenda (mensal ou a cada N dias), método padrão, e limites por moeda («só pagar se houver ≥ 5000 R$ disponíveis»). Pagamentos manuais e via API sempre funcionam, independente da agenda.

Você pode disparar um pagamento a partir do card do indicador, da seção Pagamentos, via API POST /v1/referral/payout, ou com um botão dentro de uma automação.

Ciclo de vida:

Solicitado → Em processamento → Concluído
                              ↘ Falhou (o valor volta para o saldo)

O que acontece com o saldo

O saldo é controlado separadamente por moeda e composto de quatro partes:

O quê	Significado
Disponível	Créditos aprovados não vinculados a um pagamento. Pode ser sacado agora mesmo
Reservado	Já incluído em um pagamento que está em andamento
Em retenção	O período de retenção ainda não passou
Pago	Total de todos os pagamentos bem-sucedidos

Um crédito percorre a rota: Em retenção → Aprovado → Em pagamento → Pago, com ramificações para Estornado (um crédito compensatório) e Cancelado.

Conferindo os resultados

Visão geral — um resumo de 30 dias: total de indicadores, indicados trazidos, regras ativas, créditos; saldos por moeda; um funil de «novos usuários → evento gatilho → créditos → pagamentos»; dinâmica dia a dia; top 5 por ganhos e por número de indicados.

Indicadores — uma lista com filtros (período, moeda, «tem saldo disponível», mínimo de indicados), ordenável por ganhos, com exportação. No card do indicador: o link dele e um botão de saque.

Créditos e Pagamentos — um livro-razão completo com status. Cada unidade monetária é contabilizada, e se algo der errado, dá para ver exatamente o quê.

Mas a parte interessante começa aqui. Cada crédito é gravado na análise como seu próprio evento, e os dados de indicação mais as tags UTM do parâmetro start estão disponíveis no criador de relatórios. Isso significa que você pode montar mais do que só «quanto a gente distribuiu» — relatórios de produto de verdade:

Coortes de indicados vs. todo mundo — a retenção de usuários indicados quase sempre é maior, e é bom ver isso em números.
Funil por origem do link de indicação — se você separou ref e source em parâmetros diferentes (como comentamos antes), dá para ver de quais canais seus indicadores realmente trazem usuários pagantes, e quais só trazem tráfego.
Economia do programa — quanta receita os indicados geraram versus quanto você pagou aos indicadores para consegui-los. Dá para aumentar ou diminuir a taxa de uma regra com base nisso, em vez de achismo.
Tendências por regra — qual regra realmente está valendo a pena, e qual só está dando dinheiro de graça.

E se um dia quisermos migrar para o nosso próprio sistema ou outro?

Uma pergunta justa, e vale a pena fazer a qualquer serviço antes de entregar seu programa de indicações a ele. Resposta honesta: dá para sair, e seus dados saem com você.

Tudo que o sistema acumulou fica disponível via API:

Códigos e seus donos — qual usuário é dono de qual código.
Indicados — quem trouxe quem, lista completa.
Créditos — o livro-razão inteiro, com valores, moedas, status e qual regra disparou cada um.
Saldos — disponível, em retenção, pago, por moeda.
Histórico de pagamentos — o quê, quando, por qual método, e com qual ID de transação externo.

Mais uma exportação de indicadores direto pela interface.

Ou seja, exportar tudo e carregar no seu próprio banco é um script de uma noite, não uma negociação com o suporte. A gente não coloca nenhum cadeado nos seus dados: se o Graspil um dia deixar de fazer sentido para você, você sai com todo o histórico do seu programa intacto. É assim que deveria funcionar, no fim das contas.

Resumindo

A checklist inteira cabe em seis passos:

Conectou o bot com um token.
Desligou o modo simples de processamento do start e definiu um formato de link.
Ativou o programa de indicações no modo manage.
Criou uma regra de recompensa.
Escolheu um método de pagamento.
Importou a «Área do indicador» do catálogo de automações.

O único passo que vale a pena gastar um tempo de verdade é o segundo. Refazer o formato de link dói; todo o resto muda nas configurações a qualquer momento.

Ainda tem dúvidas sobre a configuração, ou precisa de um método de pagamento que ainda não existe — escreva para o suporte.

Como adicionar um sistema de indicações ao seu bot em 2 minutos