Triggers API

The Triggers API allows you to create, manage, and monitor workflow triggers. Triggers are events that automatically start your workflows, such as incoming messages, scheduled times, or external webhooks.

List Triggers

Retrieve a list of all triggers in your account.

Request

GET /v1/triggers

Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`type`	string	Filter by trigger type (`message`, `schedule`, `webhook`, `api`)
`status`	string	Filter by status (`active`, `inactive`, `paused`)
`workflow_id`	string	Filter by workflow ID

Response

{
  "data": [
    {
      "id": "trigger-123",
      "name": "WhatsApp Support Trigger",
      "type": "message",
      "status": "active",
      "workflow_id": "workflow-456",
      "channel": "whatsapp",
      "configuration": {
        "keywords": ["help", "support", "question"],
        "case_sensitive": false
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z",
      "execution_count": 250,
      "last_triggered": "2024-01-25T09:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 15,
    "pages": 1
  }
}

Get Trigger

Retrieve details of a specific trigger.

Request

GET /v1/triggers/{trigger_id}

Response

{
  "data": {
    "id": "trigger-123",
    "name": "WhatsApp Support Trigger",
    "type": "message",
    "status": "active",
    "workflow_id": "workflow-456",
    "channel": "whatsapp",
    "configuration": {
      "keywords": ["help", "support", "question"],
      "case_sensitive": false,
      "exact_match": false,
      "language": "en"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:45:00Z",
    "execution_count": 250,
    "last_triggered": "2024-01-25T09:15:00Z"
  }
}

Create Trigger

Create a new trigger for a workflow.

Request

POST /v1/triggers

Request Body

{
  "name": "Instagram Marketing Trigger",
  "type": "message",
  "workflow_id": "workflow-789",
  "channel": "instagram",
  "configuration": {
    "keywords": ["promo", "discount", "sale"],
    "case_sensitive": false,
    "exact_match": false,
    "language": "en"
  }
}

Response

{
  "data": {
    "id": "trigger-456",
    "name": "Instagram Marketing Trigger",
    "type": "message",
    "status": "active",
    "workflow_id": "workflow-789",
    "channel": "instagram",
    "configuration": {
      "keywords": ["promo", "discount", "sale"],
      "case_sensitive": false,
      "exact_match": false,
      "language": "en"
    },
    "created_at": "2024-01-25T11:00:00Z",
    "updated_at": "2024-01-25T11:00:00Z",
    "execution_count": 0,
    "last_triggered": null
  }
}

Update Trigger

Update an existing trigger.

Request

PUT /v1/triggers/{trigger_id}

Request Body

{
  "name": "Updated Instagram Marketing Trigger",
  "configuration": {
    "keywords": ["promo", "discount", "sale", "offer"],
    "case_sensitive": false,
    "exact_match": false,
    "language": "en"
  }
}

Response

{
  "data": {
    "id": "trigger-456",
    "name": "Updated Instagram Marketing Trigger",
    "type": "message",
    "status": "active",
    "workflow_id": "workflow-789",
    "channel": "instagram",
    "configuration": {
      "keywords": ["promo", "discount", "sale", "offer"],
      "case_sensitive": false,
      "exact_match": false,
      "language": "en"
    },
    "created_at": "2024-01-25T11:00:00Z",
    "updated_at": "2024-01-25T12:00:00Z",
    "execution_count": 0,
    "last_triggered": null
  }
}

Delete Trigger

Delete a trigger permanently.

Request

DELETE /v1/triggers/{trigger_id}

Response

{
  "message": "Trigger deleted successfully"
}

Trigger Types

Message Triggers

Trigger workflows based on incoming messages.

Configuration

{
  "type": "message",
  "configuration": {
    "keywords": ["help", "support", "question"],
    "case_sensitive": false,
    "exact_match": false,
    "language": "en",
    "channel": "whatsapp"
  }
}

Parameters

Parameter	Type	Description
`keywords`	array	List of keywords to match
`case_sensitive`	boolean	Whether matching is case sensitive
`exact_match`	boolean	Whether to match exact phrases
`language`	string	Language code for matching
`channel`	string	Communication channel to monitor

Schedule Triggers

Trigger workflows at specific times or intervals.

Configuration

{
  "type": "schedule",
  "configuration": {
    "cron_expression": "0 9 * * 1-5",
    "timezone": "UTC",
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-12-31T23:59:59Z"
  }
}

Parameters

Parameter	Type	Description
`cron_expression`	string	Cron expression for scheduling
`timezone`	string	Timezone for the schedule
`start_date`	string	When to start the schedule
`end_date`	string	When to end the schedule

Webhook Triggers

Trigger workflows from external webhooks.

Configuration

{
  "type": "webhook",
  "configuration": {
    "url": "https://api.kaie.ai/v1/webhooks/trigger-123",
    "secret": "webhook-secret-key",
    "method": "POST",
    "headers": {
      "X-Custom-Header": "value"
    }
  }
}

Parameters

Parameter	Type	Description
`url`	string	Webhook URL for this trigger
`secret`	string	Secret for webhook verification
`method`	string	HTTP method for webhook
`headers`	object	Custom headers for webhook

API Triggers

Trigger workflows via direct API calls.

Configuration

{
  "type": "api",
  "configuration": {
    "endpoint": "/v1/triggers/trigger-123/fire",
    "authentication": "api_key",
    "rate_limit": 100
  }
}

Parameters

Parameter	Type	Description
`endpoint`	string	API endpoint for triggering
`authentication`	string	Authentication method
`rate_limit`	integer	Rate limit per hour

Trigger Management

Activate Trigger

Activate a trigger to start monitoring for events.

Request

POST /v1/triggers/{trigger_id}/activate

Response

{
  "data": {
    "id": "trigger-123",
    "status": "active",
    "activated_at": "2024-01-25T11:00:00Z"
  }
}

Deactivate Trigger

Deactivate a trigger to stop monitoring for events.

Request

POST /v1/triggers/{trigger_id}/deactivate

Response

{
  "data": {
    "id": "trigger-123",
    "status": "inactive",
    "deactivated_at": "2024-01-25T12:00:00Z"
  }
}

Pause Trigger

Temporarily pause a trigger without deactivating it.

Request

POST /v1/triggers/{trigger_id}/pause

Response

{
  "data": {
    "id": "trigger-123",
    "status": "paused",
    "paused_at": "2024-01-25T12:30:00Z"
  }
}

Resume Trigger

Resume a paused trigger.

Request

POST /v1/triggers/{trigger_id}/resume

Response

{
  "data": {
    "id": "trigger-123",
    "status": "active",
    "resumed_at": "2024-01-25T13:00:00Z"
  }
}

Trigger Executions

List Trigger Executions

Get a list of trigger executions.

Request

GET /v1/triggers/{trigger_id}/executions

Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`status`	string	Filter by status (`success`, `failed`, `running`)
`start_date`	string	Filter executions after this date (ISO 8601)
`end_date`	string	Filter executions before this date (ISO 8601)

Response

{
  "data": [
    {
      "id": "execution-789",
      "trigger_id": "trigger-123",
      "workflow_id": "workflow-456",
      "status": "success",
      "triggered_at": "2024-01-25T10:30:00Z",
      "completed_at": "2024-01-25T10:30:15Z",
      "duration_ms": 15000,
      "input": {
        "message": "I need help with my order",
        "customer_id": "customer-789",
        "channel": "whatsapp"
      },
      "output": {
        "workflow_execution_id": "workflow-execution-123"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "pages": 3
  }
}

Get Trigger Execution Details

Get detailed information about a specific trigger execution.

Request

GET /v1/triggers/{trigger_id}/executions/{execution_id}

Response

{
  "data": {
    "id": "execution-789",
    "trigger_id": "trigger-123",
    "workflow_id": "workflow-456",
    "status": "success",
    "triggered_at": "2024-01-25T10:30:00Z",
    "completed_at": "2024-01-25T10:30:15Z",
    "duration_ms": 15000,
    "input": {
      "message": "I need help with my order",
      "customer_id": "customer-789",
      "channel": "whatsapp",
      "metadata": {
        "user_agent": "WhatsApp/2.23.1.74",
        "timestamp": "2024-01-25T10:30:00Z"
      }
    },
    "output": {
      "workflow_execution_id": "workflow-execution-123",
      "workflow_status": "success"
    },
    "error": null
  }
}

Trigger Analytics

Get Trigger Metrics

Retrieve analytics data for a specific trigger.

Request

GET /v1/triggers/{trigger_id}/metrics

Parameters

Parameter	Type	Description
`start_date`	string	Start date for metrics (ISO 8601)
`end_date`	string	End date for metrics (ISO 8601)
`granularity`	string	Data granularity (`hour`, `day`, `week`, `month`)

Response

{
  "data": {
    "trigger_id": "trigger-123",
    "period": {
      "start_date": "2024-01-01T00:00:00Z",
      "end_date": "2024-01-31T23:59:59Z"
    },
    "metrics": {
      "total_executions": 250,
      "successful_executions": 240,
      "failed_executions": 10,
      "success_rate": 0.96,
      "average_duration_ms": 5000,
      "unique_customers": 150,
      "channel_breakdown": {
        "whatsapp": 200,
        "instagram": 50
      }
    },
    "daily_metrics": [
      {
        "date": "2024-01-01",
        "executions": 8,
        "success_rate": 0.95,
        "average_duration_ms": 4800
      }
    ]
  }
}

Error Handling

Common Error Codes

Status Code	Error Code	Description
400	`INVALID_TRIGGER_CONFIG`	Trigger configuration is invalid
400	`MISSING_REQUIRED_FIELD`	Required field is missing
404	`TRIGGER_NOT_FOUND`	Trigger does not exist
409	`TRIGGER_ALREADY_EXISTS`	Trigger with this name already exists
422	`INVALID_CRON_EXPRESSION`	Cron expression is invalid
500	`TRIGGER_EXECUTION_FAILED`	Trigger execution failed

Error Response Format

{
  "error": {
    "code": "INVALID_TRIGGER_CONFIG",
    "message": "Trigger configuration is invalid",
    "details": "Keywords array cannot be empty",
    "field": "configuration.keywords"
  }
}

Rate Limiting

Trigger API endpoints are subject to rate limiting:

List/Get operations: 1000 requests per hour
Create/Update operations: 100 requests per hour
Delete operations: 50 requests per hour
Execution operations: 500 requests per hour

Next Steps

Explore more API endpoints:

Workflows API

Manage workflows programmatically

Analytics API

Access analytics data

Webhooks API

Set up webhook integrations

Authentication

Learn about API authentication

API Documentation

Endpoints

​Triggers API

​List Triggers

​Request

​Parameters

​Response

​Get Trigger

​Request

​Response

​Create Trigger

​Request

​Request Body

​Response

​Update Trigger

​Request

​Request Body

​Response

​Delete Trigger

​Request

​Response

​Trigger Types

​Message Triggers

​Configuration

​Parameters

​Schedule Triggers

​Configuration

​Parameters

​Webhook Triggers

​Configuration

​Parameters

​API Triggers

​Configuration

​Parameters

​Trigger Management

​Activate Trigger

​Request

​Response

​Deactivate Trigger

​Request

​Response

​Pause Trigger

​Request

​Response

​Resume Trigger

​Request

​Response

​Trigger Executions

​List Trigger Executions

​Request

​Parameters

​Response

​Get Trigger Execution Details

​Request

​Response

​Trigger Analytics

​Get Trigger Metrics

​Request

​Parameters

​Response

​Error Handling

​Common Error Codes

​Error Response Format

​Rate Limiting

​Next Steps

Workflows API

Analytics API

Webhooks API

Authentication

Triggers API

List Triggers

Request

Parameters

Response

Get Trigger

Request

Response

Create Trigger

Request

Request Body

Response

Update Trigger

Request

Request Body

Response

Delete Trigger

Request

Response

Trigger Types

Message Triggers

Configuration

Parameters

Schedule Triggers

Configuration

Parameters

Webhook Triggers

Configuration

Parameters

API Triggers

Configuration

Parameters

Trigger Management

Activate Trigger

Request

Response

Deactivate Trigger

Request

Response

Pause Trigger

Request

Response

Resume Trigger

Request

Response

Trigger Executions

List Trigger Executions

Request

Parameters

Response

Get Trigger Execution Details

Request

Response

Trigger Analytics

Get Trigger Metrics

Request

Parameters

Response

Error Handling

Common Error Codes

Error Response Format

Rate Limiting

Next Steps