Create an event
Track timestamped events representing user or organization actions. Events are used to track important business outcomes (signups, conversions, upgrades, cancellations, etc.) and integrate them into Greenflash's quality metrics. Each event can be optionally linked to a conversation, user, and organization.
Request body
The specific name or category of the event being tracked (e.g., "trial_started", "signup", "feature_usage"). This helps categorize events for analysis and often pairs with "value" to define the outcome.
The unique identifier of the Greenflash product associated with this event. This links the event to a specific product context.
Your system's unique identifier for the user associated with this event. Used to map Greenflash events back to your user records.
The unique Greenflash identifier for the user. Provide this if you already have the Greenflash User ID; otherwise, use "externalUserId".
Your system's unique identifier for the organization associated with this event. Used to map events to your customer accounts.
The unique Greenflash identifier for the organization. Provide this if you have the Greenflash Organization ID.
Your system's unique identifier for the conversation or thread where this event occurred.
The unique Greenflash identifier for the conversation. Links the event to a specific chat session in Greenflash.
A high-level categorization of how this event generally "changed things" or influenced quality (positive, negative, or neutral). Use this for broad classification of outcomes.
A precise numeric score between -1.0 and 1.0 for direct control over the quality impact. If omitted, it is automatically derived from the "influence" field.
The specific value associated with the event (e.g., "99.00", "5", "premium_plan"). This pairs with "valueType" and "eventType" to define the magnitude or content of the event.
Defines the format of the "value" field (currency, numeric, or text). This ensures the value is interpreted and processed correctly.
The ISO 8601 timestamp of when the event actually occurred. Defaults to the current time if not provided. Useful for backdating historical events.
A key-value object for storing additional, unstructured context about the event (e.g., { source: "web_app", campaign_id: "123" }). Useful for custom filtering.
A unique key for idempotency. If you retry a request with the same insertId, it prevents creating a duplicate event record.
Controls the percentage of requests that are ingested (0.0 to 1.0). For example, 0.1 means 10% of events will be stored. Defaults to 1.0 (all events ingested). Sampling is deterministic based on event type and organization.
When true, bypasses sampling and ensures this event is always ingested regardless of sampleRate. Use for critical events that must be captured.
Response
Event created successfully or existing event returned (idempotent)
Whether the API call was successful.
The unique Greenflash ID of the event record that was created.