Telegram Stars: what is that and how does it work with no-code | Directual blog (2024)

The ultimate payment system is here—Telegram Stars! A no-coder’s paradise, especially if you build stuff on Directual in the first place. Decentralized, accessible, and already widely used all over the world. Build it, rake in the cash—what’s not to like?

This article is there for the unfamiliar or the fence-sitters. See what Telegram Stars are, how they fit into Telegram Mini Apps, and how it all ties together with no-code.

Telegram Stars: what’s that?

Okay, let’s cut to the chase: hundreds of millions of users are messing around with bots and mini apps on Telegram every single month. They’re buying stuff, getting services, playing games—you name it. Now, Telegram's latest update lets these bots and mini apps hawk digital goods and services too.

It’s not new for businesses to sell physical stuff on Telegram through these bots and apps, but now they can push digital products as well. This means everything from e-books to online courses and game items can be sold directly on Telegram.

Telegram Stars—digital cash you buy within the app, and now they’re letting you pay for all these digital goods. You can grab these Stars through stuff like Apple, Google, or this PremiumBot thing, then blow them on whatever digital goodies you want.

These Stars go well with Apple and Google rules, so developers and users get easier access to in-app purchases right from their phones. Also, developers will soon be able to cash out their Stars for Toncoins via something called Fragment.

Try it out: @directual_stars_bot is where you can give some tips to the Directual team! Below, we'll unveil the details of how this bot operates on our platform.

Some more facts as to why it’s worthwhile to use Telegram Stars:

• If you’re buying physical items, it’s business as usual with Telegram's usual payment methods.
• Easy, fast payments—now even more types of businesses can jump into Telegram and reach a whopping 900 million potential customers.
• Telegram is planning to add more features like gifts for content creators.

And here’s the pricing:

All of this can be brought together with no-code on Directual. That's right, even if you can’t code your way out of a paper bag, you can still build this stuff on Directual and get it running on Telegram. More reach, more sales, less hassle.

How does the API work?

Telegram Bot Payments let sellers take payments for stuff directly from Telegram users, all for free.

Here’s the lowdown:

Telegram Payments are designed right into the app, so you can trade digital goods and services for Telegram Stars, which you can turn into rewards later.

How this works:

You set up a bot to sell digital goods and services. Your bot can pop invoices into chats, groups, or channels. If you've got inline mode, your bot can even send bills to other chats, like directly to someone else.

Invoices come with a photo, a description, and a big ‘Pay’ button. Hitting that button opens a special payment screen right in the app.

Since it’s all digital, all transactions go through in Telegram Stars. Users buy these Stars through regular in-app purchases or via @PremiumBot, and then use them to buy your digital stuff.

The payment part is super smooth – no need for personal info like full names, addresses, or credit card numbers.

Step-by-step, as explained by Telegram’s own docs

To get started taking payments, you need a Telegram bot. Create one using @BotFather if you haven't yet.

Basically, here's what you'll do:

• Send a bill with sendInvoice (currency: “XTR”)
• Wait for an Update showing pre_checkout_query
• Approve or nix the purchase with answerPreCheckoutQuery
• Wait for another Update showing successful_payment
• Keep the SuccessfulPayment’s telegram_payment_charge_id—might need it for refunds
• Hand over the digital goods or services the user bought

Note: for digital stuff, you won’t need a provider_token. That’s just for physical goods.

You can mess around with payments in Telegram Stars using Telegram’s test environment. Make sure you pick the right parameters depending on what you're selling.

1. Create invoice: the user hits up @yourbotname (for the sake of the exercise, not a real name) wanting to buy something. Your bot whips up an invoice with what’s being bought and the cost in Telegram Stars. You can create an invoice in two ways:some text
   1. Bot invoice: use sendInvoice to make and send an invoice to a chat. No need for a provider_token if it’s for digital goods.
   2. Inline invoice: if @yourbotname does inline stuff, use inputInvoiceMessageContent so users can spread your invoices in their chats.
2. Choose forwarding behavior: how you handle invoices that get forwarded depends on the start_parameter in the sendInvoice method:some text
   1. Multi-chat invoice: forwarded copies can still be paid from.
   2. Single-chat invoice: payment only from the original chat, forwarded copies get a URL button linking back to the bot.

Switch “Pay from Forwards” on or off when making invoices with @ShopBot to see the difference.

3. Pre-checkout: the user buys Stars if needed, then smacks the pay button. The Bot API then sends a pre_checkout_query Update to your bot. Your bot has to respond with answerPrecheckoutQuery within 10 seconds, or the deal’s off. You can throw in an error message if there’s a snag.

