Skip to main content

✨ Interactions

The Interaction category helps you enhance user engagement and interactivity in your app. By attaching these actions to UI elements (e.g., buttons), you can display alerts, show temporary messages (toasts), send push notifications, or store data locally.

1. Open Alert​

Use the Open Alert action to display a popup dialog containing a title, description, and an optional action button. This is ideal for warnings, confirmations, or important messages that require immediate user attention.

How to Use​

  1. Open the Workflow Editor: Select the element on your canvas (e.g., a button) you want to attach the action to. Click on it to open left and right bar. In the left bar click Add Action → More actions....
  2. Add the Action:
    • In the workflow canvas, click the plus (+) icon.
    • Select Interaction → Open alert.
  3. Configure Alert Details:
    • Alert Header: The main title or header text for the alert (e.g., "Warning").
    • Alert Description: Additional information about the alert (e.g., "Are you sure you want to delete this item?").
    • Action Button Text: The text displayed on the alert's button (e.g., "OK" or "Confirm").
  4. Save & Test:
    • Click Save, then Preview your app. When the user interacts with the element, the alert will appear.

Use Cases:​

  • Confirmations: Asking the user to confirm an action (e.g., deleting data).
  • Warnings: Notifying the user of potential issues (e.g., incomplete forms).
  • Information: Displaying important announcements or instructions.

Open Alert

2. Show Toast​

A Toast is a small, temporary notification message that appears on the screen. It automatically disappears after a specified duration. This is useful for non-intrusive updates, like success messages or quick reminders.

How to Use​

  1. Open the Workflow Editor: Open the Workflow Editor: Select the element on your canvas (e.g., a button) you want to attach the action to. Click on it to open left and right bar. In the left bar click Add Action → More actions....
  2. Add the Action:
    • In the workflow canvas, click the plus (+) icon.
    • Select Interaction → Show toast.
  3. Configure Toast Details:
    • Toast Title: The main text shown in the toast (e.g., "Item saved successfully!").
    • Duration: How long the toast remains visible. Options typically include Short or Long.
    • Position: The vertical position of the toast on the screen (Bottom, Middle, or Top).
  4. Save & Test:
    • Click Save, then Preview your app. Interacting with the element triggers the toast message.

Show Toast

Use Cases:​

  • Success Messages: Confirming that an action was completed (e.g., "Profile updated!").
  • Status Updates: Indicating loading results or partial completion.
  • Reminders: Briefly informing users about small updates without disrupting their workflow.

3. Push Notification​

The Push Notification action in AppStruct enables you to send device-level notifications to your users on iOS and Android (or both). Once you've set up the necessary configurations, you can trigger a push notification from a button press, a specific workflow event, or any custom logic you define.

Prerequisites​

  1. Firebase Configuration:
    • You must connect your app to Firebase for handling push tokens and message delivery.
    • Follow the Firebase setup instructions in AppStruct's Publishing section to ensure your project is linked properly.
  2. Platform Publishing:
    • If you plan to send push notifications to iOS or Android devices, your app must be configured and published (or test-deployed) on the respective platforms.
    • This ensures the device tokens can be registered correctly for push notifications.

Adding a Push Action​

  1. Select the UI element (e.g., a Button) you want to trigger the notification from.
  2. In the left bar, click Add Action → More actions... to open the workflow canvas.
  3. Click the plus (+) icon in the workflow canvas.
  4. Select Interaction → Push notification from the menu.
  5. Configure Notification Details:
    • Push Notification Title: The main headline for your notification (e.g., "Order Update").
    • Push Notification Description: A short message describing the alert (e.g., "Your order is out for delivery!").
    • Platform: Choose All, iOS, or Android to specify which devices will receive the notification.
    • Opened Screen on Clicking Notification: Select the screen in your app that users should be taken to when they tap the notification.
  6. Click Save.
  7. In Preview, you may see a placeholder or test message. Actual push notifications typically require a published or test environment on a real device to function.

Push Notifications

Use Cases:​

  • Success Messages: Confirming that an action was completed (e.g., "Profile updated!").
  • Status Updates: Indicating loading results or partial completion (e.g., "Your order is being prepared").
  • Reminders: Briefly informing users about small updates without disrupting their workflow (e.g., "Don't forget your upcoming appointment").

4. Local Storage​

