Integration Guide
Welcome to the sukuna.site integration documentation. Here you will learn how to integrate our high-speed, secure redirect logic into your applications specifically to break users out of in-app browsers like Telegram.
Telegram Bot Integration
If you are running a Telegram bot, you can easily implement the secure redirect by modifying your short URL generation logic. Our service expects a base64 encoded destination URL passed as the to query parameter.
# Define your Next.js redirect app URL REDIRECT_SERVICE_URL = "https://sukuna.site/api/redirect"
import base64
from config import REDIRECT_SERVICE_URL
import urllib.parse
def generate_secure_redirect(target_url: str) -> str:
"""
Generates a secure redirect URL for sukuna.site
which handles the Telegram in-app browser breakout.
"""
# Encode the destination URL in base64
encoded_bytes = base64.b64encode(target_url.encode("utf-8"))
encoded_target = encoded_bytes.decode("utf-8")
# URL encode the base64 string just to be safe with query params
safe_target = urllib.parse.quote(encoded_target)
# Construct the final URL
final_url = f"{REDIRECT_SERVICE_URL}?to={safe_target}"
return final_url
# Example Usage
if __name__ == "__main__":
destination = "https://example.com/secret-file-download"
secure_link = generate_secure_redirect(destination)
print(f"Send this link to users: {secure_link}")
How it works
When a user clicks this link in Telegram, the Telegram WebView will open `sukuna.site`. Our Next.js backend detects the custom user-agent from Telegram and instantly returns an HTML page containing an Android Intent (`intent://`) or iOS Custom Scheme (`googlechromes://`) payload, forcing the native Chrome browser to open and load your original target URL dynamically.