Business Events (Python)

System prompt for coding agents to add business event tracking to an existing Python SDK integration. Copy and paste the content of this page into your coding assistant.

Using a Skills-compatible agent like Claude Code? The Greenflash agent skill handles this automatically. Run /greenflash-onboard-events instead of copying this prompt.

Add Business Event Tracking to Our Greenflash Integration

You are a coding agent tasked with extending our existing Greenflash Python SDK integration to track business events. We already have message logging working. Your goal is to add event tracking so that Greenflash can connect AI interactions to real business outcomes like conversions, upgrades, and churn.

---

High-Level Objective

Extend the current implementation to:

1. Track business events that represent meaningful user milestones
2. Link events to conversations when the outcome relates to an AI interaction
3. Assign influence and value to quantify the business impact
4. Use the correct Python SDK syntax

Reference: The full documentation for the Events API is available at: https://docs.greenflash.ai/features/events

---

Why Track Events?

Events close the loop between AI interactions and business outcomes. While Greenflash already analyzes conversation quality and sentiment, events provide the ground truth:

• Attribute Success: Link specific AI responses directly to business outcomes like upgrades or purchases
• Validate Quality: Confirm heuristic signals (like sentiment) with tangible outcome data
• Deepen Insights: Train Greenflash to identify conversation patterns that drive real-world results

---

When to Send Events

Capture moments that matter. Send an event whenever a user reaches a milestone that represents 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	Type	Required	Description
event_type	string	Yes	The name of the event (e.g., upgrade, cancellation_requested)
product_id	uuid	Yes	Your Greenflash Product ID
conversation_id	uuid	No	Link to the conversation that influenced this outcome
influence	enum	No	positive, negative, or neutral (defaults to neutral)
value	string	Yes	The measurable value (e.g., "149.00")
value_type	string	No	The type of value (e.g., currency, count)
properties	dict	No	Additional context as key-value pairs
insert_id	string	No	Unique ID for deduplication

---

Basic Event Tracking

Sync Example

# Track a successful upgrade after a support conversation
client.events.create(
    event_type="upgrade",
    product_id=product_id,
    conversation_id=conversation_id,  # Link to the AI interaction
    influence="positive",
    value="149.00",
    value_type="currency",
    properties={
        "plan": "pro",
        "billing_cycle": "annual",
    },
)

Async (Fire-and-Forget) Example

# Fire-and-forget so we don't block the main flow
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",
    },
))

---

Event Examples by Use Case

Customer Support: Post-Chat Upgrade

# User upgraded to Pro after a helpful support chat
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 Request

# User requested cancellation during a support chat
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

# AI-assisted outreach led to a booked meeting
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,
        "days_since_first_touch": 7,
    },
)

Workflow: Task Completed Successfully

# AI-powered workflow completed a task
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 Encountered

# AI workflow encountered an 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",
        "records_affected": 1,
    },
)

---

Linking Events to Conversations

The conversation_id field is crucial for connecting business outcomes to AI interactions. Always 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 the conversation and the outcome

# Store the conversation ID from your message logging
conversation_id = response.conversation_id

# Later, when a business event occurs...
client.events.create(
    event_type="upgrade",
    product_id=product_id,
    conversation_id=conversation_id,  # Links this outcome to the AI interaction
    influence="positive",
    value="149.00",
    value_type="currency",
)

---

Sampling for High-Volume Events

For high-volume applications, use sampling to control ingestion:

# Sample 10% of page view events
client.events.create(
    event_type="feature_viewed",
    product_id=product_id,
    sample_rate=0.1,  # 10% sampling
    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,  # Never drop this event
    influence="positive",
    value="149.00",
    value_type="currency",
)

---

Idempotency for Reliable Event Tracking

Use \`insert_id\` to prevent duplicate events when retrying failed requests:

\`\`\`python import uuid

Generate a unique ID for this event (store it if you need to retry)

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, # Same ID = same event (no duplicates) ) \`\`\`

Best Practice: For critical events like purchases, generate the \`insert_id\` before attempting the request and persist it. If the request fails, retry with the same \`insert_id\` to guarantee exactly-once delivery.

---

Async vs Sync Considerations

When adding event tracking, match our existing async/sync pattern:

• Sync apps: Call client.events.create(...) directly
• Async apps: Use AsyncGreenflash and wrap calls in asyncio.create_task() for fire-and-forget

Important: In Python, calling an async function without await returns a coroutine that never executes. Always use asyncio.create_task() for fire-and-forget patterns in async code.

---

Integration Checklist

Your code should:

1. Identify key business milestones in our application (upgrades, cancellations, task completions, etc.)
2. Add event tracking at each milestone using client.events.create(...)
3. Link events to conversations by passing conversation_id when relevant
4. Set appropriate influence (positive, negative, neutral)
5. Include value and value_type for revenue-impacting events
6. Add useful properties for deeper analysis
7. Use fire-and-forget (asyncio.create_task()) in async code to avoid blocking

---

What You Must 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 will enable Greenflash to connect AI interactions to real business outcomes, validating conversation quality with tangible results.