Skip to main content
Triggers define how flows are initiated. Flows can be triggered by incoming WhatsApp messages or external API calls, providing flexible entry points for automated conversations.

​
Trigger types

WhatsApp message trigger
  • Starts flow when message received on specific WhatsApp number
  • Intercepts messages before they reach agents
  • Provides message content and user context to flow
API trigger
  • Starts flow via HTTP POST request
  • Programmatic flow execution from external systems
  • Pass custom variables and context data

​
WhatsApp message trigger

When active, starts the flow when messages are received on the configured WhatsApp number. Configuration
  • Select WhatsApp configuration (phone number)
  • Only one flow can have an active WhatsApp trigger per number
Available context 
# Access in flow 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

​
API trigger

Execute flows programmatically via HTTP API. Perfect for integrating flows with external systems, webhooks, or custom applications. Endpoint 
POST /api/v1/flows/{flow_id}/executions
Authorization: Bearer {api_key}
Content-Type: application/json
Request parameters 
{
  "phone_number": "+1234567890",           // Required
  "whatsapp_config_id": "config-123abc",   // Optional - WhatsApp config to use
  "variables": {                           // Optional flow 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"}
  }
}
whatsapp_config_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
Response 
{
  "message": "Flow execution initiated",
  "flow_id": "flow_uuid",
  "tracking_id": "tracking_uuid"
}
Example API call 
curl -X POST "https://app.kapso.ai/api/v1/flows/your-flow-id/executions" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+1234567890",
    "whatsapp_config_id": "config-123abc",
    "variables": {
      "customer_name": "Alice Smith",
      "order_total": 149.99
    },
    "context": {
      "source": "checkout_flow"
    }
  }'

​
Flow context

Triggered flows 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.flow_id}}                        # Current flow ID

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

# Flow variables
{{last_user_input}}                       # The received message text
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.flow_id}}                       # Current flow 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 Flow settings
  2. Add trigger (WhatsApp or API)
  3. Configure trigger settings
  4. Activate/deactivate as needed
⌘I