Use Local Storage to store small pieces of data on the user's device (e.g., preferences, tokens, or temporary form inputs). This data persists even if the user closes the app, but is specific to their device or browser.

Enhanced Local Storage Features​

Local Storage saves data directly on the user's device, perfect for preferences, offline data, and app state management.

How to Use​

  1. Open the Workflow Editor: Select the element on your canvas (e.g., a button) you want to attach the action to. Click on it to open left and right bar. In the left bar click Add Action → More actions....
  2. Add the Action:
    • In the workflow canvas, click the plus (+) icon.
    • Select Interaction → Local storage.
  3. Configure Local Storage Settings:
    • Operation: Save, Load, or Remove data
    • Storage Key: A unique identifier for the stored data (e.g., "userToken" or "themePreference").
    • Value Source: Where the data is coming from. Options might include:
      • Static text: A fixed value that you enter manually.
      • Element input: Data pulled from a user input field or another element in your app.
  4. Save & Test:
    • Click Save, then Preview. Interacting with the element writes the specified data to local storage.

Local Storage Desktop

Operations Available​

  • Save: Store data with a specific key
  • Load: Retrieve previously stored data
  • Remove: Delete specific stored data
  • Clear All: Remove all locally stored data

Use Cases:​

  • User Preferences: Storing user preferences (e.g., dark mode, language settings).
  • Form Drafts: Save incomplete form data
  • Offline Mode: Store data when internet is unavailable
  • Shopping Cart: Persist cart items between sessions
  • User Progress: Save game or tutorial progress
  • Caching Data: Keeping temporary data so the user doesn't have to re-enter information.
  • Authentication: Storing tokens for session management (though be mindful of security best practices).

5. Share Content​

Share Content leverages the device's native sharing capabilities to share text, links, or data.

How to Use​

  1. Add action via Interaction → Share Content
  2. Configure:
    • Content Type: Text, URL, or custom data
    • Share Text: The content to be shared
    • Share URL: Optional link to include

Share Content Desktop

Features​

  • Native Share Dialog: Uses device's built-in sharing interface
  • App Detection: Automatically shows available sharing apps
  • Fallback Options: Graceful degradation if sharing isn't available

Use Cases​

  • Social Sharing: Share app content to social media
  • Referral Programs: Share invite links with friends
  • Content Export: Share generated reports or data
  • Marketing: Encourage users to share your app

Platform Support​

  • Mobile: Full native sharing support on iOS and Android
  • Web: Uses Web Share API where available, falls back to copy link
  • Desktop: Copy to clipboard functionality

6. Play Vibration​

Play Vibration provides haptic feedback to enhance user interactions on mobile devices.

How to Use​

  1. Add action via Interaction → Play Vibration
  2. Configure:
    • Vibration Pattern: Duration and intensity of vibration
    • Custom Pattern: Array of vibration intervals

Play Vibration

Patterns Available​

  • Short Pulse: Quick confirmation (15ms)
  • Medium Pulse: Standard feedback (50ms)
  • Long Pulse: Attention-grabbing (200ms)
  • Double Tap: Two quick pulses
  • Custom: Define your own pattern

Use Cases​

  • Button Feedback: Confirm user taps and interactions
  • Notifications: Alert users to important events
  • Game Mechanics: Enhance gaming experiences
  • Error Feedback: Indicate invalid actions
  • Success Confirmation: Confirm completed actions

Platform Considerations​

  • iOS: Supports taptic engine feedback
  • Android: Full vibration pattern support
  • Web: Limited vibration API support
  • Accessibility: Respect user vibration preferences

7. Toggle Dark Mode​

Toggle Dark Mode switches your app between light and dark themes, improving accessibility and user preference.

How to Use​

  1. Add action via Interaction → Toggle Dark Mode
  2. Configure:
    • Default Mode: Light or Dark starting mode
    • User Preference: Remember user's choice
    • Auto Detection: Use system theme preference

Toggle Dark Mode

Features​

  • System Integration: Respects device dark mode setting
  • Persistent Choice: Remembers user preference
  • Smooth Transition: Animated theme switching
  • Component Adaptation: All components automatically adapt

Benefits​

  • Better Accessibility: Easier viewing in low light
  • Battery Saving: Reduces power consumption on OLED screens
  • User Preference: Modern apps expect theme options
  • Professional Polish: Shows attention to user experience

