> ## Documentation Index
> Fetch the complete documentation index at: https://docs.greenflash.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Close the loop between AI interactions and business outcomes.

*Connect real-world user actions to your AI conversations. By tracking timestamped business events, you enable Greenflash to validate which interactions drive revenue, retention, and delight—and which ones lead to churn.*

<Info>
  **Events are the bridge between conversation and conversion.** While tools like Amplitude or PostHog track *what* happened, Greenflash connects *why* it happened by linking outcomes directly to the AI interactions that preceded them.
</Info>

## Why Track Events?

Greenflash provides powerful analytics on user interactions, giving you visibility into conversation quality, sentiment, and engagement. Tracking events adds a critical layer of business context to these insights.

By correlating downstream user actions with upstream AI interactions, you can:

* **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 the conversation patterns that drive real-world results.

<Note>
  Events work for any AI product that drives user actions, not just chatbots. Whether you're building AI-powered sales tools, workflow automation, or content generation, events let you measure what matters: real business outcomes.
</Note>

## 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

*Signals that the user is succeeding.*

* `signup_completed`
* `trial_started`
* `task_success`
* `upgrade_purchased`

### Negative Indicators

*Signals of friction or churn.*

* `cancellation_requested`
* `error_encountered`
* `workflow_abandoned`

### Contextual Indicators

*Neutral signals that provide usage context.*

* `feature_viewed`
* `step_completed`
* `usage_logged`

## Integration Guide

Sending events is a simple API call. You can trigger this from your backend, frontend, or webhooks.

### The Endpoint

`POST https://www.greenflash.ai/api/v1/events`

### Basic Example: Customer Support Chatbot

Here's how you might track a user upgrading to a "Pro" plan immediately after a helpful support chat:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
curl --request POST \
  --url https://www.greenflash.ai/api/v1/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "eventType": "upgrade",
    "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "conversationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "influence": "positive",
    "value": "149.00",
    "valueType": "currency",
    "properties": {
      "plan": "pro",
      "billing_cycle": "annual"
    },
    "insertId": "unique-id-123"
  }'
```

### Beyond Chatbots: Other AI Product Examples

Events are valuable across many types of AI products. Here are some scenarios:

<AccordionGroup>
  <Accordion title="Sales Engagement: AI-Suggested Outreach" icon="dollar-sign">
    If your product helps sales teams with AI-generated comments or relationship-building suggestions, track when those interactions convert to real conversations:

    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    # Track when a prospect replies to AI-suggested engagement
    POST /api/v1/events
    {
      "eventType": "prospect_replied",
      "conversationId": "abc-123",
      "influence": "positive",
      "value": "1",
      "valueType": "numeric",
      "properties": {
        "engagement_type": "linkedin_comment",
        "days_since_first_touch": 3
      }
    }

    # Track when the conversation advances to a meeting
    POST /api/v1/events
    {
      "eventType": "meeting_booked",
      "conversationId": "abc-123",
      "influence": "positive",
      "value": "50000",
      "valueType": "currency",
      "properties": {
        "pipeline_stage": "qualification",
        "engagement_touches": 5
      }
    }
    ```

    **The insight:** Which AI suggestions actually lead to pipeline? What patterns exist in successful engagement strategies vs. ignored ones?
  </Accordion>

  <Accordion title="Operations: AI Workflow Analysis" icon="chart-no-axes-combined">
    If your product uses AI to analyze and optimize business processes, track when recommendations get implemented:

    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    # Track when an AI-identified improvement is acted on
    POST /api/v1/events
    {
      "eventType": "workflow_optimized",
      "conversationId": "workflow-session-456",
      "influence": "positive",
      "value": "40",
      "valueType": "numeric",
      "properties": {
        "process_area": "finance_operations",
        "improvement_type": "automation_identified",
        "estimated_hours_saved": 40
      }
    }

    # Track the business impact when automation goes live
    POST /api/v1/events
    {
      "eventType": "automation_deployed",
      "conversationId": "workflow-session-456",
      "influence": "positive",
      "value": "5000",
      "valueType": "currency",
      "properties": {
        "automation_type": "process_standardization",
        "departments_impacted": 3
      }
    }
    ```

    **The insight:** Are AI discovery sessions leading to real operational changes? Which types of insights drive the most value?
  </Accordion>

  <Accordion title="Lead Intelligence: AI Social Monitoring" icon="radar">
    If your product monitors conversations to identify high-intent prospects, track which signals lead to actual conversions:

    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    # Track when an AI-identified lead responds to outreach
    POST /api/v1/events
    {
      "eventType": "lead_responded",
      "conversationId": "signal-789",
      "influence": "positive",
      "value": "1",
      "valueType": "numeric",
      "properties": {
        "intent_signal": "competitor_frustration",
        "platform": "reddit",
        "time_to_response_hours": 2
      }
    }

    # Track when that lead becomes a customer
    POST /api/v1/events
    {
      "eventType": "lead_converted",
      "conversationId": "signal-789",
      "influence": "positive",
      "value": "2500",
      "valueType": "currency",
      "properties": {
        "channel": "social_listening",
        "time_to_conversion_days": 14,
        "original_intent_type": "competitor_mention"
      }
    }
    ```

    **The insight:** Which intent signals convert vs. which are false positives? Optimize your monitoring criteria based on actual revenue data.
  </Accordion>