4. Checkout: if the order and payment are good, the API sends a successful_payment message. Your bot should then deliver whatever the user bought.

Make sure you get that successful_payment update before you give out the goods—just replying to a pre_checkout_query isn’t enough to seal the deal.

If the invoice was in a chat with @yourbotname, it shows up as a Receipt for the user—they can check it anytime to see their transaction details. If it was sent to a different chat, the Pay button stays active, and it’s up to the merchant bot to decide if it'll take more payments.

Live checklist

Before you let your merchant bot loose, make sure to check off these points:

• Seriously consider turning on 2-step verification for the Telegram account running your bot.
• Remember, if stuff goes sideways with transactions, it’s on you. Be ready to handle any disputes or chargebacks.
• Don’t let things get messy. Have your bot spit out your Terms and Conditions when someone types /terms or something similar. Make those terms clear and make sure users get it—they need to agree before they buy.
• Your bot better have a way to deal with customer issues. Set it up so users can hit up a /support command or another obvious method to get help. Be quick about handling their concerns and tell them straight up that Telegram won't sort out their bot purchase problems.
• Double-check your server gear and software. Use backups, so you don’t end up losing any payment data.
• Finally, make sure you’ve read and agreed to Telegram’s Terms of Service and the Bot Platform Developer Terms. You gotta play by the rules.

And that’s the gist of it on the Telegram side. Now let’s talk Directual side!

Building Telegram bots on Directual

Simple!

Assuming you’ve already got a Telegram bot up and running, here’s how to hook it up with Directual.

• First off, head to the Plugins section in the Directual app, pick Telegram, slap in that secret token you saved earlier, and get the plugin installed.
• Next, navigate to the Database section and dig up the Integrations/Telegram folder (it pops up on its own).
• You’ll spot 5 data structures hanging out there: Incoming Telegram messages, Outgoing Telegram messages, Users Telegram, Chats Telegram, and Keyboards Telegram (Legacy).
• You’ll also see that a webhook for snagging Telegram messages is in place, and a new System scenario called "Parse incoming telegram messages" is set up (leave that one alone!).
• Now, let’s give this integration a whirl and poke around the TMessageIn structure. Fire off a text, picture, file, or your location to the bot and see what lands in TMessageIn.
• You’ll find new entries in TMessageIn, like the "text" field for text messages (which holds the message content), plus bits for images, files, and locations stored as Telegram file IDs.
• To wrap this up, let’s whip up a simple scenario that gets new objects popping up in TMessageIn. Create a new scenario, drop a Telegram step in it, tweak the settings (and remember to publish and run your scenario).

And that’s pretty much it! For the bot part, anyways.

Configuring workflow for working with Telegram Stars

Step 1. Sending an invoice

Use the Telegram step in “Professional mode”, call the method sendInvoice, specifying the details in the body: description, title, prices and currency = XTR (the code of Telegram Stars).

Step 2. Catching pre-checkout-query

When a user pays, Telegram sends a specific request with pre_checkout_query parameter. We need to catch that request and response calling answerPreCheckoutQuery method, approving the transaction.

And that is it! Anyone can build the same on Directual. Moreover, the upcoming Telegram plugin update will make the process super-easy.

Integrating Telegram Mini Apps with Directual

Also simple.

Step 1. Grab the free TMA plugin from the Marketplace in your Directual app!

Here are the two ways you can tweak the TMA plugin settings:

Auto log in. Set to True: it logs users in automatically when they open TMA. Set to False: users have to hit "Log in with Telegram" to get in. Use False if you're letting users log in with other methods like email or Google.

Disable registration. True means users can't log in if there isn’t a matching WebUser ID already. False automatically creates a WebUser ID when someone logs in.

If someone’s registered with TMA and later tries to log in via a web browser, they’ll need a username/password. You can generate a one-time password and shoot it over via your Telegram bot.

Step 2. Deploy your Directual app to Telegram!

If you haven’t got a Telegram bot yet, kick things off in BotFather with the /newbot command. Once you’ve got your bot, stick your Directual-based app onto it as a webapp using the /newapp command. Just follow what BotFather tells you.

Boom, you’re all set! When testing, remember the login kicks in automatically when the user hits the login page.

Afterword

Want to learn more about Telegram Stars, Mini Apps, bots, and whatever else they’re bringing out that’s already integrated with Directual? Come and talk to us live—the links to our communities are provided below.

Cheers, happy building!