Implementation Details​

  • CSS Variables: Uses CSS custom properties for theme switching
  • Local Storage: Saves user preference across sessions
  • Media Query: Detects system preference automatically
  • Smooth Animations: Transitions between themes smoothly

8. Show/Hide Element​

Show Element and Hide Element control the visibility of elements dynamically based on user interactions or conditions.

How to Use​

  1. Add action via Interaction → Show Element or Hide Element
  2. Configure:
    • Target Element: Choose which element to show/hide
    • Animation: Fade, slide, or instant visibility change
    • Timing: Delay before showing/hiding

Advanced Options​

  • Conditional Visibility: Show based on data or user state
  • Group Visibility: Show/hide multiple elements together
  • Animated Transitions: Smooth appearance/disappearance
  • State Persistence: Remember visibility state

Use Cases​

  • Progressive Disclosure: Show advanced options when needed
  • Form Logic: Show fields based on previous answers
  • Loading States: Hide content while loading
  • Success/Error Messages: Display feedback messages
  • Onboarding: Guide users through features step-by-step

Animation Types​

  • Fade: Gradual opacity change
  • Slide: Movement-based reveal/hide
  • Scale: Size-based animation
  • Instant: Immediate show/hide

9. Telegram Action​

Telegram Action provides comprehensive integration with Telegram Mini Apps, enabling you to create native-feeling experiences within the Telegram ecosystem. These actions leverage Telegram's WebApp API to control interface elements, handle payments, and interact with users.

Prerequisites​

  • Your app must be configured as a Telegram Mini App
  • Telegram Bot Token may be required for certain actions (e.g., payments)
  • Actions only work when app is opened within Telegram and app in published

Available Actions​

Telegram Action Types

Main Button Control​

