Embedding the portal in Telegram Mini Apps
Learn how to embed your Domino community portal within Telegram Mini Apps, handle authentication properly, and configure the necessary settings for seamless integration.
Last updated
Learn how to embed your Domino community portal within Telegram Mini Apps, handle authentication properly, and configure the necessary settings for seamless integration.
Last updated
Telegram Mini Apps provide a seamless way to integrate web applications directly into the Telegram ecosystem. By embedding your Domino community portal in a Mini App, you can offer your Telegram community direct access to , , and other community features without leaving the Telegram interface.
This integration requires special handling due to the unique authentication requirements and technical constraints of the Telegram Mini App environment. The portal automatically detects when it's running inside a Mini App and adjusts its behavior accordingly.
Telegram Mini Apps have a unique authentication system that differs from standard web applications. When users access your Mini App, Telegram provides initialization data that must be forwarded to your portal for proper user identification and session management.
Init Data: Telegram automatically generates user authentication data when the Mini App loads
URL Hash Fragment: Authentication data must be passed through the URL hash (#
) for security
No SSR Parameter: Server-side rendering must be disabled for proper Mini App functionality
External Browser Flow: Social media connections require opening external browser windows
Telegram Mini Apps run in a sandboxed environment with limited browser capabilities. Social media authentication (Discord, Twitter) will open in external browser windows rather than inline popups.
Before embedding your portal, you need to configure it properly in the Domino dashboard.
Navigate to your portal settings and configure the authentication tab:
Access Portal Settings from your community dashboard
Go to the Authentication tab
Enable the social login methods your community needs:
Discord: For Discord-based quests and verification
Twitter: For Twitter engagement quests
Configure wallet login options if you have crypto-related quests
Your Telegram Mini App's bot must be configured in your portal settings to enable proper integration:
In your portal settings, navigate to the Authentication tab
Locate the Telegram Bot ID field
Enter your bot's unique identifier
Click Save to apply the configuration
This ensures the portal recognizes and properly handles requests from your specific bot, providing an additional layer of security.
Here's the essential code structure for embedding your portal in a Telegram Mini App:
nossr=true
: Disables server-side rendering, which is required for proper Mini App functionality
Hash forwarding: The location.hash
contains Telegram's authentication data and must be passed to the portal
Expected Outcome
After implementing this code, your Telegram Mini App will display your Domino portal with proper authentication and full functionality. Users will be automatically signed in using their Telegram credentials.
You can embed specific quest pages or sections of your portal:
For more complex implementations, you can dynamically construct the portal URL based on user context:
Due to Telegram Mini App constraints, social media authentication flows (Discord, Twitter) will open in external browser windows rather than inline popups.
User clicks connect: Portal detects Mini App environment
External browser opens: Authentication happens in device's default browser
Return to Mini App: User manually returns to the Mini App after authentication
Automatic sync: Portal detects the new connection and updates the interface
Portal not loading in Mini App
Verify the nossr=true
parameter is included in your iframe URL
Check that the hash is being properly forwarded from location.hash
Ensure your bot ID is configured in portal settings under the Authentication tab
Confirm your portal URL is correct and accessible
Authentication failures
Confirm the portal URL is correct and accessible
Check for CORS issues if using custom domains
Ensure your bot ID matches exactly in the portal settings
Social connections not working
Ensure users understand the external browser flow
Verify social app configurations in your community settings
Test the authentication flow outside the Mini App first