---
title: "Create workflow trigger"
method: POST
path: "/workflows/{workflow_id}/triggers"
tags: ["Workflow Triggers"]
---

# Create workflow trigger

`POST /workflows/{workflow_id}/triggers`

Create a new trigger for a workflow. Triggers define when the workflow should automatically execute.

Trigger types:
- `inbound_message`: Workflow starts when WhatsApp messages arrive at specified phone number (requires phone_number_id)
- `api_call`: Workflow starts only via POST /workflows/{id}/executions (no phone_number_id needed)

After creating a trigger:
- For inbound_message: Messages to the phone_number_id will start workflow executions
- For api_call: Workflow can only be started via API endpoint

Note: A workflow can have multiple triggers (e.g., multiple phone numbers, or both inbound_message and api_call).

## Request body

- WorkflowTriggerCreateRequest — Request to create a new workflow trigger
  - `trigger` object, required
    - `trigger_type` 'inbound_message' | 'api_call' | 'whatsapp_event' | 'project_event', required — Type of trigger to create: - `inbound_message`: Workflow starts when messages arrive at a WhatsApp number (requires phone_number_id) - `api_call`: Workflow starts via API endpoint (no phone_number_id needed) - `whatsapp_event`: Workflow starts on WhatsApp events (requires event, optional phone_number_id) - `project_event`: Workflow starts when a matching Project Event is emitted (requires event_name)
    - `active` boolean — Whether the trigger should be active immediately after creation
    - `phone_number_id` string — **Required for inbound_message triggers.** For whatsapp_event triggers, optional to scope to specific number. WhatsApp Business phone number ID that will trigger this workflow. Messages to this number will start workflow executions. Not used for api_call triggers.
    - `event` 'whatsapp.message.received' | 'whatsapp.message.sent' | 'whatsapp.message.failed' | 'whatsapp.conversation.created' | 'whatsapp.conversation.ended' — **Required for whatsapp_event triggers.** WhatsApp event type that will trigger the workflow. Not used for inbound_message or api_call triggers.
    - `event_name` string — **Required for project_event triggers.** Lowercase dotted snake_case Project Event name.
    - `property_key` string — Optional Project Event property key to filter on.
    - `operator` 'eq' | 'lt' | 'lte' | 'gt' | 'gte' — Optional Project Event property comparison operator.
    - `property_value` unknown

## Response `201`

Trigger created successfully

- WorkflowTriggerResponse — Single workflow trigger response
  - `data` WorkflowTrigger, required — Workflow trigger defining when and how a workflow execution should start
    - `id` string, uuid, required — Unique trigger identifier
    - `workflow_id` string, uuid, required — ID of the workflow this trigger belongs to
    - `trigger_type` 'inbound_message' | 'api_call' | 'whatsapp_event' | 'project_event', required — Trigger activation mechanism: - `inbound_message`: Triggered by incoming WhatsApp messages to a specific phone number - `api_call`: Triggered by POST /workflows/{id}/executions API calls - `whatsapp_event`: Triggered by WhatsApp events (message and conversation lifecycle) - `project_event`: Triggered by an emitted Project Event
    - `active` boolean, required — Whether this trigger is enabled. Inactive triggers will not start workflow executions even when their conditions are met. Use this to temporarily disable a trigger without deleting it.
    - `display_name` string, nullable — Human-readable trigger name. Format varies by type: - Inbound message: "WhatsApp: [phone number display name]" - API call: "API Call Trigger" - Project event: "Event: [event name]"
    - `created_at` string, date-time — Trigger creation timestamp
    - `updated_at` string, date-time — Last modification timestamp
    - `triggerable` union — Type-specific trigger configuration. Structure varies by trigger_type: - For `inbound_message`: Contains phone_number_id - For `api_call`: Empty object - For `whatsapp_event`: Contains event and optional phone_number_id - For `project_event`: Contains event_name and optional property filter fields
      - object — Inbound message trigger configuration
        - `phone_number_id` string, required — WhatsApp Business phone number ID that will trigger the workflow
      - object — API call trigger configuration (no additional fields)
      - object — WhatsApp event trigger configuration
        - `event` 'whatsapp.message.received' | 'whatsapp.message.sent' | 'whatsapp.message.failed' | 'whatsapp.conversation.created' | 'whatsapp.conversation.ended', required — WhatsApp event type that will trigger the workflow
        - `phone_number_id` string — Optional WhatsApp Business phone number ID to scope trigger to specific number
      - object — Project Event trigger configuration
        - `event_name` string, required — Lowercase dotted snake_case Project Event name that starts the workflow.
        - `property_key` string, nullable — Optional Project Event property key to filter on.
        - `operator` 'eq' | 'lt' | 'lte' | 'gt' | 'gte' | 'null', nullable — Optional property comparison operator.
        - `property_value` unknown

## Other responses

- `401` — Missing or invalid API key
- `404` — Resource not found
- `422` — Request validation failed

---

[API](https://skmtc.net/kapso/apis/kapso-platform-api.md) · [All operations](https://skmtc.net/kapso/apis/kapso-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kapso/kapso-platform-api/revisions/18ff5548a33f/schema)