Show Main Button

  • Displays Telegram's main action button at the bottom of the app
  • Configuration:
    • Button Text: Text displayed on the button (e.g., "Continue", "Buy Now")
    • Button Color: Hex color for button background (#3378FF)
    • Text Color: Hex color for button text

Hide Main Button

  • Removes the main action button from view
  • No additional configuration required

Show Back Button

  • Displays Telegram's back button in the header
  • Automatically handles navigation back to previous context

Hide Back Button

  • Removes the back button from view
  • Use when you want to prevent users from going back

User Interaction​

Show Alert

  • Displays a native Telegram alert dialog
  • Configuration:
    • Title: Alert title (optional)
    • Message: Alert message text

Show Confirm

  • Displays a confirmation dialog with OK/Cancel options
  • Configuration:
    • Title: Confirmation title (optional)
    • Message: Confirmation message
    • On Confirm Actions: Actions to execute when user confirms
    • On Cancel Actions: Actions to execute when user cancels

Haptic Feedback​

Haptic Feedback

  • Triggers device vibration for enhanced user interaction
  • Types:
    • Impact: Physical feedback (light, medium, heavy, rigid, soft)
    • Notification: Status feedback (success, warning, error)
    • Selection: Selection change feedback

App Control​

Send Data

  • Sends data back to the Telegram bot
  • Configuration:
    • Data: String data to transmit to bot

Close

  • Closes the mini app and returns to Telegram chat
  • Use for final actions or exit points

Expand

  • Expands app to full viewport height
  • Improves user experience for content-heavy apps

Theme Control​

Set Header Color

  • Changes Telegram's header bar color
  • Configuration:
    • Color: Hex color value

Set Background Color

  • Changes the app's background color within Telegram
  • Configuration:
    • Color: Hex color value

User Data​

Get Current User

  • Retrieves current Telegram user information
  • Configuration:
    • Element Mappings: Map user data fields to app elements
    • Available Fields: id, first_name, last_name, username, photo_url, language_code

Payments​

Pay with Stars

  • Initiates Telegram Stars payment
  • Configuration:
    • Bot Token: Your Telegram bot token
    • Stars Price: Number of Telegram Stars required
    • Payment Title: Title shown in payment dialog
    • Payment Description: Description of the purchase
    • On Payment Success Actions: Actions to execute on successful payment
    • On Payment Error Actions: Actions to execute on payment failure

How to Use​

  1. Open the Workflow Editor: Select the element you want to attach the action to
  2. Add the Action:
    • In the workflow canvas, click the plus (+) icon
    • Select Interaction → Telegram Action
  3. Choose Action Type: Select the specific Telegram action from the dropdown
  4. Configure Settings: Fill in the required parameters for your chosen action
  5. Add Result Actions (for confirm/payment actions):
    • Click Add Action in the success/error/confirm/cancel sections
    • Choose from available action types (Local Storage, Show Toast, Navigation, etc.)
  6. Save & Test: Preview your app within Telegram to test functionality

Telegram Action Desktop

Advanced Features​

Action Chaining​

Telegram actions support sophisticated result handling:

User clicks "Buy Now" button
↓
Telegram Action: Pay with Stars
├── On Success: Show Toast "Payment successful!"
├── On Success: Local Storage: Save purchase data
├── On Success: Navigation: Go to success page
└── On Error: Show Alert "Payment failed. Please try again."

User Data Mapping​

Map Telegram user data to your app elements:

  • Profile Picture: Map photo_url to Image element's src
  • Username: Map username to Text element's innerText
  • Language: Map language_code for localization

Payment Integration​

Complete payment flow with Telegram Stars:

  1. User initiates purchase
  2. Telegram shows native payment dialog
  3. On success: Update app state, save purchase, show confirmation
  4. On error: Show error message, allow retry

Use Cases​

E-commerce Apps​

  • Product Browsing: Use main button for "Add to Cart"
  • Checkout Process: Implement payment with Telegram Stars
  • Order Confirmation: Send data back to bot for order processing

Gaming Apps​

  • In-App Purchases: Buy game items with Telegram Stars
  • Haptic Feedback: Enhance game interactions
  • Leaderboards: Share scores back to Telegram bot

Utility Apps​

  • Form Submission: Send completed forms to bot
  • User Authentication: Get user data for personalization
  • Theme Customization: Allow header/background color changes

Content Apps​

  • Article Reading: Expand to full height for better reading
  • Content Sharing: Send interesting content back to chat
  • User Preferences: Store reading preferences locally

Best Practices​

User Experience​

  • Progressive Enhancement: Start with basic functionality, add Telegram-specific enhancements
  • Fallback Handling: Provide alternative flows for non-Telegram environments
  • Clear Feedback: Use haptic feedback and visual cues appropriately
  • Payment Security: Always validate payments on your backend

Technical Implementation​

  • Bot Token Security: Store bot tokens securely, never expose in client code
  • Error Handling: Implement comprehensive error handling for all actions
  • Testing: Test thoroughly within actual Telegram environment
  • Performance: Minimize API calls, cache user data when appropriate

Design Guidelines​

  • Native Feel: Follow Telegram's design patterns and guidelines
  • Consistent Theming: Use Telegram's color scheme for seamless integration
  • Button Placement: Use main button for primary actions only
  • Information Hierarchy: Reserve alerts for important messages

Debugging​

When testing outside Telegram:

  • Actions will log to browser console for debugging
  • Use forceTelegram=true URL parameter to simulate Telegram environment
  • Check browser developer tools for action execution logs

Platform Support​

  • iOS: Full support for all Telegram actions
  • Android: Complete action compatibility
  • Web: Limited to Telegram Web interface capabilities
  • Desktop: Available through Telegram Desktop app

Best Practices​

User Experience​

  • Use Alerts Sparingly: Overusing alerts can interrupt user flow. Reserve them for critical information or confirmations.
  • Short & Sweet Toasts: Keep toast messages brief so they're easy to read before they disappear.
  • Push Notification Permissions: Ensure you handle user permissions correctly. Users must opt-in to receive push notifications on most platforms.
  • Local Storage Security: Avoid storing sensitive information (like passwords) in local storage. Instead, store tokens securely and implement proper security measures.

Technical Considerations​

  • Test Across Platforms: Different devices may handle interactions differently
  • Graceful Degradation: Provide fallbacks for unsupported features
  • Performance Impact: Monitor the impact of frequent interactions
  • Accessibility: Ensure interactions work with screen readers and assistive technologies

Design Guidelines​

  • Consistent Feedback: Use similar patterns throughout your app
  • Clear Visual Cues: Make interactive elements obvious
  • Respect User Preferences: Honor system settings and user choices
  • Progressive Enhancement: Start with basic functionality and add enhancements

Need Assistance?​

If you encounter any challenges or require further guidance while building your app, please refer to the Documentation or, contact our support team at [email protected].