</AccordionGroup>

### Key Fields

| Field                    | Type     | Required | Description                                                                                |
| :----------------------- | :------- | :------- | :----------------------------------------------------------------------------------------- |
| `eventType`              | string   | Yes      | The name of the event (e.g., `upgrade`).                                                   |
| `productId`              | uuid     | Yes      | Your Greenflash Product ID.                                                                |
| `value`                  | string   | Yes      | The measurable value (e.g., `"149.00"`).                                                   |
| `valueType`              | enum     | No       | How to interpret `value`: `currency`, `numeric`, `text`, or `boolean`. Defaults to `text`. |
| `influence`              | enum     | No       | `positive`, `negative`, or `neutral`. Defaults to `neutral`.                               |
| `qualityImpactScore`     | number   | No       | Fine-grained quality impact from `-1.0` to `1.0`. Overrides `influence` if provided.       |
| `conversationId`         | uuid     | No       | Link this event to a specific Greenflash conversation.                                     |
| `externalConversationId` | string   | No       | Link using your own conversation identifier.                                               |
| `externalUserId`         | string   | No       | Associate the event with a user in your system.                                            |
| `eventAt`                | ISO 8601 | No       | When the event occurred. Defaults to now. Useful for importing historical data.            |
| `insertId`               | string   | No       | Unique key for idempotency. Prevents duplicate events on retry.                            |
| `properties`             | object   | No       | Additional context as key-value pairs for filtering and analysis.                          |

<Tip>
  For the complete API specification, check out the [API Reference](https://docs.greenflash.ai/api-reference/business-events/create-an-event).
</Tip>

## Sampling

For high-volume applications, you can control the percentage of events that are ingested using the `sampleRate` field (0-1). Use `forceSample: true` for critical events that should never be dropped.

<Tip>
  For detailed information on sampling behavior, including the differences between message and event sampling, see the [Sampling documentation](/features/sampling).
</Tip>

## The Impact on Quality Scores

Events directly feed into your **Product Quality Index (PQI)** and **Conversation Quality Index (CQI)**.

1. **Weighted Scoring:** You can configure the impact of events in your quality settings. This allows you to weight business outcomes (like purchases) more heavily than other signals in your CQI and PQI scores.
2. **Validation:** Events serve as the "ground truth" for your analytics. They turn assumptions into facts.

## Recommended Workflow

1. **Identify Milestones:** Pick events that define success for your product (e.g., "Onboarding Complete", "Subscription Started").
2. **Instrument Your Code:** Add the API call to your backend logic where these events occur.
3. **Link Conversations:** Whenever possible, pass the `conversationId` if the event happened during or shortly after an AI session.
4. **Verify:** Check the Greenflash dashboard to see your events populating the **Business Outcomes** view.

## Next Steps

<CardGroup cols={2}>
  <Card title="Product Analytics" icon="chart-line" href="/intro/ai-product-analysis">
    See how events drive your product metrics.
  </Card>

  <Card title="Connect Conversations" icon="comments" href="https://docs.greenflash.ai/api-reference/interactions/create">
    Learn how to link events to specific chats.
  </Card>
</CardGroup>