greenflash-onboard-events

Greenflash Business Event Tracking

Read greenflash-config.md from the greenflash skill — the entry skill, installed alongside this one (${CLAUDE_SKILL_DIR}/../greenflash/greenflash-config.md in Claude Code) — for authentication, API patterns, and error handling.

Purpose

This skill extends an existing Greenflash SDK integration to track business events, connecting AI conversations to real outcomes like conversions, upgrades, and churn. Events close the loop between conversation quality and business impact, so you can see which interactions actually drive revenue and which ones lose customers.

Prerequisite: The codebase must already have a working Greenflash integration (client + message logging). If not, run /greenflash:greenflash-onboard first.

Language Detection

Detect the project language:

1. Python — look for existing greenflash imports, greenflash_client.py, or from greenflash import
2. TypeScript — look for existing greenflash imports, greenflash-client.ts, or import Greenflash from 'greenflash'

If an argument is provided, use that.

---

Why Track Events?

• Attribute success to conversations: Link specific AI interactions directly to business outcomes
• Move beyond sentiment scores: Confirm heuristic signals with tangible outcome data
• Find what actually drives results: Identify conversation patterns that lead to conversions, upgrades, or churn

---

When to Send Events

Capture moments that matter — user milestones representing value creation or loss.

Positive Indicators (Success Signals)

• signup_completed, trial_started, task_success
• upgrade_purchased, meeting_booked, lead_converted

Negative Indicators (Friction/Churn Signals)

• cancellation_requested, error_encountered
• workflow_abandoned, refund_requested

Contextual Indicators (Usage Context)

• feature_viewed, step_completed, usage_logged

---

Core Event Fields

Field	Python	TypeScript	Required	Description
Event type	event_type	eventType	Yes	Name of the event (e.g., upgrade)
Product ID	product_id	productId	Yes	Your Greenflash Product ID
Conversation ID	conversation_id	conversationId	No	Link to the conversation that influenced this outcome
Influence	influence	influence	No	positive, negative, or neutral (default)
Value	value	value	Yes	The measurable value (e.g., "149.00")
Value type	value_type	valueType	No	Type of value (currency, count, numeric, text)
Properties	properties	properties	No	Additional context as key-value pairs
Insert ID	insert_id	insertId	No	Unique ID for deduplication

---

Python Implementation

Basic Event (Sync)

client.events.create(
    event_type="upgrade",
    product_id=product_id,
    conversation_id=conversation_id,
    influence="positive",
    value="149.00",
    value_type="currency",
    properties={
        "plan": "pro",
        "billing_cycle": "annual",
    },
)

Basic Event (Async fire-and-forget)

asyncio.create_task(client.events.create(
    event_type="upgrade",
    product_id=product_id,
    conversation_id=conversation_id,
    influence="positive",
    value="149.00",
    value_type="currency",
    properties={
        "plan": "pro",
        "billing_cycle": "annual",
    },
))

Use Case Examples

Customer Support — Post-Chat Upgrade:

client.events.create(
    event_type="upgrade",
    product_id=product_id,
    conversation_id=support_conversation_id,
    influence="positive",
    value="149.00",
    value_type="currency",
    properties={"plan": "pro", "billing_cycle": "annual", "previous_plan": "free"},
)

Customer Support — Cancellation:

client.events.create(
    event_type="cancellation_requested",
    product_id=product_id,
    conversation_id=support_conversation_id,
    influence="negative",
    value="49.00",
    value_type="currency",
    properties={"reason": "too_expensive", "plan": "starter", "months_subscribed": 3},
)

Sales — Meeting Booked:

client.events.create(
    event_type="meeting_booked",
    product_id=product_id,
    conversation_id=outreach_conversation_id,
    influence="positive",
    value="50000",
    value_type="currency",
    properties={"pipeline_stage": "qualification", "engagement_touches": 5},
)

Workflow — Task Success:

client.events.create(
    event_type="task_success",
    product_id=product_id,
    conversation_id=workflow_session_id,
    influence="positive",
    value="1500",
    value_type="numeric",
    properties={"task_type": "data_extraction", "records_processed": 1500, "time_saved_minutes": 45},
)

Workflow — Error:

client.events.create(
    event_type="error_encountered",
    product_id=product_id,
    conversation_id=workflow_session_id,
    influence="negative",
    value="1",
    value_type="numeric",
    properties={"error_type": "validation_failure", "error_message": "Invalid date format in row 42"},
)

Python — Sampling

# Sample 10% of page view events
client.events.create(
    event_type="feature_viewed",
    product_id=product_id,
    sample_rate=0.1,
    value="dashboard",
    value_type="text",
    properties={"feature": "dashboard"},
)

# Always capture critical events
client.events.create(
    event_type="upgrade",
    product_id=product_id,
    force_sample=True,
    influence="positive",
    value="149.00",
    value_type="currency",
)

Python — Idempotency

import uuid

event_insert_id = str(uuid.uuid4())

client.events.create(
    event_type="upgrade",
    product_id=product_id,
    conversation_id=conversation_id,
    influence="positive",
    value="149.00",
    value_type="currency",
    insert_id=event_insert_id,
)

