claude-flow-novice 2.14.37 → 2.15.1

package/claude-assets/cfn-extras/skills/marketing/cfn-marketing-chatbot-conversations/SKILL.md

@@ -0,0 +1,340 @@
+# CFN Marketing Chatbot Conversations Skill
+
+**Version:** 1.0.0
+**Status:** Active
+**Owner:** CFN Marketing Team
+**Last Updated:** 2025-10-29
+
+## Overview
+
+Manages chatbot conversations for lead qualification, demo scheduling, and human escalation using n8n workflow automation.
+
+## Purpose
+
+Enable automated customer conversations through chatbot interfaces (Intercom, Drift) with BANT-based lead qualification, appointment scheduling, and seamless human handoff.
+
+## Use Cases
+
+1. **Lead Qualification**: Score leads using BANT framework (60-point threshold)
+2. **Demo Scheduling**: Book appointments based on qualified lead status
+3. **Human Escalation**: Transfer complex conversations to human agents
+4. **Conversation Tracking**: Retrieve and analyze conversation history
+5. **Real-time Engagement**: Send context-aware messages (<2 seconds response time)
+
+## Operations
+
+### 1. send-message.sh
+
+**Purpose:** Send chatbot message to visitor
+
+**Parameters:**
+- `--visitor-id` (required): Unique visitor identifier
+- `--message` (required): Message content
+- `--platform` (required): Chatbot platform (intercom|drift)
+- `--context` (optional): Conversation context JSON
+
+**Exit Codes:**
+- 0: Success
+- 1: Validation error (missing parameters)
+- 2: API error (network, authentication)
+- 3: Platform error (visitor not found)
+
+**Example:**
+```bash
+./operations/send-message.sh \
+  --visitor-id "vis_12345" \
+  --message "Hello! How can I help you today?" \
+  --platform "intercom" \
+  --context '{"page": "/pricing", "source": "website"}'
+```
+
+**Response:**
+```json
+{
+  "message_id": "msg_67890",
+  "visitor_id": "vis_12345",
+  "sent_at": "2025-10-29T14:30:00Z",
+  "status": "delivered"
+}
+```
+
+### 2. get-conversation-history.sh
+
+**Purpose:** Retrieve conversation transcript
+
+**Parameters:**
+- `--visitor-id` (required): Unique visitor identifier
+- `--platform` (required): Chatbot platform
+- `--limit` (optional): Maximum messages to retrieve (default: 50)
+- `--since` (optional): ISO 8601 timestamp for filtering
+
+**Exit Codes:**
+- 0: Success
+- 1: Validation error
+- 2: API error
+- 3: Visitor not found
+
+**Example:**
+```bash
+./operations/get-conversation-history.sh \
+  --visitor-id "vis_12345" \
+  --platform "intercom" \
+  --limit 20
+```
+
+**Response:**
+```json
+{
+  "visitor_id": "vis_12345",
+  "messages": [
+    {
+      "id": "msg_1",
+      "sender": "bot",
+      "text": "Hello! How can I help you today?",
+      "timestamp": "2025-10-29T14:30:00Z"
+    },
+    {
+      "id": "msg_2",
+      "sender": "visitor",
+      "text": "I need pricing information",
+      "timestamp": "2025-10-29T14:31:00Z"
+    }
+  ],
+  "total_messages": 12
+}
+```
+
+### 3. qualify-lead.sh
+
+**Purpose:** Score lead using BANT framework
+
+**Parameters:**
+- `--visitor-id` (required): Unique visitor identifier
+- `--budget` (required): Budget indicator (0-40 points)
+- `--authority` (required): Authority indicator (0-20 points)
+- `--need` (required): Need indicator (0-20 points)
+- `--timeline` (required): Timeline indicator (0-20 points)
+
+**BANT Scoring:**
+- **Budget** (40 points max): Financial capacity
+  - 40: Budget confirmed and approved
+  - 30: Budget range discussed
+  - 20: Budget awareness shown
+  - 10: Budget concerns mentioned
+  - 0: No budget discussion
+- **Authority** (20 points max): Decision-making power
+  - 20: C-level or final decision maker
+  - 15: Manager with approval authority
+  - 10: Influencer in decision process
+  - 5: Individual contributor
+  - 0: Unknown authority level
+- **Need** (20 points max): Problem severity
+  - 20: Critical pain point identified
+  - 15: Significant need expressed
+  - 10: Moderate interest shown
+  - 5: Exploratory discussion
+  - 0: No clear need
+- **Timeline** (20 points max): Purchase urgency
+  - 20: Immediate need (within 1 month)
+  - 15: Short-term (1-3 months)
+  - 10: Medium-term (3-6 months)
+  - 5: Long-term (6+ months)
+  - 0: No timeline mentioned
+
+**Qualification Threshold:** 60 points
+
+**Exit Codes:**
+- 0: Success (lead scored)
+- 1: Validation error
+- 2: API error
+- 3: Visitor not found
+
+**Example:**
+```bash
+./operations/qualify-lead.sh \
+  --visitor-id "vis_12345" \
+  --budget 30 \
+  --authority 20 \
+  --need 15 \
+  --timeline 10
+```
+
+**Response:**
+```json
+{
+  "visitor_id": "vis_12345",
+  "qualified": true,
+  "score": 75,
+  "tier": "MQL",
+  "breakdown": {
+    "budget": 30,
+    "authority": 20,
+    "need": 15,
+    "timeline": 10
+  },
+  "recommendation": "Schedule demo immediately"
+}
+```
+
+### 4. schedule-demo.sh
+
+**Purpose:** Book demo appointment
+
+**Parameters:**
+- `--visitor-id` (required): Unique visitor identifier
+- `--email` (required): Contact email
+- `--preferred-date` (required): ISO 8601 date
+- `--timezone` (required): IANA timezone (e.g., America/New_York)
+- `--notes` (optional): Additional context
+
+**Exit Codes:**
+- 0: Success
+- 1: Validation error
+- 2: API error
+- 3: No available slots
+
+**Example:**
+```bash
+./operations/schedule-demo.sh \
+  --visitor-id "vis_12345" \
+  --email "contact@example.com" \
+  --preferred-date "2025-11-05T14:00:00" \
+  --timezone "America/New_York" \
+  --notes "Interested in enterprise plan"
+```
+
+**Response:**
+```json
+{
+  "appointment_id": "apt_78901",
+  "visitor_id": "vis_12345",
+  "scheduled_at": "2025-11-05T14:00:00-05:00",
+  "calendar_link": "https://calendly.com/demo/apt_78901",
+  "confirmation_sent": true
+}
+```
+
+### 5. transfer-to-human.sh
+
+**Purpose:** Escalate conversation to human agent
+
+**Parameters:**
+- `--visitor-id` (required): Unique visitor identifier
+- `--platform` (required): Chatbot platform
+- `--reason` (required): Escalation reason
+- `--priority` (optional): Priority level (low|medium|high, default: medium)
+
+**Exit Codes:**
+- 0: Success
+- 1: Validation error
+- 2: API error
+- 3: No agents available
+
+**Example:**
+```bash
+./operations/transfer-to-human.sh \
+  --visitor-id "vis_12345" \
+  --platform "intercom" \
+  --reason "Complex pricing question" \
+  --priority "high"
+```
+
+**Response:**
+```json
+{
+  "transfer_id": "trf_45678",
+  "visitor_id": "vis_12345",
+  "agent_id": "agt_111",
+  "agent_name": "Sarah Johnson",
+  "transferred_at": "2025-10-29T14:35:00Z",
+  "eta_minutes": 2
+}
+```
+
+## Environment Variables
+
+```bash
+# Required
+N8N_BASE_URL=https://n8n.example.com
+N8N_API_KEY=n8n_api_key_xxx
+
+# Platform-specific
+INTERCOM_ACCESS_TOKEN=intercom_token_xxx
+DRIFT_API_TOKEN=drift_token_xxx
+```
+
+## Performance Requirements
+
+- **Message Delivery:** <2 seconds
+- **Lead Qualification:** <1 second (local calculation)
+- **History Retrieval:** <3 seconds
+- **Demo Scheduling:** <5 seconds
+- **Human Transfer:** <2 seconds
+
+## Error Handling
+
+All operations return standardized JSON error responses:
+
+```json
+{
+  "error": "Visitor not found",
+  "code": "VISITOR_NOT_FOUND",
+  "timestamp": "2025-10-29T14:30:00Z",
+  "visitor_id": "vis_12345"
+}
+```
+
+## Integration Points
+
+- **n8n Workflows:** Chatbot message webhook triggers
+- **CRM Systems:** Lead qualification sync
+- **Calendar Systems:** Demo scheduling (Calendly, Google Calendar)
+- **Support Platforms:** Human transfer (Intercom, Drift)
+- **Analytics:** Conversation tracking and scoring
+
+## Testing
+
+```bash
+# Test message sending
+./operations/send-message.sh \
+  --visitor-id "test_visitor" \
+  --message "Test message" \
+  --platform "intercom"
+
+# Test BANT qualification
+./operations/qualify-lead.sh \
+  --visitor-id "test_visitor" \
+  --budget 40 \
+  --authority 20 \
+  --need 20 \
+  --timeline 15
+# Expected: qualified=true, score=95, tier=MQL
+
+# Test demo scheduling
+./operations/schedule-demo.sh \
+  --visitor-id "test_visitor" \
+  --email "test@example.com" \
+  --preferred-date "2025-11-01T10:00:00" \
+  --timezone "America/Los_Angeles"
+```
+
+## Maintenance
+
+- **Log Rotation:** Conversation logs rotated daily
+- **Performance Monitoring:** Response time alerts (<2 seconds)
+- **BANT Calibration:** Review scoring threshold quarterly
+- **Platform Updates:** Monitor Intercom/Drift API changes
+
+## Related Skills
+
+- `cfn-marketing-email-campaigns`: Email follow-up for qualified leads
+- `cfn-marketing-sms-campaigns`: SMS notifications for scheduled demos
+- `cfn-marketing-analytics-reporting`: Conversation performance analytics
+- `cfn-marketing-crm-integration`: Lead sync to CRM
+
+## References
+
+- [Intercom API Documentation](https://developers.intercom.com/)
+- [Drift API Documentation](https://devdocs.drift.com/)
+- [BANT Framework Guide](https://www.salesforce.com/resources/articles/bant/)
+- [n8n Template #3558](https://n8n.io/workflows/3558)

package/claude-assets/cfn-extras/skills/marketing/cfn-marketing-chatbot-conversations/operations/get-conversation-history.sh

@@ -0,0 +1,121 @@
+#!/bin/bash
+# CFN Marketing Chatbot Conversations - Get Conversation History Operation
+# Version: 1.0.0
+# Purpose: Retrieve conversation transcript
+
+set -euo pipefail
+
+# Parse arguments
+VISITOR_ID=""
+PLATFORM=""
+LIMIT=50
+SINCE=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --visitor-id)
+      VISITOR_ID="$2"
+      shift 2
+      ;;
+    --platform)
+      PLATFORM="$2"
+      shift 2
+      ;;
+    --limit)
+      LIMIT="$2"
+      shift 2
+      ;;
+    --since)
+      SINCE="$2"
+      shift 2
+      ;;
+    *)
+      echo '{"error": "Unknown parameter: '$1'", "code": "INVALID_PARAMETER"}' >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Validate required parameters
+if [[ -z "$VISITOR_ID" ]]; then
+  echo '{"error": "Missing required parameter: --visitor-id", "code": "MISSING_PARAMETER"}' >&2
+  exit 1
+fi
+
+if [[ -z "$PLATFORM" ]]; then
+  echo '{"error": "Missing required parameter: --platform", "code": "MISSING_PARAMETER"}' >&2
+  exit 1
+fi
+
+# Validate platform
+if [[ "$PLATFORM" != "intercom" && "$PLATFORM" != "drift" ]]; then
+  echo '{"error": "Invalid platform. Must be intercom or drift", "code": "INVALID_PLATFORM"}' >&2
+  exit 1
+fi
+
+# Validate limit
+if ! [[ "$LIMIT" =~ ^[0-9]+$ ]] || [[ "$LIMIT" -lt 1 ]] || [[ "$LIMIT" -gt 500 ]]; then
+  echo '{"error": "Invalid limit. Must be between 1 and 500", "code": "INVALID_LIMIT"}' >&2
+  exit 1
+fi
+
+# Validate environment variables
+if [[ -z "${N8N_BASE_URL:-}" ]]; then
+  echo '{"error": "Environment variable N8N_BASE_URL not set", "code": "MISSING_ENV_VAR"}' >&2
+  exit 2
+fi
+
+if [[ -z "${N8N_API_KEY:-}" ]]; then
+  echo '{"error": "Environment variable N8N_API_KEY not set", "code": "MISSING_ENV_VAR"}' >&2
+  exit 2
+fi
+
+# Build query parameters
+QUERY_PARAMS="visitor_id=${VISITOR_ID}&platform=${PLATFORM}&limit=${LIMIT}"
+if [[ -n "$SINCE" ]]; then
+  QUERY_PARAMS="${QUERY_PARAMS}&since=${SINCE}"
+fi
+
+# Retrieve conversation history via n8n webhook
+RESPONSE=$(curl -s -w "\n%{http_code}" \
+  -X GET \
+  -H "X-N8N-API-KEY: ${N8N_API_KEY}" \
+  "${N8N_BASE_URL}/webhook/chatbot/conversation-history?${QUERY_PARAMS}" 2>&1) || {
+  echo '{"error": "Network error: Failed to connect to n8n", "code": "NETWORK_ERROR"}' >&2
+  exit 2
+}
+
+HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
+BODY=$(echo "$RESPONSE" | sed '$d')
+
+# Handle HTTP errors
+if [[ "$HTTP_CODE" -ge 400 ]]; then
+  if [[ "$HTTP_CODE" -eq 404 ]]; then
+    echo '{"error": "Visitor not found", "code": "VISITOR_NOT_FOUND", "visitor_id": "'"$VISITOR_ID"'"}' >&2
+    exit 3
+  elif [[ "$HTTP_CODE" -eq 401 ]]; then
+    echo '{"error": "Authentication failed", "code": "AUTH_ERROR"}' >&2
+    exit 2
+  else
+    ERROR_MSG=$(echo "$BODY" | jq -r '.error // "Unknown API error"' 2>/dev/null || echo "Unknown API error")
+    echo '{"error": "'"$ERROR_MSG"'", "code": "API_ERROR", "http_code": '$HTTP_CODE'}' >&2
+    exit 2
+  fi
+fi
+
+# Parse response
+if ! echo "$BODY" | jq empty 2>/dev/null; then
+  echo '{"error": "Invalid JSON response from API", "code": "INVALID_RESPONSE"}' >&2
+  exit 2
+fi
+
+# Return conversation history
+echo "$BODY" | jq \
+  --arg visitor_id "$VISITOR_ID" \
+  '{
+    visitor_id: $visitor_id,
+    messages: (.messages // []),
+    total_messages: (.total_messages // (.messages | length))
+  }'
+
+exit 0

package/claude-assets/cfn-extras/skills/marketing/cfn-marketing-chatbot-conversations/operations/qualify-lead.sh

@@ -0,0 +1,156 @@
+#!/bin/bash
+# CFN Marketing Chatbot Conversations - Qualify Lead Operation
+# Version: 1.0.0
+# Purpose: Score lead using BANT framework
+
+set -euo pipefail
+
+# Parse arguments
+VISITOR_ID=""
+BUDGET_SCORE=0
+AUTHORITY_SCORE=0
+NEED_SCORE=0
+TIMELINE_SCORE=0
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --visitor-id)
+      VISITOR_ID="$2"
+      shift 2
+      ;;
+    --budget)
+      BUDGET_SCORE="$2"
+      shift 2
+      ;;
+    --authority)
+      AUTHORITY_SCORE="$2"
+      shift 2
+      ;;
+    --need)
+      NEED_SCORE="$2"
+      shift 2
+      ;;
+    --timeline)
+      TIMELINE_SCORE="$2"
+      shift 2
+      ;;
+    *)
+      echo '{"error": "Unknown parameter: '$1'", "code": "INVALID_PARAMETER"}' >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Validate required parameters
+if [[ -z "$VISITOR_ID" ]]; then
+  echo '{"error": "Missing required parameter: --visitor-id", "code": "MISSING_PARAMETER"}' >&2
+  exit 1
+fi
+
+# Validate score ranges
+if ! [[ "$BUDGET_SCORE" =~ ^[0-9]+$ ]] || [[ "$BUDGET_SCORE" -lt 0 ]] || [[ "$BUDGET_SCORE" -gt 40 ]]; then
+  echo '{"error": "Invalid budget score. Must be between 0 and 40", "code": "INVALID_BUDGET"}' >&2
+  exit 1
+fi
+
+if ! [[ "$AUTHORITY_SCORE" =~ ^[0-9]+$ ]] || [[ "$AUTHORITY_SCORE" -lt 0 ]] || [[ "$AUTHORITY_SCORE" -gt 20 ]]; then
+  echo '{"error": "Invalid authority score. Must be between 0 and 20", "code": "INVALID_AUTHORITY"}' >&2
+  exit 1
+fi
+
+if ! [[ "$NEED_SCORE" =~ ^[0-9]+$ ]] || [[ "$NEED_SCORE" -lt 0 ]] || [[ "$NEED_SCORE" -gt 20 ]]; then
+  echo '{"error": "Invalid need score. Must be between 0 and 20", "code": "INVALID_NEED"}' >&2
+  exit 1
+fi
+
+if ! [[ "$TIMELINE_SCORE" =~ ^[0-9]+$ ]] || [[ "$TIMELINE_SCORE" -lt 0 ]] || [[ "$TIMELINE_SCORE" -gt 20 ]]; then
+  echo '{"error": "Invalid timeline score. Must be between 0 and 20", "code": "INVALID_TIMELINE"}' >&2
+  exit 1
+fi
+
+# Calculate total BANT score
+TOTAL_SCORE=$((BUDGET_SCORE + AUTHORITY_SCORE + NEED_SCORE + TIMELINE_SCORE))
+THRESHOLD=60
+
+# Determine qualification status
+QUALIFIED="false"
+TIER="Unqualified"
+RECOMMENDATION="Continue nurturing"
+
+if [[ "$TOTAL_SCORE" -ge 80 ]]; then
+  QUALIFIED="true"
+  TIER="Hot Lead"
+  RECOMMENDATION="Schedule demo immediately - high priority"
+elif [[ "$TOTAL_SCORE" -ge "$THRESHOLD" ]]; then
+  QUALIFIED="true"
+  TIER="MQL"
+  RECOMMENDATION="Schedule demo within 24-48 hours"
+elif [[ "$TOTAL_SCORE" -ge 40 ]]; then
+  QUALIFIED="false"
+  TIER="Warm Lead"
+  RECOMMENDATION="Continue conversation to gather more information"
+else
+  QUALIFIED="false"
+  TIER="Cold Lead"
+  RECOMMENDATION="Add to nurture campaign"
+fi
+
+# Generate detailed recommendations based on weak areas
+IMPROVEMENTS=()
+
+if [[ "$BUDGET_SCORE" -lt 20 ]]; then
+  IMPROVEMENTS+=("Discuss budget ranges and ROI")
+fi
+
+if [[ "$AUTHORITY_SCORE" -lt 10 ]]; then
+  IMPROVEMENTS+=("Identify decision maker and approval process")
+fi
+
+if [[ "$NEED_SCORE" -lt 10 ]]; then
+  IMPROVEMENTS+=("Clarify pain points and business impact")
+fi
+
+if [[ "$TIMELINE_SCORE" -lt 10 ]]; then
+  IMPROVEMENTS+=("Understand urgency and implementation timeline")
+fi
+
+# Build improvements JSON array
+IMPROVEMENTS_JSON="[]"
+if [[ ${#IMPROVEMENTS[@]} -gt 0 ]]; then
+  IMPROVEMENTS_JSON=$(printf '%s\n' "${IMPROVEMENTS[@]}" | jq -R . | jq -s .)
+fi
+
+# Store qualification in Redis (optional - for analytics)
+if command -v redis-cli &> /dev/null; then
+  redis-cli SET "chatbot:qualification:${VISITOR_ID}" "$TOTAL_SCORE" EX 2592000 > /dev/null 2>&1 || true
+  redis-cli SET "chatbot:tier:${VISITOR_ID}" "$TIER" EX 2592000 > /dev/null 2>&1 || true
+fi
+
+# Return qualification result
+jq -n \
+  --arg visitor_id "$VISITOR_ID" \
+  --argjson qualified "$QUALIFIED" \
+  --arg score "$TOTAL_SCORE" \
+  --arg tier "$TIER" \
+  --arg budget "$BUDGET_SCORE" \
+  --arg authority "$AUTHORITY_SCORE" \
+  --arg need "$NEED_SCORE" \
+  --arg timeline "$TIMELINE_SCORE" \
+  --arg recommendation "$RECOMMENDATION" \
+  --argjson improvements "$IMPROVEMENTS_JSON" \
+  '{
+    visitor_id: $visitor_id,
+    qualified: $qualified,
+    score: ($score | tonumber),
+    tier: $tier,
+    breakdown: {
+      budget: ($budget | tonumber),
+      authority: ($authority | tonumber),
+      need: ($need | tonumber),
+      timeline: ($timeline | tonumber)
+    },
+    recommendation: $recommendation,
+    improvements: $improvements
+  }'
+
+exit 0