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

# Triggers

> Start workflow execution from WhatsApp, project events, or API calls

Triggers define how workflows are initiated. Workflows can be triggered by incoming WhatsApp messages, project events, or external API calls.

## Trigger types

**WhatsApp message trigger**

* Starts workflow when message received on specific WhatsApp number
* Intercepts messages before they reach agents
* Provides message content and user context to workflow

**WhatsApp event trigger**

* Starts workflow when WhatsApp events occur (message and conversation lifecycle)
* Runs in observer mode (read-only, no outbound messages unless overridden)
* Access event data, conversation state, and message details

**API trigger**

* Starts workflow via HTTP POST request
* Programmatic workflow execution from external systems
* Pass custom variables and context data

**Project event trigger**

* Starts workflow when a custom project event is emitted
* Optionally filters by one event property
* Runs in observer mode (read-only, no outbound messages unless overridden)

For configuration, available context, and caveats, see [Use project events in workflows](/docs/flows/project-events).

## WhatsApp message trigger

When active, starts the workflow when messages are received on the configured WhatsApp number.

**Configuration**

* Select WhatsApp configuration (phone number)
* Only one workflow can have an active WhatsApp trigger per number

**Available context**

```
# Access in workflow via variables
{{context.phone_number}}       # User's WhatsApp number
{{last_user_input}}           # The received message text
{{context.channel}}           # "whatsapp"
{{context.conversation_id}}   # WhatsApp conversation ID
```

## WhatsApp event trigger

Starts workflows when WhatsApp message and conversation events occur. Workflows run in observer mode: they can read event data but cannot send messages unless a step explicitly overrides the destination phone number.

**Configuration**

* Select event type (message or conversation event)
* Optionally scope to specific WhatsApp number
* Only one workflow per event type per number

**Available events**

Message events:

* `whatsapp.message.received` - New message from customer
* `whatsapp.message.sent` - Message sent to WhatsApp
* `whatsapp.message.failed` - Message delivery failed

Conversation events:

* `whatsapp.conversation.created` - New conversation initiated
* `whatsapp.conversation.ended` - Conversation closed

**Observer mode**

Event-triggered workflows run in observer mode:

* Cannot send outbound messages by default
* Send steps (text, template, interactive) are skipped
* To send messages: configure "To phone number" in send step

**Available context**

```
# System variables
{{system.trigger_type}}                # "whatsapp_event"
{{system.observer_mode}}               # true
{{system.allow_outbound}}              # false

# Event data
{{system.event.type}}                    # "whatsapp.message.sent"
{{system.event.payload}}                 # Full event payload
{{system.event.conversation.id}}         # Conversation ID
{{system.event.conversation.phone_number}} # Customer phone number
{{system.event.message.id}}              # Message ID (for message events)
{{system.event.message.text.body}}       # Message text (when applicable)
```

**Testing event triggers**

Test event triggers from the Flow Test modal:

* Select trigger type: "WhatsApp Event"
* Choose conversation ID
* Select event type
* Test execution runs in observer mode
* Use phone number override in send steps to test outbound messages

## API trigger

Execute workflows programmatically via HTTP API. Perfect for integrating workflows with external systems, webhooks, or custom applications.

**Endpoint**

```
POST /platform/v1/workflows/{workflow_id}/executions
X-API-Key: {api_key}
Content-Type: application/json
```

**Request parameters**

```json theme={null}
{
  "workflow_execution": {
    "phone_number": "+1234567890",           // Required
    "phone_number_id": "123456789012345",    // Optional - WhatsApp phone number ID (preferred)
    "whatsapp_config_id": 123,               // Optional - Deprecated, use phone_number_id
    "variables": {                           // Optional workflow variables
      "customer_name": "John Doe",
      "order_id": "ORDER-123",
      "priority": "high"
    },
    "context": {                            // Optional context data
      "source": "website",
      "campaign": "summer_promo"
    },
    "initial_data": {                       // Optional initial data
      "user_preferences": {"language": "en"}
    }
  }
}
```

**phone\_number\_id validation**

* Must belong to your project (direct or via customer)
* Returns 422 error if invalid or doesn't belong to project
* When omitted, uses project's default WhatsApp config
* Preferred over deprecated `whatsapp_config_id`

**Response**

```json theme={null}
{
  "data": {
    "message": "Workflow execution initiated",
    "workflow_id": "workflow_uuid",
    "id": "execution_uuid",
    "tracking_id": "tracking_uuid"
  }
}
```

**Burst rate limit**

* This endpoint has an additional burst limiter scoped by API key and `workflow_id`
* `legacy` / `free`: 5 requests per second
* `pro`: 15 requests per second
* `enterprise` / `platform`: 30 requests per second
* Successful responses include `X-Burst-RateLimit-Limit` and `X-Burst-RateLimit-Remaining`
* If exceeded, the API returns `429 Too Many Requests` with `Retry-After: 1`
* General platform API rate limits still apply

**Example API call**

```bash theme={null}
curl -X POST "https://api.kapso.ai/platform/v1/workflows/your-workflow-id/executions" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_execution": {
      "phone_number": "+1234567890",
      "phone_number_id": "123456789012345",
      "variables": {
        "customer_name": "Alice Smith",
        "order_total": 149.99
      },
      "context": {
        "source": "checkout_flow"
      }
    }
  }'
```

## Workflow context

Triggered workflows receive context data based on the trigger type:

**WhatsApp message trigger context**

```
# System variables
{{system.trigger_type}}                    # "inbound_message"
{{system.trigger_whatsapp_config_id}}     # WhatsApp config ID
{{system.workflow_id}}                    # Current workflow ID

# Context variables
{{context.phone_number}}                  # "+1234567890"
{{context.channel}}                       # "whatsapp"
{{context.conversation_id}}               # WhatsApp conversation ID

# Workflow variables
{{last_user_input}}                       # The received message text
```

**WhatsApp event trigger context**

```
# System variables
{{system.trigger_type}}                  # "whatsapp_event"
{{system.observer_mode}}                 # true
{{system.allow_outbound}}                # false
{{system.workflow_id}}                   # Current workflow ID

# Event data
{{system.event.type}}                      # "whatsapp.message.sent"
{{system.event.payload}}                   # Full event payload
{{system.event.conversation.id}}           # Conversation ID
{{system.event.conversation.phone_number}} # "+1234567890"
{{system.event.conversation.status}}       # "active" or "ended"
{{system.event.message.id}}                # Message ID (for message events)
{{system.event.message.type}}              # "text", "image", etc.
{{system.event.message.text.body}}         # Message text (when applicable)
```

**API trigger context**

```
# System variables
{{system.trigger_type}}                  # "api_call"
{{system.tracking_id}}                   # Unique execution tracking ID
{{system.api_key_id}}                    # API key used
{{system.workflow_id}}                   # Current workflow ID
{{system.trigger_whatsapp_config_id}}    # WhatsApp config used (if provided)

# Context variables
{{context.phone_number}}         # "+1234567890" (from request, normalized)
{{context.channel}}              # "api"

# Custom variables (from request)
{{your_variable_name}}           # From request variables object
{{vars.your_variable_name}}      # Explicit vars namespace

# Request metadata (in metadata namespace)
{{metadata.request_ip}}          # API caller IP
{{metadata.request_timestamp}}   # Request time
```

## Managing triggers

Triggers are managed via the web interface:

1. Go to Workflow settings
2. Add a WhatsApp, project event, or API trigger
3. Configure trigger settings
4. Activate/deactivate as needed

See [Use project events in workflows](/docs/flows/project-events) for project event triggers. See [Project events](/docs/platform/events) for emitting and querying events through the API.