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

# Use project events in workflows

> Trigger workflows from project events and emit events from workflow runs

Project events are durable custom records, such as `lead.qualified` or `conversation.csat_scored`. Use them in workflows to react to product events or record an outcome for later querying, analysis, or automation. For the API and event data model, see [Project events](/docs/platform/events).

## Trigger workflows

Use a Project event trigger to start a workflow when a project event is emitted.

### Configure a trigger

Select an event definition in the dashboard. Create the definition first when you need to configure a trigger before real events exist; events that have already been emitted also appear in the picker.

You can optionally filter on one event property:

* `eq` for exact matches
* `lt`, `lte`, `gt`, `gte` for numeric comparisons

Numeric filters match only numeric property values.

### Observer mode and context

Project-event-triggered workflows run in observer mode. They can read event data, but send steps do not send WhatsApp messages unless the step explicitly overrides the destination phone number.

```text theme={null}
{{system.trigger_type}}              # "project_event"
{{system.project_event_id}}          # Event ID
{{system.observer_mode}}             # true
{{system.allow_outbound}}            # false
{{system.workflow_id}}               # Current workflow ID
{{context.channel}}                  # "project_event" or "whatsapp"
{{context.conversation_id}}          # Conversation ID, when linked
{{context.event.id}}                 # Event ID
{{context.event.name}}               # "conversation.csat_scored"
{{context.event.occurred_at}}        # Event timestamp
{{context.event.properties}}         # Event properties
{{context.event.properties.score}}   # Event property
```

Project events must be available on your plan. A workflow triggered by a project event cannot emit project events, which prevents trigger loops.

## Emit project events

Workflows can emit project events in three ways:

* An [Emit event node](/docs/flows/step-types/emit-event-node)
* The Agent node's [`emit_event` tool](/docs/flows/step-types/agent-node#emitting-project-events)
* A [Function node response](/docs/flows/step-types/function-node)

Function responses include events in `project_events`:

```json theme={null}
{
  "vars": {
    "csat_score": 4
  },
  "project_events": [
    {
      "name": "conversation.csat_scored",
      "properties": {
        "score": 4,
        "reason": "Issue resolved in one reply",
        "source": "workflow"
      }
    }
  ]
}
```

### Limits and test mode

* A workflow execution can emit at most 10 project events.
* A workflow execution can emit at most 3 events with the same name.
* A Function node response can emit at most 5 project events.
* In test mode, emitted events are validated and appear in workflow execution events, but project events are not stored.