📱 From WhatsApp to Web Widgets: Building Consent‑First Chatbots for Health Trends

Health Trends Automation & Hybrid Chatbot Alignment

An integrated view of how a hybrid web + WhatsApp chatbot layer fits into a modular health trends automation backend, using your existing Node.js project structure and services.

Context Folder Layout Chatbot Alignment Chatbot Modules Integration Points Notes

1. Context

In our health trends automation we have not focused well on the area: chatbot, which version, is it imported from eg npmjs library or what?

This original prompt highlights the missing architectural definition of the chatbot layer.

The chatbot becomes the front door to health trends automation: consent capture, intent discovery, follow-ups, and CRM enrichment all flow from this entry point.

2. Project Folder Layout

Root: package.json: Scripts and dependencies. .env.example: Placeholder keys and URLs. prisma/ Prisma schema and migrations. src/ Application source (API, services, utils). scripts/ Seeding and utility CLIs. README.md: Setup and run instructions. health-trend-seller/ 
├─ src/ 
│     ├─ index.js 
│     ├─ config/env.js 
│     ├─ api/  
│     │ ├─ routes/ 
│     │ │ ├─ trends.js 
│     │ │ ├─ contacts.js 
│     │ │ ├─ catalog.js 
│     │ │ ├─ orders.js 
│     │ │ └─ crm.js
│     │ └─ server.js
│     ├─ services/
│     │ ├─ ingest/
│     │ │ ├─ facebook.js 
│     │ │ ├─ twitter.js 
│     │ │ ├─ instagram.js 
│     │ │ └─ linkedin.js
│     │ ├─ scoring/engine.js 
│     │ ├─ crm/hubspot.js 
│     │ ├─ email/sendgrid.js 
│     │ ├─ sms/twilio.js 
│     │ ├─ payments/stripe.js 
│     │ └─ receipts/pdf.js
│     ├─ db/prisma.js 
│     ├─ queue/worker.js 
│     └─ utils/validators.js
├─ prisma/ 
│      ├─ schema.prisma 
│      └─ seed.js 
├─ scripts/
│      ├─ seed-catalog.js 
│      └─ rotate-keys.js
├─ .env.example 
├─ package.json 
└─ README.md

This structure already behaves like a small platform: API routes, service layer, data layer, and utilities are clearly separated.

3. Chatbot Alignment

The hybrid chatbot aligns perfectly with your architecture. It becomes a new interface that talks to your existing modules without requiring restructuring.

The chatbot becomes just another interface — like a mobile app or dashboard — that consumes your existing API and services.

4. Chatbot Modules

4.1 Web Widget

Calls your existing API routes:

• /api/contacts
• /api/crm
• /api/trends
• /api/catalog

4.2 WhatsApp Bot

Uses your services layer:

• SendGrid
• Twilio
• HubSpot
• Scoring Engine
• PDF Receipts

4.3 New Modules to Add

Consent Engine

src/services/consent/
    ├─ capture.js
    ├─ validate.js
    ├─ mapToCRM.js
    └─ timestamp.js

AI Layer

src/services/ai/
    ├─ router.js
    ├─ intent.js
    ├─ summarizer.js
    └─ conversation.js

📂 What the Structure Means

You’re looking at a directory tree (a folder structure) for a new feature called CONSENT ENGINE inside your project.

src/
 └─ services/
     └─ consent/
         ├─ capture.js
         ├─ validate.js
         ├─ mapToCRM.js
         └─ timestamp.js
  

Explanation:

• src/ → the main source code folder.
• services/ → reusable service logic lives here.
• consent/ → a new module dedicated to handling user consent.
• Each .js file is a sub‑module with a specific responsibility.

🧩 Modules Explained

capture.js

Responsible for collecting consent details from user input.

// capture.js
function capture(userInput) {
  return {
    userId: userInput.userId,
    consentType: userInput.consentType,
    consentValue: userInput.consentValue,
    source: userInput.source || 'web_form'
  };
}
module.exports = capture;
  

validate.js

Checks if the consent data is valid and compliant.

