Telegram Integration
This page outlines how to integrate Passport within a Telegram Mini App.
Due to variations in how pop-ups are handled across devices in the Telegram Mini App browser, only pre-approved transactions are supported.
See the pre-approved transactions page for more information on setting up pre-approved transactions.
Immutable Hub Setup
Create a Passport client in the Immutable Hub. For Telegram Mini App support ensure that the Application Type is Native.
Passport Initialisation
When initialising the Passport instance, ensure that crossSdkBridgeEnabled: true is provided to enable pre-approved transactions.
export const passportInstance = new passport.Passport({
baseConfig: new ImmutableConfiguration({ environment: Environment.SANDBOX }),
// The client ID of the application created in Hub
clientId: process.env.NEXT_PUBLIC_CLIENT_ID || "",
// The redirect URI set in the application created in Hub
redirectUri: process.env.NEXT_PUBLIC_REDIRECT_URI || "",
// The logout redirect URI set in the application created in Hub
logoutRedirectUri: process.env.NEXT_PUBLIC_LOGOUT_REDIRECT_URI || "",
audience: "platform_api",
scope: "openid offline_access email transact",
// Set crossSdkBridgeEnabled to enable pre-approved transactions
crossSdkBridgeEnabled: true,
});
Passport Login
For logging in successfully across any device in the Telegram Mini App browser use the loginWithDeviceFlow() method instead of the login() method. Ensure the Passport client you setup earlier in the Immutable Hub is configured as a Native Application Type.
// Use loginWithDeviceFlow as the login method for Telegram Mini App to ensure support for all devices
const deviceFlowParams = await passportInstance.loginWithDeviceFlow();
// Open the device flow url using the openLink function on the telegram sdk
WebApp.openLink(deviceFlowParams.url);
// Wait for the user to complete the login before calling eth_requestAccounts
await passportInstance.loginWithDeviceFlowCallback(
deviceFlowParams.deviceCode,
deviceFlowParams.interval,
);
// Get the provider and call eth_requestAccounts to get the user's wallet address
const provider = passportInstance.connectEvm();
const [userAddress] = await provider.request({
method: "eth_requestAccounts",
});
setWalletAddress(userAddress);
Submitting Transactions
Transactions in Telegram Mini Apps require pre-approvals to work across all devices. Once your contract function has been configured for pre-approval then the function can be called as usual. This will submit the transaction without displaying a confirmation popup to the user.
The below example is how to submit an asset transfer transaction. In this example the safeTransferFrom function needs to be configured for pre-approval for the collection you are calling the transfer function on.
// Setup the contract ABI with the safeTransferFrom function for transferring assets
const abi = [
"function safeTransferFrom(address from, address to, uint256 token_id)",
];
// Get the signer from the provider that was initialised in the Connect flow and create a contract instance
const signer = zkEvmProvider.getSigner();
const contract = new ethers.Contract(collectionAddress, abi, signer);
try {
// Call the transfer function on the contract
await contract.safeTransferFrom(walletAddress, toAddress, tokenId);
setTransferSuccess(true);
} catch (error: any) {
setErrorMessage(error.message);
}
Full Demo
See the below demo on GitHub for an example of how to use Passport with a Telegram Mini App.
"use client";
import React from "react";
import Home from "./components/Home";
import { passport } from "@imtbl/sdk";
import { Environment, ImmutableConfiguration } from "@imtbl/sdk/config";
// #doc passport-telegram-mini-app-configuration
export const passportInstance = new passport.Passport({
baseConfig: new ImmutableConfiguration({ environment: Environment.SANDBOX }),
// The client ID of the application created in Hub
clientId: process.env.NEXT_PUBLIC_CLIENT_ID || "",
// The redirect URI set in the application created in Hub
redirectUri: process.env.NEXT_PUBLIC_REDIRECT_URI || "",
// The logout redirect URI set in the application created in Hub
logoutRedirectUri: process.env.NEXT_PUBLIC_LOGOUT_REDIRECT_URI || "",
audience: "platform_api",
scope: "openid offline_access email transact",
// Set crossSdkBridgeEnabled to enable pre-approved transactions
crossSdkBridgeEnabled: true,
});
// #enddoc passport-telegram-mini-app-configuration
export default function App() {
return <Home />;
}