For critical events, generate insert_id before the request and persist it. Retry with the same ID for exactly-once delivery.

---

TypeScript Implementation

Basic Event (Fire-and-forget)

client.events.create({
  eventType: "upgrade",
  productId: productId,
  conversationId: conversationId,
  influence: "positive",
  value: "149.00",
  valueType: "currency",
  properties: {
    plan: "pro",
    billingCycle: "annual",
  },
}).catch(err => console.error('Greenflash event error:', err));

Basic Event (Awaited)

await client.events.create({
  eventType: "upgrade",
  productId: productId,
  conversationId: conversationId,
  influence: "positive",
  value: "149.00",
  valueType: "currency",
  properties: {
    plan: "pro",
    billingCycle: "annual",
  },
});

Use Case Examples

Customer Support — Post-Chat Upgrade:

client.events.create({
  eventType: "upgrade",
  productId: productId,
  conversationId: supportConversationId,
  influence: "positive",
  value: "149.00",
  valueType: "currency",
  properties: { plan: "pro", billingCycle: "annual", previousPlan: "free" },
}).catch(err => console.error('Greenflash event error:', err));

Customer Support — Cancellation:

client.events.create({
  eventType: "cancellation_requested",
  productId: productId,
  conversationId: supportConversationId,
  influence: "negative",
  value: "49.00",
  valueType: "currency",
  properties: { reason: "too_expensive", plan: "starter", monthsSubscribed: 3 },
}).catch(err => console.error('Greenflash event error:', err));

Sales — Meeting Booked:

client.events.create({
  eventType: "meeting_booked",
  productId: productId,
  conversationId: outreachConversationId,
  influence: "positive",
  value: "50000",
  valueType: "currency",
  properties: { pipelineStage: "qualification", engagementTouches: 5 },
}).catch(err => console.error('Greenflash event error:', err));

Workflow — Task Success:

client.events.create({
  eventType: "task_success",
  productId: productId,
  conversationId: workflowSessionId,
  influence: "positive",
  value: "1500",
  valueType: "numeric",
  properties: { taskType: "data_extraction", recordsProcessed: 1500, timeSavedMinutes: 45 },
}).catch(err => console.error('Greenflash event error:', err));

Workflow — Error:

client.events.create({
  eventType: "error_encountered",
  productId: productId,
  conversationId: workflowSessionId,
  influence: "negative",
  value: "1",
  valueType: "numeric",
  properties: { errorType: "validation_failure", errorMessage: "Invalid date format in row 42" },
}).catch(err => console.error('Greenflash event error:', err));

TypeScript — Sampling

// Sample 10% of page view events
client.events.create({
  eventType: "feature_viewed",
  productId: productId,
  sampleRate: 0.1,
  value: "dashboard",
  valueType: "text",
  properties: { feature: "dashboard" },
}).catch(err => console.error('Greenflash event error:', err));

// Always capture critical events
client.events.create({
  eventType: "upgrade",
  productId: productId,
  forceSample: true,
  influence: "positive",
  value: "149.00",
  valueType: "currency",
}).catch(err => console.error('Greenflash event error:', err));

TypeScript — Idempotency

import { randomUUID } from 'crypto';

const eventInsertId = randomUUID();

client.events.create({
  eventType: "upgrade",
  productId: productId,
  conversationId: conversationId,
  influence: "positive",
  value: "149.00",
  valueType: "currency",
  insertId: eventInsertId,
}).catch(err => console.error('Greenflash event error:', err));

---

Linking Events to Conversations

The conversation_id/conversationId field connects business outcomes to AI interactions. Include it when:

• The event happened during an AI session
• The event happened shortly after an AI interaction
• There's a clear causal relationship between conversation and outcome

# Python: Store conversation ID from message logging
conversation_id = response.conversation_id

# Later...
client.events.create(
    event_type="upgrade",
    product_id=product_id,
    conversation_id=conversation_id,
    influence="positive",
    value="149.00",
    value_type="currency",
)

// TypeScript: Store conversation ID from message logging
const conversationId = response.conversationId;

// Later...
client.events.create({
  eventType: "upgrade",
  productId: productId,
  conversationId: conversationId,
  influence: "positive",
  value: "149.00",
  valueType: "currency",
}).catch(err => console.error('Greenflash event error:', err));

---

Integration Checklist

• Identified key business milestones in the application
• Added event tracking at each milestone using client.events.create(...)
• Linked events to conversations by passing conversation_id/conversationId when relevant
• Set appropriate influence (positive, negative, neutral)
• Included value and value_type/valueType for revenue-impacting events
• Added useful properties for deeper analysis
• Used fire-and-forget pattern to avoid blocking
• No disruption to existing message logging behavior

---

What to Deliver

1. Event tracking at key business milestones
2. Proper conversation linking where applicable
3. Correct influence assignment (positive/negative/neutral)
4. Value tracking for revenue-related events
5. No disruption to existing message logging behavior

This closes the loop between conversation quality and business impact, so Greenflash can tell you not just where users struggle but whether those struggles cost you revenue.