// validate.js
function validate(consentData) {
  if (!consentData.userId) return false;
  if (!consentData.consentType) return false;
  if (typeof consentData.consentValue !== 'boolean') return false;

  const allowedTypes = ['email_marketing','sms_notifications','data_sharing'];
  if (!allowedTypes.includes(consentData.consentType)) return false;

  return true;
}
module.exports = validate;
  

timestamp.js

Adds a timestamp for audit trail and compliance.

// timestamp.js
function timestamp(consentData) {
  return {
    ...consentData,
    timestamp: new Date().toISOString()
  };
}
module.exports = timestamp;
  

mapToCRM.js

Integrates consent data into the CRM system.

// mapToCRM.js
const axios = require('axios');

async function mapToCRM(consentData) {
  try {
    const crmPayload = {
      id: consentData.userId,
      consentType: consentData.consentType,
      consentValue: consentData.consentValue,
      timestamp: consentData.timestamp
    };

    const response = await axios.post(
      'https://crm.example.com/api/consents',
      crmPayload,
      {
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${process.env.CRM_API_TOKEN}`
        }
      }
    );

    return { success: true, data: response.data };
  } catch (error) {
    console.error('CRM mapping failed:', error.message);
    return { success: false, error: error.message };
  }
}
module.exports = mapToCRM;
  

⚙️ Orchestration: index.js

This file orchestrates all modules into one clean workflow.

// index.js
const capture = require('./capture');
const validate = require('./validate');
const mapToCRM = require('./mapToCRM');
const timestamp = require('./timestamp');

async function processConsent(userInput) {
  const consentData = capture(userInput);

  const isValid = validate(consentData);
  if (!isValid) throw new Error('Consent is invalid or incomplete');

  const stampedConsent = timestamp(consentData);
  await mapToCRM(stampedConsent);

  return stampedConsent;
}

module.exports = { processConsent };
  

🖥️ Sample Run

Demonstrates the Consent Engine pipeline end‑to‑end with fake user input.

// testConsentEngine.js
const { processConsent } = require('./src/services/consent/index');

const fakeUserInput = {
  userId: 'user123',
  consentType: 'email_marketing',
  consentValue: true,
  source: 'signup_form'
};

(async () => {
  try {
    const result = await processConsent(fakeUserInput);
    console.log('Final consent object:', result);
  } catch (error) {
    console.error('Consent processing failed:', error.message);
  }
})();
  

Example Output

{
  "userId": "user123",
  "consentType": "email_marketing",
  "consentValue": true,
  "source": "signup_form",
  "timestamp": "2025-12-21T18:34:00.123Z"
}
  

💡 Notes & Callouts

Each module is kept focused and reusable. If rules or integrations change, you only update the relevant file.

• Modularity: Easier to maintain and extend.
• Audit Trail: Timestamp ensures compliance.
• Integration: CRM mapping connects consent data to business systems.

5. Integration Points

5.1 API Backbone

Your existing routes already support chatbot needs.

5.2 New Chatbot Route

src/api/routes/chatbot.js

5.3 Queue Worker

Supports async chatbot tasks like reminders and follow-ups.

6. Notes & Next Steps

Your architecture is already modular.
Your services layer is rich and reusable.
Your API routes match chatbot needs.
Only minimal additions are required.

Next Step: Formalise the consent‑capture flow and chatbot API contracts.

1. Formalizing the Consent‑Capture Flow

Since the chatbot will likely handle sensitive data, the consent flow needs to be bulletproof but low‑friction.

The Trigger: Before the first prompt is processed, the chatbot checks a has_consented flag via your API.
The Payload: If false, the API sends a structured "Consent Component" instead of a text bubble.
The Storage: Once the user clicks "I Agree," the chatbot hits a POST /consent endpoint that updates your database with a timestamp and version ID of the terms.

2. Chatbot API Contracts

To keep the frontend and backend decoupled, define a strict JSON contract.

Request Interface

{
  "conversation_id": "uuid-123",
  "message": "I need help with X",
  "metadata": { "user_id": "user-456", "platform": "web" }
}

Response Interface

{
  "status": "success",
  "reply_type": "text | options | markdown",
  "content": "Here is what I found...",
  "suggestions": ["Tell me more", "Contact support"]
}

3. Immediate Priorities

• State Management: Ensure your API can handle conversation_id to maintain context.
• Error Handling: Define graceful fallback messages when services fail.
• Webhook/Polling: Decide between REST polling or Webhook for long‑running tasks.

Perfect. Let’s get these contracts defined so you can hand them off to the frontend or start implementation.

Consent‑Capture API Contract

This ensures a legal audit trail before the chatbot processes user data.

Endpoint: POST /api/v1/consent

Field | Type   | Description
userId | UUID   | Unique identifier for the user
consentType | String | e.g., "data_processing" or "marketing"
version | String | Terms of Service version accepted
source | String | Where consent happened (e.g., "chat_v1")

Success Response (201 Created)

{
  "status": "success",
  "data": {
    "consentId": "uuid-987",
    "timestamp": "2024-05-20T10:00:00Z"
  }
}

Chatbot Message API Contract

Endpoint: POST /api/v1/chat/message

Request Body

{
  "sessionId": "uuid-session-123",
  "message": "I need to update my billing address.",
  "context": { "currentPage": "/dashboard/settings", "authenticated": true }
}

Response Body

{
  "messageId": "msg-555",
  "replyType": "options",
  "content": "I can help with that. Which address would you like to update?",
  "options": [
    { "label": "Home Address", "value": "home" },
    { "label": "Work Address", "value": "work" }
  ],
  "metadata": { "tokensUsed": 45, "intentDetected": "billing_update" }
}

Logical Flow

Handshake: Frontend sends user message.
Gatekeeper: Service layer checks for valid consent.
Route: If no consent → return replyType: "consent_required". If consented → forward to LLM.
Response: Format result according to contract and return to UI.

Implementation: Gatekeeper Service

async function handleUserMessage(payload) {
  const { userId, message, sessionId } = payload;

  // 1. Consent Check
  const hasConsented = await consentService.verifyUserConsent(userId, 'chat_data_v1');
  if (!hasConsented) {
    return {
      replyType: "consent_required",
      content: "Before we start, I need your permission to process this chat.",
      metadata: { requiredConsentVersion: "v1.0" }
    };
  }

  // 2. Process via Service Layer
  const response = await aiService.generateResponse(message, sessionId);

  // 3. Return formatted contract
  return {
    messageId: generateUuid(),
    replyType: "text",
    content: response.text,
    metadata: { intent: response.intent }
  };
}

Consent Service Layer

// services/consentService.js
const db = require('../models');

const ConsentService = {
  async checkStatus(userId, consentKey) {
    const record = await db.UserConsent.findFirst({
      where: { userId, consentKey, status: true }
    });
    return !!record;
  },

  async grant(userId, consentKey, metadata) {
    return await db.UserConsent.create({
      data: {
        userId,
        consentKey,
        status: true,
        ipAddress: metadata.ip,
        version: metadata.version,
        timestamp: new Date()
      }
    });
  }
};

module.exports = ConsentService;

Gatekeeper Middleware

// middleware/gatekeeper.js
const ConsentService = require('../services/consentService');

const consentGatekeeper = async (req, res, next) => {
  const { userId } = req.body;
  const REQUIRED_CONSENT = 'chat_v1';

  const hasConsented = await ConsentService.checkStatus(userId, REQUIRED_CONSENT);
  if (!hasConsented) {
    return res.status(200).json({
      replyType: "consent_required",
      content: "To give you the best experience, I need your permission to process chat data.",
      metadata: { consentKey: REQUIRED_CONSENT, termsLink: "https://yourdomain.com/terms" }
    });
  }
  next();
};

module.exports = consentGatekeeper;

Applying to API Route

// routes/chatRoutes.js
const express = require('express');
const router = express.Router();
const gatekeeper = require('../middleware/gatekeeper');
const chatController = require('../controllers/chatController');

router.post('/message', gatekeeper, chatController.handleMessage);

module.exports = router;

Real‑world flow:
User sends message → Middleware checks consent → If missing, returns consent_required → Frontend shows "I Agree" → Consent stored → Message re‑sent → Chat logic proceeds.

Frontend Component Logic

To keep your architecture modular, the chatbot UI should be data-driven. The UI reacts to replyType sent by your backend rather than hardcoded routes.

Here is how to implement the handler for the consent_required contract in a modern React/JavaScript environment.

1. The Chat Interface Logic

This function processes the backend response. If it sees the consent flag, it injects a special "Consent Card" into the chat feed.

// components/ChatWindow.js
const handleSendMessage = async (userText) => {
  // 1. Add user message to UI
  appendMessage({ sender: 'user', text: userText });

  // 2. Hit your protected API
  const response = await api.post('/chat/message', { message: userText });
  const data = response.data;

  // 3. Handle the Gatekeeper's response
  if (data.replyType === 'consent_required') {
    renderConsentUI(data.metadata); // Trigger the consent card
    return;
  }

  // 4. Otherwise, render standard response
  renderBotReply(data.content);
};

2. The Consent UI Component

This component captures the user's click and calls your new POST /consent endpoint.

// components/ConsentCard.js
const ConsentCard = ({ metadata, onAgreed }) => {
  const handleAccept = async () => {
    await api.post('/api/v1/consent', {
      consentKey: metadata.consentKey,
      version: metadata.termsVersion,
      agreed: true
    });
    onAgreed(); // Retry the message
  };

  return (
    <div className="consent-card">
      <p>We need your permission to process this chat.</p>
      <a href={metadata.termsLink} target="_blank">Read Privacy Policy</a>
      <button onClick={handleAccept}>I Agree & Continue</button>
    </div>
  );
};

3. The "Retry" Pattern

When the user clicks "Agree," the chatbot should automatically resend the last message so they don’t have to re-type it.

Example Flow:
User types: "Check my balance."
System shows Consent Card.
User clicks "Agree."
System fires Consent API, then re-triggers the "Check my balance" request.

Summary of the Modular Flow

Layer           Responsibility
Database        Stores timestamp and version of consent
Service Layer   Provides checkStatus() and grant() methods
API Gatekeeper  Intercepts requests, returns consent_required if needed
Frontend UI     Renders ConsentCard when replyType = consent_required

System Prompt & Guardrails

The System Prompt is the "brain" of your service layer. Store it in a configuration file or dedicated promptService.

1. Persona & Guardrails Prompt

## ROLE
You are the [Project Name] Assistant. Your goal is to provide helpful, concise, and accurate technical support.

## STYLE & TONE
- Professional yet Peer-like
- Concise, bullet points preferred
- Use Markdown for formatting
- Use LaTeX only for formulas (e.g., $E=mc^2$)

## CONSTRAINTS & GUARDRAILS
1. Scope: Only answer within project scope.
2. Privacy: Never reveal internal IDs or private data.
3. Honesty: Admit when you don't know; escalate to human support.
4. Consent: Assume consent already granted via Gatekeeper.

## SERVICE LAYER CAPABILITIES
- Account status and billing
- Technical troubleshooting
- Dashboard navigation

2. Dynamic Context Injection

// Example Service Logic
const systemPrompt = `You are the [Project] Assistant. Current User: ${user.name}. Plan: ${user.subscription}.`;

const messages = [
  { role: "system", content: systemPrompt },
  { role: "user", content: userInput }
];

3. Handling Structured Output

Instruct the LLM to return ACTION tags (e.g., [UPDATE_EMAIL]) so the frontend can trigger UI forms automatically.

Deployment & Testing Strategy

1. Integration Test Suite

• Path A: New user → Expect consent_required, ensure LLM not called.
• Path B: User with consent → Expect text, ensure LLM triggered.

2. Deployment Checklist

Environment & Security:
[ ] CORS whitelist
[ ] Rate limiting
[ ] Encryption of consent records

Frontend & UX:
[ ] Typing indicator
[ ] Persistent sessionId

3. Monitoring & Analytics

• Consent Drop-off Rate: Track how many users abandon at consent_required.
• Gatekeeper Latency: Consent check should add < 50ms.

Final Milestone Reached 🚀
Your architecture is now robust, compliant, and ready for users.

Hybrid chatbot alignment for health trends automation · HTML5, structured navigation, and architecture‑grade clarity.

Back to top © 2025 Peter M. Mutiti

Author: Peter M. Mutiti | Investigative Journalist & Civic Technologist

MIT License © 2025 Peter M. Mutiti · View License