[Weekly Report] Conversation Handler

This workflow manages interactive weekly business report conversations with users, guiding them through profit summaries, debt tracking, and goal setting while adapting to both WhatsApp and SMS channels.

Purpose

No business context provided yet — add a context.md to enrich this documentation.

How It Works

1. Receives conversation input from another workflow containing user message and phone number
2. Fetches user's weekly report data from the database to get profit, sales, and cost information
3. Retrieves user profile including current conversation stage, name, and communication channel preferences
4. Loads credit tracking data if the user has active debt management features
5. Processes the conversation through a state machine that handles different stages of the weekly report flow
6. Updates user's conversation stage in the database to track progress
7. Saves the AI response to chat history for record keeping
8. Returns the formatted message to be sent back to the user

The workflow supports a multi-stage conversation flow including profit summaries, debt analysis, micro-action reviews, and next week's goal setting.

Mermaid Diagram

graph TD
    A[When Executed by Another Workflow] --> B[Fetch Weekly Report]
    B --> C[Fetch User]
    C --> D[Fetch Credit]
    D --> E[State Machine]
    E --> F[Update Stage]
    F --> G[Save to Chat History]
    G --> H[Return Output]

Trigger

Execute Workflow Trigger - This workflow is called by other workflows that handle incoming messages from users. It expects input containing the user's phone number and message content.

Nodes Used

Node Type	Purpose
Execute Workflow Trigger	Receives execution requests from parent workflows
PostgreSQL (3x)	Fetches weekly report data, user profile, and credit information
Code	Implements the conversation state machine logic
PostgreSQL	Updates user's conversation stage
PostgreSQL	Saves AI response to chat history
Set	Formats the final output message

External Services & Credentials Required

• PostgreSQL Database: Requires connection credentials for accessing:
  • weeklyReports table
  • youthEntrepreneursReal table
  • creditTracking table
  • n8n_chat_histories table

Environment Variables

No specific environment variables are required beyond the database connection credentials configured in the PostgreSQL nodes.

Data Flow

Input: - phoneNumber: User's phone number identifier - message: User's response/message content

Output: - output: Formatted message to send back to the user

Internal Data: - Weekly report metrics (sales, costs, profit, trends) - User profile (name, stage, channel preference) - Credit tracking information (if applicable) - Conversation state transitions

Error Handling

• Continue on Error: The "Save to Chat History" node is configured to continue execution even if logging fails
• Error Workflow: The workflow has an error workflow configured (cuHEGQjAfvuGwIOD) to handle unexpected failures
• Data Validation: The state machine includes fallback logic for missing or invalid data
• Safe SQL: Message content is escaped to prevent SQL injection

Known Limitations

• Workflow is currently inactive and needs to be enabled for production use
• Relies on specific database schema and table structures
• State machine logic is tightly coupled to the current conversation flow design
• SMS vs WhatsApp formatting differences require channel detection

Related Workflows

• Parent workflows that trigger this handler (not specified in the current workflow)
• Error handling workflow: cuHEGQjAfvuGwIOD

Setup Instructions

1. Import the workflow into your n8n instance
2. Configure PostgreSQL credentials for all database nodes:
   • Ensure access to weeklyReports, youthEntrepreneursReal, creditTracking, and n8n_chat_histories tables
3. Set up the error workflow referenced in settings if not already present
4. Configure caller policy - currently set to "workflowsFromSameOwner"
5. Test the state machine logic with sample data to ensure proper conversation flow
6. Activate the workflow when ready for production use
7. Set up parent workflows to call this handler with proper input format

The workflow expects to be called by other workflows that handle message routing and should not be triggered directly by external webhooks.