From 87c99129e31461119a758405183d3c678f349e37 Mon Sep 17 00:00:00 2001 From: Mathis Debuire <68806646+64ix@users.noreply.github.com> Date: Thu, 21 Aug 2025 09:07:21 +0200 Subject: [PATCH 1/4] feat: Move and rework Web3telegram integration guide to Web3Messaging in guides section --- .vitepress/sidebar.ts | 9 +- src/guides/use-iapp/web3-messaging.md | 123 ++++++++++++++++++ src/references/web3telegram.md | 4 +- .../web3telegram/integration-guide.md | 112 ---------------- 4 files changed, 130 insertions(+), 118 deletions(-) create mode 100644 src/guides/use-iapp/web3-messaging.md delete mode 100644 src/references/web3telegram/integration-guide.md diff --git a/.vitepress/sidebar.ts b/.vitepress/sidebar.ts index af4a6d47..8ca97b62 100644 --- a/.vitepress/sidebar.ts +++ b/.vitepress/sidebar.ts @@ -252,6 +252,10 @@ export function getSidebar() { text: 'Add Inputs to the Execution', link: '/guides/use-iapp/add-inputs-to-execution', }, + { + text: 'Integrate Web3 Messaging', + link: '/guides/use-iapp/web3-messaging', + }, { text: 'How to Pay the Executions', link: '/guides/use-iapp/how-to-pay-executions', @@ -591,10 +595,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..664a08d3 --- /dev/null +++ b/src/guides/use-iapp/web3-messaging.md @@ -0,0 +1,123 @@ +--- +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). The flow is +the same, except that: + +- For Web3Mail, you only need the user's email address. +- For Web3Telegram, you must first retrieve the user's Telegram Chat ID. + +## Overview + +1. (Telegram only) Retrieve the Chat ID from the iExec bot +2. Create the `protectedData` using DataProtector +3. Grant access with DataProtector +4. Send the message using the relevant SDK + +## 1. Retrieve the Telegram Chat ID (Telegram only) {#retrieve-chat-id} + +Ask the recipient to open Telegram and start a conversation with +[@IExecWeb3TelegramBot](https://t.me/IExecWeb3TelegramBot). The bot replies with +their 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 identifier using DataProtector Core. + +### Web3Mail — protect the email address + +```ts twoslash +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', + }, +}); +``` + +### Web3Telegram — protect the Chat ID + +```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', + }, +}); +``` + +## 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 + +### Web3Mail — sendEmail + +```ts twoslash +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, +}); +``` + +### Web3Telegram — sendTelegram + +```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...', + senderName: 'Arthur', + telegramContent: 'My telegram message content', + // useVoucher: true, +}); +``` + +## Payment + +See the full payment guide: +[/guides/use-iapp/how-to-pay-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). From 9c88c74d39fd94fa99c822e053b75674494efc04 Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Thu, 21 Aug 2025 15:58:04 +0200 Subject: [PATCH 2/4] fix: correct formatting in sidebar.ts for iApp guide entry --- .vitepress/sidebar.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vitepress/sidebar.ts b/.vitepress/sidebar.ts index 9b57f9c7..a14553b0 100644 --- a/.vitepress/sidebar.ts +++ b/.vitepress/sidebar.ts @@ -252,7 +252,7 @@ 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', From 02813a5bceb16dd59262972f73cd3aee37800101 Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Thu, 21 Aug 2025 16:16:01 +0200 Subject: [PATCH 3/4] refactor: update Web3 Messaging guide for clarity and consistency --- src/guides/use-iapp/web3-messaging.md | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/src/guides/use-iapp/web3-messaging.md b/src/guides/use-iapp/web3-messaging.md index 664a08d3..36d132fe 100644 --- a/src/guides/use-iapp/web3-messaging.md +++ b/src/guides/use-iapp/web3-messaging.md @@ -7,35 +7,37 @@ description: # Integrate Web3 Messaging -This guide covers both Web3Mail (email) and Web3Telegram (Telegram). The flow is -the same, except that: +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 must first retrieve the user's Telegram Chat ID. +- For Web3Telegram, you only need the user's Telegram Chat ID. ## Overview -1. (Telegram only) Retrieve the Chat ID from the iExec bot -2. Create the `protectedData` using DataProtector -3. Grant access with DataProtector -4. Send the message using the relevant SDK +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) {#retrieve-chat-id} +## 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 -their unique Chat ID. +a unique Chat ID. -:::: tip +::: 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. :::: + messages. + +::: ## 2. Create the Protected Data -Protect the identifier using DataProtector Core. +Protect the email address or Chat ID using DataProtector Core. ### Web3Mail — protect the email address From d28a56b29576927481e3484e36e20bfea8c13e78 Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Thu, 21 Aug 2025 16:16:12 +0200 Subject: [PATCH 4/4] refactor: enhance Web3 Messaging guide with code grouping and payment details --- src/guides/use-iapp/web3-messaging.md | 29 +++++++++++++++------------ 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/src/guides/use-iapp/web3-messaging.md b/src/guides/use-iapp/web3-messaging.md index 36d132fe..0881ac8d 100644 --- a/src/guides/use-iapp/web3-messaging.md +++ b/src/guides/use-iapp/web3-messaging.md @@ -39,9 +39,9 @@ a unique Chat ID. Protect the email address or Chat ID using DataProtector Core. -### Web3Mail — protect the email address +::: code-group -```ts twoslash +```ts twoslash [Web3Mail] import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; const web3Provider = getWeb3Provider('PRIVATE_KEY'); const dataProtectorCore = new IExecDataProtectorCore(web3Provider); @@ -53,9 +53,7 @@ const protectedData = await dataProtectorCore.protectData({ }); ``` -### Web3Telegram — protect the Chat ID - -```ts twoslash +```ts twoslash [Web3Telegram] import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; const web3Provider = getWeb3Provider('PRIVATE_KEY'); const dataProtectorCore = new IExecDataProtectorCore(web3Provider); @@ -67,6 +65,8 @@ const protectedData = await dataProtectorCore.protectData({ }); ``` +::: + ## 3. Grant Access Grant permission for a sender and/or an app to contact the user. @@ -87,9 +87,9 @@ const grantedAccess = await dataProtectorCore.grantAccess({ ## 4. Send the Message -### Web3Mail — sendEmail +::: code-group -```ts twoslash +```ts twoslash [Web3Mail] import { IExecWeb3mail, getWeb3Provider } from '@iexec/web3mail'; const web3Provider = getWeb3Provider('PRIVATE_KEY'); @@ -103,9 +103,7 @@ const sendEmail = await web3mail.sendEmail({ }); ``` -### Web3Telegram — sendTelegram - -```ts twoslash +```ts twoslash [Web3Telegram] import { IExecWeb3telegram, getWeb3Provider } from '@iexec/web3telegram'; const web3Provider = getWeb3Provider('PRIVATE_KEY'); @@ -115,11 +113,16 @@ const sendTelegram = await web3telegram.sendTelegram({ protectedData: '0x123abc...', senderName: 'Arthur', telegramContent: 'My telegram message content', - // useVoucher: true, }); ``` +::: + ## Payment -See the full payment guide: -[/guides/use-iapp/how-to-pay-executions](/guides/use-iapp/how-to-pay-executions) +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)