Module · Something changed in the CRM

Segment trigger

Lesson 2 of 10 · 2 min

A segment is a saved question about your contacts — everyone in Bangalore with an open deal, everyone who has not been contacted in sixty days. Membership is worked out from the data rather than stored on the record.

The Segment Trigger fires when a contact enters or leaves one. That is a different event from a field changing, and it is the reason this trigger exists alongside the Database Change one.

Why it is not just a field change

A contact can join the “stale leads” segment without anybody touching their record — they qualify because time passed, or because a deal elsewhere closed. No column changed on the contact, so a Database Change Trigger would never fire. The segment's answer changed, and that is what this trigger watches.

The rule of thumb. If you can name the field, use the Database Change Trigger. If the thing you care about is a condition — a combination, an absence, a threshold — put it in a segment and trigger on that.

A worked example

Someone joins the nurture segment

Click the trigger to see the four settings that matter.

All seven fields.

Field	What it holds
`trigger_on`	When to trigger: contact added to segment, removed from segment, or both One of: `added · removed · both` Defaults to `added`.
`segment_selection_mode`	How to select which segments to monitor One of: `specific · all · by_tags` Defaults to `specific`.
`segment_ids`	Specific segment IDs to monitor (when mode is 'specific')
`segment_tags`	Monitor segments with these tags (when mode is 'by_tags')
`include_contact_data`	Include full contact details (email, phone, name, etc.) in output Defaults to `true`.
`filter_config`	Optional filters on contact properties
`once_per_contact`	Only trigger once per contact (prevent re-triggers if contact is re-added) Defaults to `false`.

trigger_on

What it holds: When to trigger: contact added to segment, removed from segment, or both One of: added · removed · both Defaults to added.

segment_selection_mode

What it holds: How to select which segments to monitor One of: specific · all · by_tags Defaults to specific.

segment_ids

What it holds: Specific segment IDs to monitor (when mode is 'specific')

segment_tags

What it holds: Monitor segments with these tags (when mode is 'by_tags')

include_contact_data

What it holds: Include full contact details (email, phone, name, etc.) in output Defaults to true.

filter_config

What it holds: Optional filters on contact properties

once_per_contact

What it holds: Only trigger once per contact (prevent re-triggers if contact is re-added) Defaults to false.

Joining, leaving, or both

trigger_on	Fires when	Typical use
`added`	A contact enters the segment.	Start a sequence. The common case.
`removed`	A contact leaves it.	Stop a sequence, or clean up — they no longer qualify.
`both`	Either.	Keeping an external system in step with membership.

added

Fires when: A contact enters the segment.
Typical use: Start a sequence. The common case.

removed

Fires when: A contact leaves it.
Typical use: Stop a sequence, or clean up — they no longer qualify.

both

Fires when: Either.
Typical use: Keeping an external system in step with membership.

removed is the one people forget, and it is often the more important half. A nurture sequence that starts when someone goes cold should stop when they warm up — otherwise the person who just replied keeps getting “we haven't heard from you” emails.

Which segments

segment_selection_mode decides how much this trigger watches:

specific — the segments you list in segment_ids. Precise, and what you usually want.
by_tags — every segment carrying a tag. Useful when segments are created regularly and should all behave the same way.
all — every segment in the organisation. Rarely right: someone else's new segment will start firing your workflow.

The re-entry problem

Contacts move in and out of segments repeatedly. Membership is recalculated, so a contact who sits near the boundary of the rule can leave and re-enter more than once — and each entry is another run. If your workflow sends something, that is a person receiving the same message twice.

once_per_contact is the guard: the workflow runs for a given contact once and does not run again for them, however many times they re-enter. Turn it on for anything that sends, charges or creates. Leave it off only when repeating is genuinely intended — a sync that should reflect the current state every time.

What the workflow receives

With include_contact_data on — it is on by default — the whole contact arrives, so you can read {{segmenttrigger_1.contact.email}} without a lookup. Turn it off only if you have a reason to keep the payload small; the extra fetch it saves is the point of the setting.

Try it

Create a segment with a rule you can satisfy by hand — a lead status, say.
Add a Segment Trigger on it with trigger_on: added and once_per_contact on, writing a note.
Edit a contact so they qualify, and watch the run.
Now make them leave and re-join. With the guard on, nothing happens the second time — turn it off and see the difference.

Next: the Due Time Trigger — when the thing you are waiting for is a date on a record rather than a change to it.