Bots do Telegram e Stars: Guia de Ações Pagas

Se um criador já tem uma audiência no Telegram, um bot pode transformar essa audiência em ações pagas: um relatório, um arquivo, um pacote de créditos, um comando privado, um mini-serviço ou um desbloqueio relacionado a mídia.

A parte estranha não é o botão. É o repasse. O comprador precisa de Stars suficientes, o bot precisa de uma fatura limpa e a ação paga deve desbloquear apenas depois que o Telegram confirma o pagamento.

Este guia é para criadores e operadores que planejam uma ação paga entregue por bot com Telegram Stars. Se seus leitores ainda são novatos no saldo em si, comece com o que são as Telegram Stars. Se os compradores precisam de Stars antes do lançamento, envie-os para recarregar Telegram Stars antes de o aviso do bot entrar no ar.

Resposta rápida

Uma ação paga de bot do Telegram funciona melhor quando você mantém a oferta pequena e verificável.

Use este fluxo:

1. Defina uma única ação paga.
2. Mostre ao comprador o que ele vai receber.
3. Envie uma fatura em Stars para essa ação.
4. Cheque a solicitação de pre-checkout antes de aceitar o pagamento.
5. Entregue apenas após um evento de pagamento bem-sucedido.
6. Guarde a referência do pagamento para que suporte e reembolsos não sejam adivinhação.
7. Diga aos compradores como conseguir Stars antes do momento do desbloqueio.

A documentação de pagamentos com Stars do Telegram descreve a sequência básica da fatura para bens e serviços digitais: sendInvoice, pre_checkout_query, answerPreCheckoutQuery, successful_payment e então a entrega. A Bot API usa XTR como tag de moeda das Stars para esses pagamentos.

Essa é a espinha técnica. O trabalho do criador é mais simples: tornar a ação paga clara o bastante para que o comprador saiba por que está gastando Stars.

O que este guia cobre

Use este guia para ações pagas entregues por bot, como:

• desbloquear um arquivo para download;
• gerar um relatório privado;
• adicionar créditos a uma conta de bot;
• abrir um comando pago;
• entregar uma checklist, um pacote de prompts, um gráfico ou um modelo personalizados;
• dar acesso a um serviço pontual tratado por um bot.

Não misture isso com todo fluxo de Telegram Stars.

Mídia paga é para fotos, vídeos e desbloqueios de mídia suportados. Se o seu produto é um drop de mídia, leia o guia do comprador de mídia paga do Telegram e o guia sobre como precificar mídia paga do Telegram com Stars.

As Assinaturas Star restringem o acesso a um canal por meio de um link de convite pago com mensalidade. Mini apps também podem usar Stars, mas o fluxo do comprador é diferente. Se for o caso, use o guia sobre como pagar mini apps do Telegram com Stars.

Se você precisa primeiro do mapa mais amplo, comece com como monetizar conteúdo do Telegram com Stars.

Passo 1: defina a ação paga

Não comece pela fatura. Comece pela coisa que o comprador recebe.

Promessas fracas de ação paga soam assim:

• "Acesso premium."
• "Desbloqueie mais."
• "Apoie o bot."
• "Ganhe conteúdo extra."

Essas frases criam dúvidas de suporte porque o comprador não consegue dizer o que muda após o pagamento.

Uma promessa de ação paga mais forte é específica:

• "Gere um relatório de auditoria privado."
• "Desbloqueie o pacote completo de modelos em PDF."
• "Adicione 50 créditos ao saldo do seu bot."
• "Execute o comando avançado de gráficos uma vez."
• "Abra a checklist privada desta aula."

Antes de precificar qualquer coisa, escreva uma frase:

Após pagar, o comprador recebe ________.

Se a frase for vaga, o fluxo do bot também vai parecer vago.

Passo 2: envie a fatura em Stars

Para uma fatura de bot padrão, o método da Bot API do Telegram é sendInvoice. Para pagamentos em Stars, a fatura usa a tag de moeda XTR.

Uma checklist prática para a fatura:

• use currency como XTR;
• mantenha o token de provedor vazio para pagamentos em Stars onde a documentação do Telegram permitir;
• use um único item de preço para um pagamento em Stars;
• coloque sua referência interna do pedido no payload;
• mantenha o título e a descrição curtos o bastante para o comprador reconhecer a ação;
• não reutilize o mesmo payload para ações não relacionadas.

O payload importa porque a tela de pagamento não é todo o seu sistema de pedidos. Seu bot ainda precisa saber a qual usuário, ação e preço esta fatura pertence.

Bons dados de payload interno geralmente incluem:

• o ID do usuário comprador;
• o ID da ação paga;
• o valor esperado de Stars;
• o timestamp do pedido;
• um nonce ou ID de pedido único;
• um status como created, pending, paid, delivered ou refunded.

Mantenha o texto público da fatura humano. O comprador não deveria ver IDs internos ou linguagem de desenvolvedor.

Título de fatura ruim:

SKU_XTR_CMD_ADV_2026

Título de fatura melhor:

Relatório de gráfico avançado

Descrição de fatura ruim:

