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

​
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 status, 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

​
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 events occur - message status changes, conversation lifecycle events. 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.delivered - Message delivered to recipient
  • whatsapp.message.read - Recipient read the message
  • 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
Authorization: Bearer {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 
{
  "message": "Workflow execution initiated",
  "workflow_id": "workflow_uuid",
  "tracking_id": "tracking_uuid"
}
Example API call 
curl -X POST "https://api.kapso.ai/platform/v1/workflows/your-workflow-id/executions" \
  -H "Authorization: Bearer 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 trigger (WhatsApp or API)
  3. Configure trigger settings
  4. Activate/deactivate as needed