Workflow Triggers
A trigger is the event that starts a Workflow execution. Every Workflow must have exactly one trigger. When the trigger condition is met, a new execution begins with the event data available to all downstream nodes.
Trigger types
Messaging triggers
| Trigger | Description | LINE | Messenger | Telegram | ||
|---|---|---|---|---|---|---|
keyword | Incoming message matches a keyword or phrase. | Yes | Yes | Yes | Yes | Yes |
new_message | Any new incoming message. | Yes | Yes | Yes | Yes | Yes |
new_conversation | First message from a previously unknown contact. | Yes | Yes | Yes | Yes | Yes |
story_reply | User replies to a Story. | Yes | -- | -- | -- | -- |
comment_keyword | A post comment contains a keyword. | Yes | -- | Yes | -- | -- |
Engagement triggers
| Trigger | Description | LINE | Messenger | Telegram | ||
|---|---|---|---|---|---|---|
follow | User follows / adds the account. | -- | Yes | -- | -- | -- |
unfollow | User unfollows / blocks the account. | -- | Yes | -- | -- | -- |
postback | User taps a button, quick reply, or menu item. | -- | Yes | Yes | -- | Yes |
System triggers
| Trigger | Description | Platform |
|---|---|---|
api_trigger | Workflow is started via a POST /v1/workflows/:id/trigger API call. | All |
schedule | Workflow runs on a cron schedule. | All |
contact_tag_added | A specific tag is added to a contact. | All |
contact_tag_removed | A specific tag is removed from a contact. | All |
contact_attribute_changed | A contact attribute is updated to a specific value. | All |
Trigger configuration
Each trigger type has its own configuration options. For example:
Keyword trigger
{
"type": "keyword",
"config": {
"keywords": ["order", "status", "track"],
"match_mode": "contains",
"case_sensitive": false,
"platforms": ["instagram", "line"]
}
}
| Option | Description |
|---|---|
keywords | Array of keywords to match. |
match_mode | exact, contains, starts_with, or regex. |
case_sensitive | Whether matching is case-sensitive. Default: false. |
platforms | Limit the trigger to specific platforms. Default: all connected platforms. |
API trigger
Start a Workflow programmatically by calling the API:
curl -X POST https://api.convotic.com/v1/workflows/wf_abc123/trigger \
-H "X-API-Key: $CONVOTIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact_id": "ct_xyz789",
"payload": {
"order_id": "ORD-1234"
}
}'
The payload object is available to all nodes in the Workflow as trigger.payload.
Trigger priority
If multiple Workflows have triggers that match the same event, they execute in priority order. You can set the priority of each Workflow in its settings (lower number = higher priority). If a Workflow marks the event as handled, lower-priority Workflows will not execute.
Use the new_message trigger as a catch-all fallback with a low priority, and more specific triggers (like keyword) with higher priority.