Executar ação paga após validação de callback.

Descrição de fatura melhor:

Desbloqueie um relatório privado de gráfico deste bot.

Passo 3: trate o pre-checkout como uma proteção

O Telegram envia uma solicitação de pre-checkout antes de o pagamento ser concluído. Trate isso como uma checagem de segurança final, não como uma formalidade.

Antes de aprovar, confirme que:

• o usuário ainda corresponde ao pedido;
• a ação paga ainda existe;
• o valor esperado de Stars ainda confere;
• a ação ainda está disponível;
• o pedido ainda não foi pago nem cancelado;
• o payload não expirou.

Se algo não conferir, rejeite a solicitação de pre-checkout com uma mensagem de erro clara. Não deixe uma fatura desatualizada desbloquear a ação errada.

Isso é especialmente importante para bots que vendem itens limitados, acesso por tempo ou resultados gerados. Um usuário pode tocar em um link de fatura antigo depois que a oferta mudou. Seu bot deve saber o que fazer.

Passo 4: entregue apenas após o sucesso

Um toque no botão não é pagamento. Uma aprovação de pre-checkout não é entrega. Entregue depois que o Telegram enviar o evento de pagamento bem-sucedido.

Um fluxo de entrega limpo é assim:

1. Receba successful_payment.
2. Combine-o com o pedido interno.
3. Guarde o ID da cobrança do pagamento do Telegram.
4. Marque o pedido como pago.
5. Entregue a ação paga.
6. Marque o pedido como entregue.
7. Envie uma mensagem curta de confirmação ao comprador.

Se a ação paga é instantânea, como um arquivo ou pacote de créditos, a entrega pode acontecer logo após a confirmação. Se ela exige processamento, diga ao comprador o que está acontecendo e o que esperar em seguida.

Mantenha o suporte prático. Se você guarda o ID do pedido, a ação paga, o valor de Stars, o ID da cobrança do pagamento e o status da entrega, consegue responder à maioria das dúvidas de suporte sem vasculhar o histórico de conversa.

Passo 5: deixe óbvio o momento de recarga do comprador

O lado do comprador é fácil de esquecer. Os criadores costumam testar o bot quando já têm Stars. Compradores reais podem chegar com saldo zerado.

A documentação de pagamentos com Stars do Telegram diz que os usuários podem adquirir Stars se necessário antes de pagar por bens e serviços digitais. Isso não significa que o passo extra seja sem atrito para todo comprador. Se sua ação paga é lançada em um horário específico, avise a audiência cedo.

Uma mensagem de lançamento simples pode dizer:

O bot vai desbloquear o relatório pago com Telegram Stars. Se você ainda não tem Stars suficientes, recarregue antes do lançamento para não fazer isso durante o checkout.

É aqui que a MyStars se encaixa naturalmente. O criador não precisa tirar o comprador do Telegram para a ação paga em si. Ele só precisa que os compradores tenham Stars prontas antes do momento do desbloqueio. Envie os compradores para recarregar Telegram Stars antes do drop, não depois que já estão frustrados.

Se você também faz drops de mídia paga, use o plano de lançamento de mídia paga para agendar teasers, lembretes ao comprador e a medição pós-lançamento.

Ramos de decisão

Se o valor pago é um arquivo ou modelo

Mantenha o pagamento único. Entregue o arquivo após o pagamento bem-sucedido e depois envie uma mensagem curta em estilo de recibo.

Não faça o comprador pedir o arquivo a um administrador manualmente. Isso transforma um fluxo de bot em uma fila de suporte.

Se o valor pago é um relatório gerado

Diga ao comprador se o relatório é instantâneo ou fica na fila.

Se a geração pode falhar, separe a confirmação do pagamento do status de entrega:

• pago, gerando;
• pago, entregue;
• pago, falhou - precisa de suporte.

Isso facilita reembolsos e suporte.

Se o valor pago são créditos

Adicione créditos apenas após o pagamento bem-sucedido. Mostre o novo saldo imediatamente.

Se os créditos expiram, diga isso antes do checkout. Regras de expiração ocultas geram reclamações.

Se o valor pago é mídia

Use o fluxo certo. Uma fatura de bot pode vender um bem ou serviço digital, mas a mídia paga tem seu próprio método da Bot API e comportamento de produto. Se você está vendendo um desbloqueio de foto/vídeo/mídia, compare o fluxo com o guia do comprador de mídia paga do Telegram antes de construir.

Se o valor pago é acesso a um canal

Isso pode ser uma Assinatura Star ou outro fluxo de acesso, não uma ação de bot única. Mantenha acesso mensal, ações pagas pontuais e mídia paga separados no seu texto.

Erros a evitar

• Vender uma vaga promessa premium sem dizer o que desbloqueia.
• Tratar um toque no botão como pagamento.
• Entregar após o pre-checkout em vez de após o pagamento bem-sucedido.
• Esquecer de guardar o ID da cobrança do pagamento do Telegram.
• Reutilizar um formato de payload para ações não relacionadas.
• Deixar links de fatura antigos desbloquearem ofertas que mudaram.
• Esconder expiração ou limites de uso até depois do pagamento.
• Usar rótulos de desenvolvedor no texto da fatura visível ao comprador.
• Mandar os compradores recarregarem só depois que o lançamento já começou.
• Chamar todo fluxo de Stars de posts pagos, o que pode confundir mídia paga, assinaturas, faturas de bot e conteúdo de canal só de texto.

