Triggers

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.

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

{
  "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

{
  "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

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:

Go to Workflow settings
Add a WhatsApp, project event, or API trigger
Configure trigger settings
Activate/deactivate as needed

See Use project events in workflows for project event triggers. See Project events for emitting and querying events through the API.

Getting started

Workflows

Functions

Workflows

Workflow Triggers

Functions

WhatsApp Conversations

Trigger types

WhatsApp message trigger

WhatsApp event trigger

API trigger

Workflow context

Managing triggers

​Trigger types

​WhatsApp message trigger

​WhatsApp event trigger

​API trigger

​Workflow context

​Managing triggers

Trigger types

WhatsApp message trigger

WhatsApp event trigger

API trigger

Workflow context

Managing triggers