Skip to main content

Guided Conversation

A Guided Conversation is a function that will inject predetermined messages into an exisitng or new conversation. This feature is responsavle for checking the app conditions, (e.g. user intent, first time user, auth staus, etc) the goal is to ensure the [Guide] can work.

Task Chat Branch API
note

These details are only updated with each release, for more acurate updates and keeping track of progress, see the task in GitHub.

Team​

OwnerLead
MendyEsti

Status​

Doc StatusProduct StatusLast UpdateVersionReleasePhase
In ProgressUp Next04.03.20240.01InternalAlpha

Description​

The Guided Conversation is not a Guide itself, it is nearly responsable for ensuring the guide can be exceuted and to excequte the guides wishes, think of it as the foundation to the guide.

Like a notification API, android handles the push notifications through an API (this is the Guided Conversation) and the developer provides the text and buttons for the notification (this is the Guide).

Guide: Similar to a Pre-built Flow, or a Saved Flow, the flow is simply a list of components. A guide is simply a document that contains a list of messages, rules, components, actions and other details for the Guilded Conversation to execute.

E.g.: the guide document/file contains Rules (if first time user, if not logged in...) Messages: (1. Your messages are saved for 15 days. 2. CTAs do it later, let's do it) 3. Wait for response (A message can contain anything, text, image, component, action, etc.) We will also need to create "non functional" actions, basically actions that no not call an API but rather takes an action in the app like navigate to..., in this example we can either navigate to login or call the login guide.

The details from the guide should be fed to the Guilded Conversation to execute, the guide itself is a static document and the guided conversation feature does not contain any messages in itself. This allows use to create new guides very easy, it also allows use to create an API and allow third party devs to create guides.

Example Guide Doc

Name preferences

Rules:

  • auth requered (yes, no) - is auth reqeied to have this conversation
  • new convo requered (yes, no) - does this guide requer a new conversation or can the messages be sent in the current conversation (dosnt aply if the user is alredy in a new conversation)
  • toppics (auth, preferences)
  • toppic retriction (yes, limited, no) - is the ai allowed to answer non topic related things?
  • triger (intent, condition, CTA) - what will trigger this guide, the user intent in chat, the conditions like first time user, not logged in, etc or a CTA like the user clicked on the avatar.
  • iniciation (user, guide) - this determinse who sends the first message (not sure if its needed as we can likly deterin this by triger)
  • Start (Top, anywhere) - where can the conversation start, it must start from the begining or ai can determin a better message. say a user asks to update thier email, do they need to start at the top of the preferences conversation or can the ai determin to send the email message directly.
  • Steps (strict, dynamic) - determin if you want to allow the ai to determin the best next message or if it should follow the step by step messages strictly like a chat bot.
  • Restar/save (yes, no) - this determins if the conversation is saved and the user can continue in the future or if they should restart each time, e.g. each time a user clicks on thier avatar do they see the chnages made before for the guide starts a new conversation.

Step Messages: - these are messages that are sent in sequence

  • Component(Profile)
  • Text ('who you are', ai) Component(quike options) Action(get user status) Text(insert user staus) puase(wait for user imput)

Free messages - these are messages that are avavle as responces if needed but are not auto sent.​

Here is the complete, production-ready specification template for your Guided Conversation Doc.

This includes your original properties, the infrastructural details required for specific flows (like Onboarding, Auth, or Settings), and an exhaustive real-world example mapping out a Security & Notifications Settings Guide.

Guided Conversation Specification Template

1. Metadata & Control Flags​

These parameters define the environment, security level, and strictness of the guide before a single message is sent.

  • Guide Name (string): The unique identifier for this specific guided workflow.

  • Feature Category (App Intro | Auth | Settings | Feature_Onboarding): Classification used by the system to apply global thematic styling or specific backend data policies.

  • Authentication Required (Yes | No): If Yes, the system must intercept unauthorized requests and route the user to an authentication flow before initializing this guide.

  • Session Isolation (New Conversation | Inline):

  • New Conversation: Clears the thread and opens a fresh canvas (ideal for critical paths like Auth Recovery).

  • Inline: Inject directly into the user's ongoing chat stream (ideal for Settings updates).

  • Trigger Type (Intent | Condition | CTA):

  • Intent: Triggered by AI text processing (e.g., typing "fix my alerts").

  • Condition: System-state evaluations (e.g., is_first_time_user == true).

  • CTA: Physical UI actions (e.g., clicking a button or avatar).

  • Entry Point (Top | Deep Link):

  • Top: Forces execution from Step 1.

  • Deep Link: Allows the AI to evaluate user context and drop them directly into a specific downstream step (e.g., if a user asks specifically to update an email, skip the profile intro steps).

  • Execution Strictness (Strict | Dynamic):

  • Strict: The AI acts as a deterministic state machine, running steps sequentially like a rigid chatbot.

  • Dynamic: The AI is allowed to rephrase text, merge steps if the user answers two questions at once, or use conversational nuance while strictly completing the underlying steps.

  • Scope Lock (Strict | Loose):

  • Strict: Total topical lockdown. If the user asks a tangent question (e.g., "What's the weather?"), the AI must ignore it, execute a polite rejection, and pull them back to the active step.

  • Loose: The AI can address small, relevant clarifying questions about the UI before returning to the flow.

  • Persistence Mode (Save & Resume | Volatile):

  • Save & Resume: Captures the progress. If the user closes the app mid-onboarding, they return exactly where they left off.

  • Volatile: Wipes on exit. If abandoned, the guide must restart from scratch next time.

2. Conversation Lifecycle Hooks​

System tasks triggered behind the scenes at the start or finish of a guide, requiring zero user interaction.

  • On-Enter Action (Endpoint / Macro): Pre-fetches state data, updates analytics, or locks background UI components to focus the user's attention.
  • On-Exit Action (Endpoint / Macro): Commits batch settings to the database, fires completion tracking, or unlocks background UI features.

3. Step Messages & Component Interoperability​

The core sequence. Because your system handles UI components and endpoints natively, each step must explicitly declare what it relies on and what events it listens for.

  • Message Type (Component | Text | Action | Logical_Branch): Defines what the step executes.
  • Content / target (String / Payload): The literal text or the identifier of the component to render.
  • UI Layout State (Standard | Fullscreen | Split_Screen): Controls the layout viewport. For instance, a settings guide might use Split_Screen (chat on the left, actual system settings page updating in real time on the right).
  • Component Event Listener (Event_Name): Specifies the precise UI interaction or hook from a custom component that tells the system: "This step is complete; advance the conversation."
  • Data Slot Mapping (Variable_Name): Captures user input or UI selection and binds it to a temporary variable to feed into the final endpoint.

Full Blueprint Example: "Account Security & Alerts Setup"

Below is a complete, real-world instantiation of a complex Settings/Auth guide utilizing every single flag.

# ==============================================================================
# 1. METADATA & CONTROL FLAGS
# ==============================================================================
Guide_Name: "account_security_alerts_v1"
Feature_Category: "Settings"
Authentication_Required: "Yes"
Session_Isolation: "Inline"
Trigger_Type: "CTA"                  # User clicked "Secure My Account" banner
Entry_Point: "Top"                   # Must execute sequentially
Execution_Strictness: "Dynamic"      # AI can use natural language styling
Scope_Lock: "Strict"                 # Do not allow tangents during security setup
Persistence_Mode: "Save & Resume"    # If they drop off, save their progress

# ==============================================================================
# 2. LIFECYCLE HOOKS
# ==============================================================================
On_Enter_Action: "System.UI.dimBackground(true) && Analytics.track('security_audit_started')"
On_Exit_Action: "System.UI.dimBackground(false) && Analytics.track('security_audit_completed')"

# ==============================================================================
# 3. SEQUENTIAL STEP MESSAGES
# ==============================================================================
Step_Messages:
  - Step: 1
    Type: "Component"
    Target: "ProfileHeaderCard"
    UI_Layout_State: "Standard"
    Context_Injected: ["user.display_name", "user.avatar_url"]
    Event_Listener: "None"            # Immediately proceeds to text line below

  - Step: 2
    Type: "Text"
    Content: "Hey {{user.display_name}}. Let's optimize your security dashboard. First, let's look at your current authentication status."

  - Step: 3
    Type: "Action"
    Target: "/api/v1/user/security-status"
    Output_Variable: "security_payload" # Returns { two_factor_enabled: false }

  - Step: 4
    Type: "Logical_Branch"
    Condition: "if security_payload.two_factor_enabled == true"
    True_Path: "Go to Step 7"          # Skip activation if already on
    False_Path: "Go to Step 5"         # Route to activation

  - Step: 5
    Type: "Component"
    Target: "TwoFactorSetupWidget"
    UI_Layout_State: "Split_Screen"   # Left panel: Chat | Right panel: interactive 2FA setup
    Event_Listener: "2FA_ACTIVATION_SUCCESS"
    Data_Slot_Mapping: "user.security.has_2fa"

  - Step: 6
    Type: "Text"
    Content: "Perfect! Your account is significantly safer now. Let's finish up by configuring your real-time login notifications."

  - Step: 7
    Type: "Component"
    Target: "QuickOptions"
    Props:
      options: ["Push Notifications Only", "Email Alerts Only", "Both Methods", "Turn Off Alerts"]
    UI_Layout_State: "Standard"
    Event_Listener: "OPTION_SELECTED"
    Data_Slot_Mapping: "selected_notification_tier"

  - Step: 8
    Type: "Action"
    Target: "/api/v1/user/update-notification-preferences"
    Payload: { "tier": "{{selected_notification_tier}}" }

  - Step: 9
    Type: "Text"
    Content: "All set! Your notification settings are live and active. Your profile is fully secured."

# ==============================================================================
# 4. FREE MESSAGES (Contextual Edge Cases)
# ==============================================================================
Free_Messages:
  - Scenario: "User expresses anxiety about 2FA locked doors"
    Condition: "User text contains 'lock out' or 'lose phone'"
    Content: "Don't worry! If you lose your phone, we will generate a set of emergency backup codes that you can download and save safely right after activation."
    
  - Scenario: "User attempts a conversational tangent (Scope Lock Intervention)"
    Condition: "Global_Interrupt_Triggered"
    Content: "I want to make sure your security setup finishes correctly so your data stays protected. Let's wrap this up first, and then I can help you with your other questions!"

Reminders​

Links & Resources​