Solução de problemas

O comprador diz que pagou, mas o bot não desbloqueou

Causas prováveis:

• o bot não recebeu ou não processou successful_payment;
• o ID do pedido interno não combinou com o payload;
• a entrega falhou após o pagamento;
• o bot marcou o pedido como pago, mas não como entregue.

Correção:

• pesquise por ID de usuário e ID de pedido;
• verifique o ID da cobrança do pagamento guardado;
• confira o status da ação paga;
• entregue manualmente se o pagamento foi concluído e o item é válido;
• registre a falha para que o mesmo bug não se repita.

O comprador não consegue pagar porque não tem Stars

Causa provável:

• o comprador chegou ao momento do pagamento sem Stars suficientes prontas.

Correção:

• adicione um lembrete pré-lançamento;
• inclua um link recarregar Telegram Stars nas instruções de lançamento;
• mantenha a mensagem de pagamento do bot curta e clara;
• não enterre a orientação de recarga dentro de um anúncio longo.

O pre-checkout falha

Causas prováveis:

• o pedido expirou;
• o payload está malformado;
• o valor esperado mudou;
• a ação paga não está mais disponível;
• o bot já processou o pedido.

Correção:

• retorne uma mensagem de erro clara;
• deixe o usuário criar uma nova fatura;
• evite falhar em silêncio sem explicação.

Chega um pedido de reembolso ou suporte

Causas prováveis:

• o comprador pagou pela ação errada;
• a entrega falhou;
• o texto da oferta não estava claro;
• o comprador esperava uma assinatura ou desbloqueio de mídia, mas comprou uma ação de bot.

Correção:

• verifique o ID da cobrança do pagamento e o log de entrega;
• decida se um reembolso é adequado segundo sua política e os métodos disponíveis do Telegram;
• reescreva a oferta se vários compradores entendem mal o mesmo ponto.

Perguntas frequentes

Um bot do Telegram pode aceitar Stars por uma ação paga?

Sim, a documentação de pagamentos com Stars do Telegram cobre bens e serviços digitais vendidos por bots e mini apps. Numa fatura de bot, o importante é a tag de moeda XTR, o tratamento do pre-checkout, a confirmação do pagamento bem-sucedido e a entrega após o pagamento.

O que significa XTR?

XTR é a tag de moeda que o Telegram usa para Stars no fluxo de pagamentos da Bot API. Use-a para faturas em Stars em vez de tratar as Stars como um código de moeda fiduciária normal.

Faturas em Stars precisam de um token de provedor de pagamento?

A documentação da Bot API do Telegram diz para passar um token de provedor vazio nos pagamentos em Telegram Stars onde esse parâmetro aparece. Confira a documentação atual da Bot API antes de implementar, pois os detalhes da API podem mudar.

Quando o bot deve entregar a ação?

Após o evento de pagamento bem-sucedido, não depois de o usuário tocar no botão de pagar e não apenas após a aprovação do pre-checkout.

E se o comprador não tiver Stars suficientes?

Avise os compradores antes do lançamento. Eles podem preparar o saldo primeiro e depois desbloquear dentro do Telegram quando a fatura do bot aparecer. Se precisarem de mais Stars, envie-os para recarregar Telegram Stars.

Uma ação paga de bot é o mesmo que mídia paga?

Não. Mídia paga é para fotos, vídeos e desbloqueios de mídia suportados. Uma ação paga de bot pode ser um arquivo, relatório, pacote de créditos, comando ou serviço entregue pelo bot. Mantenha o fluxo e o texto separados.

Pagamentos com Stars podem ser reembolsados?

A Bot API do Telegram inclui refundStarPayment para pagamentos em Stars bem-sucedidos. Guarde o ID da cobrança do pagamento e o status interno do pedido para lidar com suporte e decisões de reembolso com clareza.

Fontes e evidências

• Lançamento das Telegram Stars: Telegram Stars: Pay for Digital Goods and More.
• Fluxo de pagamentos com Stars para bots: Telegram Stars Payments.
• Parâmetros da fatura de bot: Bot API sendInvoice.
• Escopo da mídia paga: Bot API sendPaidMedia.
• Anúncio de Assinaturas Star e mídia paga: Telegram Super Channels, Star Reactions and Subscriptions.
• Termos das Stars e escopo do saldo: Telegram Stars Terms.

Checklist final

Antes de lançar uma ação paga de bot:

• a ação paga é específica;
• o título da fatura é legível por humanos;
• o payload mapeia para um único pedido interno;
• o valor de Stars é checado antes do pagamento;
• a entrega acontece após o pagamento bem-sucedido;
• o suporte consegue encontrar o ID da cobrança e o status da entrega;
• os compradores sabem como recarregar Stars antes do aviso do bot.