diff --git a/.vitepress/sidebar.ts b/.vitepress/sidebar.ts index 9f814918..a14553b0 100644 --- a/.vitepress/sidebar.ts +++ b/.vitepress/sidebar.ts @@ -253,6 +253,10 @@ export function getSidebar() { text: 'Run iApp without ProtectedData', link: '/guides/use-iapp/run-iapp-without-ProtectedData', }, + { + text: 'Integrate Web3 Messaging', + link: '/guides/use-iapp/web3-messaging', + }, ], }, ], @@ -566,10 +570,7 @@ export function getSidebar() { }, ], }, - { - text: 'Integration Guide', - link: '/references/web3telegram/integration-guide', - }, + { text: 'Advanced Configuration', link: '/references/web3telegram/advanced-configuration', diff --git a/src/guides/use-iapp/web3-messaging.md b/src/guides/use-iapp/web3-messaging.md new file mode 100644 index 00000000..0881ac8d --- /dev/null +++ b/src/guides/use-iapp/web3-messaging.md @@ -0,0 +1,128 @@ +--- +title: Integrate Web3 Messaging (Web3Mail & Web3Telegram) +description: + End-to-end guide to send messages with Web3Mail (email) and Web3Telegram + (Telegram) using iExec — protect identifiers, grant access, and send securely +--- + +# Integrate Web3 Messaging + +This guide covers both Web3Mail (email) and Web3Telegram (Telegram) toolkit. The +flow is the same, except that: + +- For Web3Mail, you only need the user's email address. +- For Web3Telegram, you only need the user's Telegram Chat ID. + +## Overview + +1. (Telegram only) Get a Chat ID from the iExec bot +2. Create the Protected Data using DataProtector Toolkit +3. Grant access of your Protected Data +4. Send the message using the relevant SDK ( Web3Mail / Web3Telegram ) + +## 1. Retrieve the Telegram Chat ID (Telegram only) + +Ask the recipient to open Telegram and start a conversation with +[@IExecWeb3TelegramBot](https://t.me/IExecWeb3TelegramBot). The bot replies with +a unique Chat ID. + +::: tip + +- Once the Chat ID is protected, all messages will arrive within this bot + conversation. +- The recipient can leave the conversation at any time to stop receiving + messages. + +::: + +## 2. Create the Protected Data + +Protect the email address or Chat ID using DataProtector Core. + +::: code-group + +```ts twoslash [Web3Mail] +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); + +const protectedData = await dataProtectorCore.protectData({ + data: { + email: 'user@example.com', + }, +}); +``` + +```ts twoslash [Web3Telegram] +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); + +const protectedData = await dataProtectorCore.protectData({ + data: { + telegram_chatId: '12345678', + }, +}); +``` + +::: + +## 3. Grant Access + +Grant permission for a sender and/or an app to contact the user. + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); + +const grantedAccess = await dataProtectorCore.grantAccess({ + protectedData: '0x123abc...', + authorizedApp: '0x456def...', + authorizedUser: '0x789cba...', + pricePerAccess: 3, + numberOfAccess: 10, +}); +``` + +## 4. Send the Message + +::: code-group + +```ts twoslash [Web3Mail] +import { IExecWeb3mail, getWeb3Provider } from '@iexec/web3mail'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const web3mail = new IExecWeb3mail(web3Provider); + +const sendEmail = await web3mail.sendEmail({ + protectedData: '0x123abc...', + emailSubject: 'My email subject', + emailContent: 'My email content', + // useVoucher: true, +}); +``` + +```ts twoslash [Web3Telegram] +import { IExecWeb3telegram, getWeb3Provider } from '@iexec/web3telegram'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const web3telegram = new IExecWeb3telegram(web3Provider); + +const sendTelegram = await web3telegram.sendTelegram({ + protectedData: '0x123abc...', + senderName: 'Arthur', + telegramContent: 'My telegram message content', +}); +``` + +::: + +## Payment + +Each message sent through Web3Mail or Web3Telegram requires payment in RLC +tokens. + +For detailed information about payment methods, pricing, and voucher usage, see +our comprehensive guide: +[How to pay for executions](/guides/use-iapp/how-to-pay-executions) diff --git a/src/references/web3telegram.md b/src/references/web3telegram.md index f485ee1d..b2034903 100644 --- a/src/references/web3telegram.md +++ b/src/references/web3telegram.md @@ -19,8 +19,8 @@ telegram chat ID recipients through use of Ethereum addresses. iExec's protocol the telegram chat ID as a `protectedData` entity using [iExec Data Protector](/references/dataProtector). Through this mechanism, users have complete control over which applications may use their -[chat ID](/references/web3telegram/integration-guide#_1-get-your-users-to-retrieve-their-chat-id) -for sending communications. +[chat ID](/guides/use-iapp/web3-messaging#retrieve-chat-id) for sending +communications. Sending a user a message, therefore, requires knowledge of the Ethereum address of their `protectedData` as well as an explicit authorization for your account diff --git a/src/references/web3telegram/integration-guide.md b/src/references/web3telegram/integration-guide.md deleted file mode 100644 index 898cc0f1..00000000 --- a/src/references/web3telegram/integration-guide.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: iExec Web3Telegram Integration Guide -description: - Integrate iExec Web3Telegram to enable secure and private Telegram messaging - via blockchain-based access control, ensuring user privacy and decentralized - messaging control ---- - -# iExec Web3Telegram Integration Guide - -## Overview - -Integrating **iExec Web3Telegram** enables secure and private messaging on -Telegram using blockchain-based access control. This allows users to send and -receive messages while maintaining full control over their data. - -The integration process consists of the following steps: - -1. **Get your user to retrieve their Chat ID from the iExec Web3Telegram bot.** -2. **Create the protected data via the iExec Data Protector SDK.** -3. **Grant access via the Data Protector SDK to authorize users to receive - messages.** -4. **Send messages securely using the Web3Telegram SDK.** - -## 1. Get your Users to Retrieve their Chat ID - -To enable messaging via Web3Telegram, you need to retrieve the recipient's Chat -ID. - -A **Chat ID** is a unique identifier assigned to your Telegram account. It -allows applications to send messages to you **without revealing your actual -Telegram username or phone number**. By **protecting your Chat ID with iExec**, -you ensure that it remains **encrypted and private**, so only **authorized -senders** can contact you. - -### Steps: - -- Ask the recipient to open Telegram and start a conversation with - [**@IExecWeb3Telegrambot**](https://t.me/IExecWeb3TelegramBot). -- The bot will reply with their unique Chat ID. -- Save this Chat ID as you will need it for the next steps. - -::: tip - -- Once the Chat ID is protected, all messages will arrive within this bot - conversation. -- The recipient can leave the conversation at any time to stop receiving - messages. - -::: - -## 2. Create the Protected Data with Data Protector SDK - -After obtaining your user's Chat ID, you need to protect it using iExec’s Data -Protector to ensure privacy and security. - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -const protectedData = await dataProtectorCore.protectData({ - data: { - telegram_chatId: '12345678', // Recipient's Chat ID - }, -}); -``` - -## 3. Grant Access via Data Protector SDK - -To allow users to send messages, you must explicitly grant access to specific -users. - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -const grantedAccess = await dataProtectorCore.grantAccess({ - protectedData: '0x123abc...', // Protected Chat ID data address - authorizedApp: '0x456def...', // Web3Telegram app address - authorizedUser: '0x789cba...', // Ethereum address of the authorized sender - pricePerAccess: 3, // Cost per message (in iExec tokens) - numberOfAccess: 10, // Allowed message count - onStatusUpdate: ({ title, isDone }) => { - console.log(title, isDone); - }, -}); -``` - -## 4. Send Messages via Web3Telegram SDK - -Once authorized, a user can send messages via Web3Telegram SDK. - -```ts twoslash -import { IExecWeb3telegram, getWeb3Provider } from '@iexec/web3telegram'; -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const web3telegram = new IExecWeb3telegram(web3Provider); -const sendTelegram = await web3telegram.sendTelegram({ - protectedData: '0x123abc...', // Protected Chat ID data address - senderName: 'Arthur', - telegramContent: 'My telegram message content', -}); -``` - -## Conclusion - -By integrating **iExec Web3Telegram**, you ensure privacy, security, and -decentralized control over your Telegram messaging. Your users decide who can -send them messages and set a cost for access while keeping their Telegram handle -hidden. - -For further support, join the iExec community on -[Discord](https://discord.com/invite/pbt9m98wnU).