UTMify
O UTMify é uma plataforma de rastreamento e atribuição de marketing. Com ela, você descobre qual anúncio, campanha ou canal gerou cada venda do seu bot. O Rise Bots possui integração 100% nativa — sem Zapier, Make ou qualquer ferramenta intermediária.
O que o UTMify mostra?
Origem da venda
Qual plataforma (Meta, TikTok, Google) e qual campanha trouxe cada cliente
Criativo que converteu
Qual anúncio específico (vídeo, imagem, copy) gerou a venda
ROI por campanha
Quanto você gastou vs quanto vendeu em cada campanha
Funil de pagamento
PIX gerado, pago e reembolsado — tudo rastreado por origem
Por que usar o UTMify?
Se você investe em anúncios pagos, o UTMify responde a pergunta mais importante: "Qual anúncio está me dando dinheiro?"
Sem rastreamento, você vê apenas o total de vendas. Com o UTMify, você vê:
- Qual campanha gerou cada venda
- Qual criativo (vídeo, imagem, carrossel) converteu
- Qual público está comprando
- O ROI real de cada centavo investido em ads
Isso permite pausar o que não funciona e escalar o que dá resultado — com dados reais, não achismo.
Pré-requisitos
Antes de configurar, você precisa de:
- Conta no UTMify — crie em app.utmify.com.br/register (tem plano gratuito)
- Token de API do UTMify — gerado no painel do UTMify
- Pelo menos um bot ativo no Rise Bots
Como configurar
Crie sua conta no UTMify
Acesse app.utmify.com.br/register e crie uma conta. O UTMify oferece um plano gratuito para começar.
Gere um token de API
No painel do UTMify, vá em Integrações > Webhooks > Credenciais de API > Adicionar Credencial. Copie o token gerado — você vai precisar dele no próximo passo.
Cole o token no Rise Bots
No Rise Bots, vá em Configurações > Integrações e clique em Nova Integração. Selecione UTMify e cole o token de API que você copiou.
Ative a integração
Ligue o switch no card da integração. O sistema faz um envio de teste para validar o token. Se estiver correto, a integração fica ativa (badge "Ativo").
Configure os redirecionadores
Acesse o bot desejado, vá na aba UTM Generator e gere os links com UTMs para as suas plataformas de anúncio. Use esses links como URL de destino nos seus ads.
⚠️ Obrigatório: use os redirecionadores
Para que o rastreamento funcione, o cliente deve acessar o bot através do link redirecionador (/go/{short_id}?utm_source=...). Se o cliente acessar diretamente pelo t.me/SeuBot, os UTMs não serão capturados e a venda aparecerá sem dados de campanha no UTMify.
Como funciona o sistema de redirecionadores
O Rise Bots usa um sistema de links redirecionadores para capturar os parâmetros UTM antes de enviar o cliente para o Telegram. Esse é o mecanismo que conecta o clique no anúncio à venda no UTMify.
A rota /go/{short_id}
Cada bot possui um short_id (código único de 8 caracteres). Ao acessar /go/{short_id}, o sistema:
- Identifica o bot pelo
short_id - Extrai os UTM params da query string (utm_source, utm_campaign, utm_medium, utm_content, utm_term)
- Gera um código de rastreamento (
salesCode) de 8 caracteres aleatórios — ou reutiliza o parâmetrostartse fornecido - Salva na tabela
redirect_clicksobot_id,sales_codee osutm_params - Redireciona o cliente para
https://t.me/{username}?start={salesCode}
Esse código de rastreamento (salesCode) é o elo que conecta o clique no anúncio ao checkout e ao pagamento.
Exemplo prático
Cliente clica no anúncio:
→ https://seusite.com/go/a1b2c3d4?utm_source=facebook&utm_campaign=blackfriday
Sistema salva: { sales_code: "xK9mQ2pL", utm_source: "facebook", utm_campaign: "blackfriday" }
Cliente é redirecionado para:
→ https://t.me/SeuBot?start=xK9mQ2pL
Fluxo completo: do clique à atribuição
Entender o fluxo completo ajuda a diagnosticar problemas e configurar corretamente:
Clique no anúncio
O cliente clica no anúncio. A URL de destino aponta para o redirecionador: /go/{short_id}?utm_source=facebook&utm_campaign=blackfriday&utm_medium=stories&utm_content=video_01
Redirecionamento com captura
O sistema captura os UTMs, gera um salesCode (ex: xK9mQ2pL), salva tudo em redirect_clicks e redireciona o cliente para t.me/SeuBot?start=xK9mQ2pL.
Cliente abre o bot
O Telegram abre o bot com o comando /start xK9mQ2pL. O bot registra esse código de rastreamento associado ao usuário.
Checkout
O cliente abre o checkout (Mini App do Telegram ou loja no browser). O sistema busca os UTMs associados ao salesCode na tabela redirect_clicks e os vincula ao pagamento.
Pagamento processado
Ao gerar o PIX, os UTMs ficam salvos no registro de pagamento (client_payments). A cada mudança de status (pending → paid → refunded), o sistema notifica automaticamente.
Dados enviados ao UTMify
Uma trigger no banco de dados dispara a cada INSERT/UPDATE em client_payments. A edge function notify-utmify formata os dados e envia para a API do UTMify com o token configurado.
Mapeamento de status
O Rise Bots converte automaticamente os status de pagamento para o formato que o UTMify espera:
| Status Rise Bots | Status UTMify | Quando acontece |
|---|---|---|
pending | waiting_payment | PIX gerado, aguardando pagamento |
paid | paid | Pagamento confirmado |
canceled | refunded | Pagamento cancelado |
refunded | refunded | Reembolso realizado |
expired | refused | PIX expirou sem pagamento |
failed | refused | Falha no processamento |
ℹ️ Funil automático no UTMify
O UTMify recebe todos os status automaticamente. Quando um PIX é gerado, ele recebe waiting_payment. Quando o cliente paga, recebe paid com a mesma orderId. Assim o UTMify calcula a taxa de conversão do checkout — quantos PIX gerados se convertem em pagamentos confirmados.
Dados enviados ao UTMify
A cada evento de pagamento, o Rise Bots envia um payload completo para a API do UTMify:
Pedido
| Campo | Descrição |
|---|---|
orderId | ID único do pagamento no Rise Bots |
platform | Sempre "RiseBots" |
paymentMethod | Sempre "pix" |
status | Status convertido (waiting_payment, paid, refunded, refused) |
createdAt | Data/hora de criação do pagamento |
approvedDate | Data/hora da aprovação (apenas quando paid) |
refundedAt | Data/hora do reembolso (apenas quando refunded) |
Cliente
| Campo | Descrição |
|---|---|
name | Nome do usuário no Telegram |
email | Email do cliente (quando fornecido no checkout) |
Produto
| Campo | Descrição |
|---|---|
name | Nome do plano |
priceInCents | Preço do plano em centavos |
quantity | Sempre 1 |
Rastreamento
| Campo | Descrição |
|---|---|
src | Código de rastreamento (salesCode) — conecta o clique ao pagamento |
utm_source | Plataforma de origem (ex: facebook, tiktok, google) |
utm_campaign | Nome ou ID da campanha |
utm_medium | Tipo de mídia ou posicionamento |
utm_content | Criativo ou variação do anúncio |
utm_term | Palavra-chave ou segmentação |
Comissão
| Campo | Descrição |
|---|---|
totalPriceInCents | Valor total do pagamento em centavos |
gatewayFeeInCents | Taxa da plataforma Rise Bots (baseada no plano do vendedor) |
userCommissionInCents | Valor líquido do vendedor |
Verificação: como saber se está funcionando
Depois de configurar, siga estes passos para confirmar que tudo está conectado:
Verifique a integração
Em Configurações > Integrações, confirme que o card do UTMify mostra o badge "Ativo".
Gere um link de teste
Na aba UTM Generator do seu bot, copie o link do Meta Ads (ou qualquer preset). Abra esse link no navegador.
Confirme o redirecionamento
O link deve redirecionar para o Telegram (t.me/SeuBot?start=...). Se redirecionar corretamente, o sistema está capturando os UTMs.
Faça um pagamento de teste
Complete um checkout usando o link gerado. Após o pagamento, verifique no painel do UTMify se a venda aparece com os dados de campanha corretos.
💡 Dica de teste
Se você quer testar rapidamente, use o preset Personalizado na aba UTM Generator e coloque valores simples como utm_source=teste e utm_campaign=verificacao. Assim fica fácil identificar a venda no UTMify.
Avisos importantes
⚠️ Sempre use os redirecionadores
Os UTMs só são capturados quando o cliente acessa pelo link redirecionador (/go/{short_id}?utm_source=...). Links diretos do Telegram (t.me/SeuBot) não carregam UTMs.
⚠️ Não duplique pixels
Se você já usa o UTMify em outra plataforma (Hotmart, Kiwify, etc.), não precisa configurar pixels adicionais no checkout do Rise Bots. A integração nativa já envia todos os dados diretamente para a API do UTMify. Duplicar pode causar contagem dupla de vendas.
ℹ️ Limite de 7 dias
O UTMify aceita apenas pedidos de até 7 dias atrás. Pagamentos mais antigos são rejeitados silenciosamente pela API do UTMify. Por isso, a integração deve estar ativa antes de começar a rodar campanhas.
💡 Integração global
Depois de ativar, todos os bots do usuário já enviam dados automaticamente. Não precisa configurar por bot — uma única integração com um token cobre toda a conta.