Skip to main content

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​

TriggerDescriptionInstagramLINEMessengerWhatsAppTelegram
keywordIncoming message matches a keyword or phrase.YesYesYesYesYes
new_messageAny new incoming message.YesYesYesYesYes
new_conversationFirst message from a previously unknown contact.YesYesYesYesYes
story_replyUser replies to a Story.Yes--------
comment_keywordA post comment contains a keyword.Yes--Yes----

Engagement triggers​

TriggerDescriptionInstagramLINEMessengerWhatsAppTelegram
followUser follows / adds the account.--Yes------
unfollowUser unfollows / blocks the account.--Yes------
postbackUser taps a button, quick reply, or menu item.--YesYes--Yes

System triggers​

TriggerDescriptionPlatform
api_triggerWorkflow is started via a POST /v1/workflows/:id/trigger API call.All
scheduleWorkflow runs on a cron schedule.All
contact_tag_addedA specific tag is added to a contact.All
contact_tag_removedA specific tag is removed from a contact.All
contact_attribute_changedA 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"]
}
}
OptionDescription
keywordsArray of keywords to match.
match_modeexact, contains, starts_with, or regex.
case_sensitiveWhether matching is case-sensitive. Default: false.
platformsLimit 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.

tip

Use the new_message trigger as a catch-all fallback with a low priority, and more specific triggers (like keyword) with higher priority.