> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpressbot.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Select a Trigger

> Choose the event that starts your workflow — and avoid duplicate or missed runs.

## What is this?

The **trigger** decides **when** a workflow runs. It listens for a specific event and starts the automation only when that event occurs.

<Info>
  If a workflow fires at the wrong time or not at all, the trigger is the first thing to check.
</Info>

## What can I do here?

* Choose the **Trigger Type** when you create a workflow
* Scope a trigger to the right channel and contact
* Use data carried by the trigger — such as the message text, contact fields, or webhook payload — in later steps

A good trigger matches the real business moment. A poor trigger causes duplicate runs, missed conversations, or logic that fires in the wrong place.

## How to use it

### Available triggers

The triggers you can choose depend on the channel type. These are available in the builder:

| Trigger                             | Runs when…                                                                                |
| ----------------------------------- | ----------------------------------------------------------------------------------------- |
| **Message Received**                | An incoming message matches your keyword automations                                      |
| **New Conversation**                | A brand-new conversation thread is opened (runs once)                                     |
| **No Match Reply**                  | An incoming message does not match any keyword automation                                 |
| **Receive Webhook**                 | An incoming webhook request is received                                                   |
| **Contact or Custom Field Changed** | A selected contact or custom field is created, updated, or its value changes              |
| **Pipeline Stage Changed**          | A contact is added to or moved within a selected pipeline, optionally filtered to a stage |
| **Trigger Sequence**                | A contact is enrolled into the sequence — use Sequence Drip steps for timed messages      |

**Instagram triggers**

| Trigger                                | Runs when…                                                           |
| -------------------------------------- | -------------------------------------------------------------------- |
| **User comments on your Post or Reel** | Someone comments on your Instagram post or reel                      |
| **User comments on your Live**         | Someone comments during your Instagram Live                          |
| **User replies to your Story**         | Someone replies to your Story in DMs                                 |
| **User clicks a referral link**        | An Instagram referral link or ad entry point starts the conversation |

**Facebook triggers**

| Trigger                                  | Runs when…                                                                                    |
| ---------------------------------------- | --------------------------------------------------------------------------------------------- |
| **User comments on your Facebook Post**  | Someone comments on your Facebook post                                                        |
| **User comments on your Facebook Live**  | Someone comments during your Facebook Live                                                    |
| **Someone @mentions your Facebook Page** | Someone @mentions your Page in a post or comment — best used with FB Private Reply            |
| **User clicks a Facebook referral link** | Someone opens Messenger from an m.me link, ad, or other referral entry with a `ref` parameter |

### Choose the right trigger

<Steps>
  <Step title="Define the outcome first">
    What should the automation achieve? For example: *Reply to pricing questions and assign them to sales.*
  </Step>

  <Step title="Identify the true starting event">
    What real activity marks the start? A keyword message, a new conversation, or a webhook — not a later step in the process.
  </Step>

  <Step title="Pick the matching trigger">
    Select the trigger whose event aligns exactly with that moment. When in doubt, prefer the most specific trigger.
  </Step>
</Steps>

### Start a workflow when a contact moves in a pipeline

Use **Pipeline Stage Changed** to react when a contact is added to, or moved within, a [Pipeline](/workspace/contacts/pipelines).

<Steps>
  <Step title="Create the pipeline first">
    Create the pipeline and its stages in [Pipelines](/workspace/contacts/pipelines). The trigger can only select pipelines and stages that already exist.
  </Step>

  <Step title="Create the workflow">
    Go to **Automation → Create Automation**, choose the channel, and pick **Pipeline Stage Changed** as the **Trigger Type**. See [Create a Workflow](/workspace/automation/create-a-workflow).
  </Step>

  <Step title="Choose the pipeline and stage">
    Select the pipeline. To run only when contacts reach a particular stage, also select that stage — otherwise the workflow runs when a contact is added to or moved within any stage of the pipeline.
  </Step>

  <Step title="Add the follow-up steps">
    Add what should happen next — for example send a message or template, assign a teammate with **Assign team member**, add a note with **Create Note/Reminder**, or update a field with **Update Field** or **Update Label**.
  </Step>

  <Step title="Test, then activate">
    Move a test contact to the chosen stage on the Pipelines board, then check the result in [Inbox](/workspace/inbox/overview) and in [Analytics](/workspace/analytics) under **Automations**. Only then activate the flow — see [Manage Live Flows](/workspace/automation/manage-live-flows).
  </Step>
</Steps>

<Note>
  Workflows can **react to** pipeline changes, but the builder has no step that creates or moves Pipeline cards. Contacts are moved on the Pipelines board.
</Note>

| Goal                              | Setup                                                                                                                                  |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Congratulate a converted lead     | Trigger: **Pipeline Stage Changed**, pipeline *Leads*, stage *Converted*. Step: send a thank-you template.                             |
| Alert the team about a hot lead   | Trigger: **Pipeline Stage Changed**, pipeline *Sales*, stage *Priority*. Steps: **Assign team member**, then **Create Note/Reminder**. |
| Tag contacts when a field changes | Trigger: **Contact or Custom Field Changed** on `requirement`. Step: **Update Label** to add *Qualified*.                              |

### Tips

* **One trigger per workflow.** Don't try to start the same flow from multiple unrelated events — create focused flows instead.
* **Prefer triggers that carry data.** A trigger that includes the payload you need saves extra lookups.
* **The pipeline must exist first.** The trigger can only select existing pipelines and stages; stage names must match exactly.
* **Scope by channel.** A workflow built for WhatsApp won't fire for Web Chat. Confirm the channel in [Channels](/workspace/channels).

## Troubleshooting / Technical Notes

* **The flow never runs.** Check that it's **Active**, the channel matches the conversation, and — for **Message Received** — that the message matches your keywords.
* **It doesn't start when a contact moves.** Is the workflow **Active**, and do the trigger's pipeline and stage match where the contact moved, on the same channel?
* **The flow runs twice.** Two automations may share the same trigger. Review the list in [Manage Live Flows](/workspace/automation/manage-live-flows).
* **Fallback replies.** Use **No Match Reply** for messages that match no keyword, so customers never get silence.

## Related docs

* [Automation Overview](/workspace/automation/overview)
* [Create a Workflow](/workspace/automation/create-a-workflow)
* [Pipelines](/workspace/contacts/pipelines)
* [Analytics](/workspace/analytics)
* [Manage Live Flows](/workspace/automation/manage-live-flows)