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

# Understanding workflow triggers

> Learn what workflow triggers are, how to configure them with filters, and how to use multiple triggers in the HoopAI Platform.

export const CourseTracker = ({courseId, lessonId, videoId}) => {
  const [progress, setProgress] = useState({});
  const [expanded, setExpanded] = useState(false);
  useEffect(() => {
    setProgress(loadProgress());
    document.body.setAttribute("data-academy", "true");
    return () => document.body.removeAttribute("data-academy");
  }, []);
  const course = COURSES[courseId];
  if (!course) return null;
  const lessons = course.lessons;
  const currentIndex = lessons.findIndex(l => l.id === lessonId);
  const completedCount = lessons.filter(l => !!progress[courseId + "/" + l.id]).length;
  const percent = lessons.length > 0 ? Math.round(completedCount / lessons.length * 100) : 0;
  const isCurrentDone = !!progress[courseId + "/" + lessonId];
  const prev = currentIndex > 0 ? lessons[currentIndex - 1] : null;
  const next = currentIndex < lessons.length - 1 ? lessons[currentIndex + 1] : null;
  const totalDuration = formatTotalDuration(lessons);
  const handleToggle = () => {
    const key = courseId + "/" + lessonId;
    const updated = {
      ...progress
    };
    if (updated[key]) {
      delete updated[key];
    } else {
      updated[key] = Date.now();
    }
    setProgress(updated);
    persistProgress(updated);
  };
  const lessonPath = lesson => "/academy/" + course.dir + "/" + lesson.id;
  const videoEmbed = videoId ? <div style={{
    position: "relative",
    width: "100%",
    paddingBottom: "56.25%",
    borderRadius: "var(--ds-radius-lg)",
    overflow: "hidden",
    marginBottom: "24px",
    background: "#000"
  }}>
      <iframe src={"https://www.youtube-nocookie.com/embed/" + videoId + "?rel=0"} title="Lesson video" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen style={{
    position: "absolute",
    top: 0,
    left: 0,
    width: "100%",
    height: "100%",
    border: "none"
  }} />
    </div> : null;
  const lessonList = lessons.map(lesson => {
    const isActive = lesson.id === lessonId;
    const isDone = !!progress[courseId + "/" + lesson.id];
    const itemStyle = {
      display: "flex",
      alignItems: "center",
      gap: "8px",
      padding: "10px 16px",
      borderTop: "1px solid var(--academy-border-subtle, #f3f4f6)",
      background: isActive ? "var(--academy-active-bg, #f9fafb)" : "transparent",
      textDecoration: "none",
      cursor: isActive ? "default" : "pointer",
      color: "inherit",
      transition: "background 0.15s"
    };
    const titleStyle = {
      flex: 1,
      fontSize: "13px",
      fontWeight: isActive ? 600 : 400,
      color: isActive ? "var(--academy-text, #111827)" : "var(--academy-text-secondary, #6b7280)",
      overflow: "hidden",
      textOverflow: "ellipsis",
      whiteSpace: "nowrap",
      lineHeight: "1.4"
    };
    const durationStyle = {
      fontSize: "12px",
      color: "var(--academy-text-muted, #9ca3af)",
      whiteSpace: "nowrap"
    };
    const inner = <>
        {isDone ? <CheckCircle /> : <VideoIcon />}
        <span style={titleStyle}>{lesson.title}</span>
        <span style={durationStyle}>{lesson.duration}</span>
      </>;
    if (isActive) {
      return <div key={lesson.id} style={itemStyle}>
          {inner}
        </div>;
    }
    return <a key={lesson.id} href={lessonPath(lesson)} style={itemStyle}>
        {inner}
      </a>;
  });
  return <div className="not-prose" id="academy-course-tracker">
      {videoEmbed}
      <div className="academy-tracker" style={{
    fontFamily: "Inter, -apple-system, BlinkMacSystemFont, sans-serif",
    borderRadius: "var(--ds-radius-lg)",
    border: "1px solid var(--academy-border, #e5e7eb)",
    background: "var(--academy-bg, #ffffff)",
    overflow: "hidden",
    marginBottom: "24px"
  }}>
        {}
        <div style={{
    padding: "16px 16px 0"
  }}>
          <h3 style={{
    margin: 0,
    fontSize: "16px",
    fontWeight: 600,
    lineHeight: "1.4",
    color: "var(--academy-text, #111827)"
  }}>
            {course.title}
          </h3>
          <div style={{
    display: "flex",
    gap: "12px",
    marginTop: "8px"
  }}>
            <span style={{
    display: "flex",
    alignItems: "center",
    gap: "5px",
    fontSize: "12px",
    color: "var(--academy-text-secondary, #6b7280)",
    padding: "3px 8px 3px 6px",
    borderRadius: "var(--ds-radius-sm)",
    border: "1px solid var(--academy-border, #e5e7eb)"
  }}>
              <BookIcon /> {lessons.length} lessons
            </span>
            <span style={{
    display: "flex",
    alignItems: "center",
    gap: "5px",
    fontSize: "12px",
    color: "var(--academy-text-secondary, #6b7280)",
    padding: "3px 8px 3px 6px",
    borderRadius: "var(--ds-radius-sm)",
    border: "1px solid var(--academy-border, #e5e7eb)"
  }}>
              <ClockIcon /> Approx. {totalDuration}
            </span>
          </div>
        </div>

        {}
        <div style={{
    padding: "14px 16px 16px"
  }}>
          <div style={{
    display: "flex",
    justifyContent: "space-between",
    fontSize: "12px",
    color: "var(--academy-text-secondary, #6b7280)"
  }}>
            <span>Your progress</span>
            <span style={{
    fontWeight: 500,
    color: "var(--academy-text, #111827)"
  }}>
              {percent}%
            </span>
          </div>
          <div style={{
    height: "6px",
    borderRadius: "var(--ds-radius-full)",
    background: "var(--academy-track, #f3f4f6)",
    marginTop: "8px",
    overflow: "hidden"
  }}>
            <div style={{
    height: "100%",
    borderRadius: "var(--ds-radius-full)",
    background: "var(--academy-progress, #3b82f6)",
    transition: "width 0.5s cubic-bezier(0.4, 0, 0.2, 1)",
    width: percent + "%"
  }} />
          </div>
        </div>

        {}
        <div className="academy-lessons-desktop">{lessonList}</div>

        {}
        <div className="academy-lessons-mobile">
          <button onClick={() => setExpanded(!expanded)} aria-expanded={expanded} style={{
    display: "flex",
    alignItems: "center",
    justifyContent: "space-between",
    padding: "12px 16px",
    cursor: "pointer",
    borderTop: "1px solid var(--academy-border-subtle, #f3f4f6)",
    background: "transparent",
    border: "none",
    borderTopStyle: "solid",
    borderTopWidth: "1px",
    borderTopColor: "var(--academy-border-subtle, #f3f4f6)",
    width: "100%",
    textAlign: "left",
    color: "var(--academy-text-secondary, #6b7280)",
    fontSize: "13px",
    fontWeight: 500,
    fontFamily: "inherit"
  }}>
            <span>
              {expanded ? "Hide lessons" : "Show all " + lessons.length + " lessons"}
            </span>
            <ChevronDown open={expanded} />
          </button>
          {expanded && lessonList}
        </div>

        {}
        <div style={{
    display: "flex",
    alignItems: "center",
    justifyContent: "space-between",
    borderTop: "1px solid var(--academy-border, #e5e7eb)",
    padding: "10px 16px"
  }}>
          {prev ? <a href={lessonPath(prev)} style={{
    fontSize: "13px",
    color: "var(--academy-text-secondary, #6b7280)",
    textDecoration: "none",
    display: "flex",
    alignItems: "center",
    gap: "4px"
  }}>
              ‹ Previous
            </a> : <div />}
          <button onClick={handleToggle} style={{
    fontSize: "13px",
    fontWeight: 500,
    cursor: "pointer",
    padding: "6px 14px",
    borderRadius: "var(--ds-radius-md)",
    border: isCurrentDone ? "1px solid var(--academy-border, #e5e7eb)" : "none",
    background: isCurrentDone ? "var(--academy-bg, #ffffff)" : "var(--academy-btn-bg, #111827)",
    color: isCurrentDone ? "var(--academy-complete, #10b981)" : "var(--academy-btn-text, #ffffff)",
    display: "flex",
    alignItems: "center",
    gap: "6px",
    transition: "all 0.2s",
    lineHeight: "1.4",
    fontFamily: "inherit"
  }}>
            {isCurrentDone ? <>
                <CheckCircle /> Completed
              </> : "Mark as completed"}
          </button>
          {next ? <a href={lessonPath(next)} style={{
    fontSize: "13px",
    color: "var(--academy-text-secondary, #6b7280)",
    textDecoration: "none",
    display: "flex",
    alignItems: "center",
    gap: "4px"
  }}>
              Next ›
            </a> : <div />}
        </div>
      </div>
    </div>;
};

<CourseTracker courseId="workflow-automation" lessonId="understanding-workflow-triggers" />

A workflow trigger is the event or condition that starts an automation. When the trigger fires, the workflow executes its sequence of actions. Choosing the right trigger — and configuring it with precise filters — ensures your automation reaches exactly the right contacts at exactly the right time.

<Frame caption="The Understanding Workflow Triggers lesson in the HoopAI Academy">
  <img src="https://mintcdn.com/hoopai-84ec0cdc/gyU98wGhFXcTdqFf/images/academy-workflow-triggers.png?fit=max&auto=format&n=gyU98wGhFXcTdqFf&q=85&s=0aa03e5a41598c8044d00b6cb03b7b27" alt="Understanding workflow triggers article" width="1536" height="826" data-path="images/academy-workflow-triggers.png" />
</Frame>

## Why this matters

Every workflow must start somewhere. Triggers are the "if this happens" part of the automation — the starting gun. Without a well-configured trigger, your automation either never fires, or fires at the wrong time for the wrong people. A properly filtered trigger is the difference between a workflow that runs precisely and one that spams contacts or misses its mark.

## Common trigger types

<AccordionGroup>
  <Accordion title="Contact-based triggers">
    Fire when something changes on a contact record:

    * **Contact Created:** Fires when a new contact is added to the platform
    * **Tag Added / Removed:** Fires when a specific tag is applied to or removed from a contact
    * **Contact Updated:** Fires when a contact field changes
    * **Contact Birthday:** Fires on a contact's birthday date
  </Accordion>

  <Accordion title="Form and survey triggers">
    Fire when a contact submits a form or survey:

    * **Form Submitted:** Fires when a specific form is submitted
    * **Survey Submitted:** Fires when a survey is completed
  </Accordion>

  <Accordion title="Appointment triggers">
    Fire based on appointment activity:

    * **Appointment Status:** Fires when an appointment is booked, confirmed, cancelled, or completed
    * **Appointment Date:** Fires X days before or after an appointment date
  </Accordion>

  <Accordion title="Conversation and message triggers">
    Fire when a contact interacts via messaging:

    * **Customer Replied:** Fires when a contact sends any message (filterable by channel and keyword)
    * **Trigger Link Clicked:** Fires when a contact clicks a specific tracked link
    * **Email Opened / Email Not Opened:** Fires based on email engagement
  </Accordion>

  <Accordion title="Pipeline and opportunity triggers">
    Fire based on pipeline movement:

    * **Opportunity Status Changed:** Fires when an opportunity moves to a different stage or status
    * **Opportunity Created:** Fires when a new opportunity is created for a contact
  </Accordion>

  <Accordion title="Payment triggers">
    Fire based on payment activity:

    * **Payment Received:** Fires when a payment is completed
    * **Order Submitted:** Fires when an order form is submitted
  </Accordion>
</AccordionGroup>

## How to configure workflow triggers

<Steps>
  <Step title="Open a workflow">
    Go to **Automation** > **Workflows** and open or create a workflow. You will see the workflow canvas with the trigger area at the top.

    <Frame caption="The Workflow Automation builder in the HoopAI Platform">
      <img src="https://mintcdn.com/hoopai-84ec0cdc/gyU98wGhFXcTdqFf/images/academy-workflow-triggers.png?fit=max&auto=format&n=gyU98wGhFXcTdqFf&q=85&s=0aa03e5a41598c8044d00b6cb03b7b27" alt="Workflow automation builder" width="1536" height="826" data-path="images/academy-workflow-triggers.png" />
    </Frame>
  </Step>

  <Step title="Click Add Trigger">
    In the workflow builder, click the **Add Trigger** button at the top of the canvas.
  </Step>

  <Step title="Select a trigger type">
    Browse or search the trigger library and select the trigger that matches the event you want to respond to.

    <Frame caption="Selecting a trigger type from the workflow trigger library">
      <img src="https://mintcdn.com/hoopai-84ec0cdc/gyU98wGhFXcTdqFf/images/academy-workflow-recipes.png?fit=max&auto=format&n=gyU98wGhFXcTdqFf&q=85&s=82127a8fe14c91ea981ab7dbb7c56771" alt="Trigger type selection" width="1536" height="826" data-path="images/academy-workflow-recipes.png" />
    </Frame>
  </Step>

  <Step title="Add filters to the trigger">
    Click **Add Filter** within the trigger configuration to narrow down which contacts or events activate the workflow.

    For example, if using **Customer Replied** as your trigger:

    * **Channel:** SMS (fires only for text message replies)
    * **Reply Type:** Exact Match — `KEYWORD` (fires only when the message matches your exact keyword)

    <Tip>
      Always use trigger filters when possible. An unfiltered "Contact Created" trigger will fire for every single new contact — which is usually not what you want. Filters ensure precision.
    </Tip>
  </Step>

  <Step title="Add multiple triggers (optional)">
    A single workflow can have multiple triggers. Click **Add Trigger** again to add a second entry point. This is useful when the same automation should fire in response to different events — for example, both a form submission and a tag being added.
  </Step>

  <Step title="Test the trigger">
    Use a test contact to simulate the trigger condition and confirm the workflow starts as expected before publishing.

    <Frame caption="Testing a workflow trigger with a test contact before publishing">
      <img src="https://mintcdn.com/hoopai-84ec0cdc/gyU98wGhFXcTdqFf/images/academy-workflow-triggers.png?fit=max&auto=format&n=gyU98wGhFXcTdqFf&q=85&s=0aa03e5a41598c8044d00b6cb03b7b27" alt="Workflow trigger testing" width="1536" height="826" data-path="images/academy-workflow-triggers.png" />
    </Frame>
  </Step>
</Steps>

## Key points

<AccordionGroup>
  <Accordion title="What is a workflow trigger?">
    A trigger is any event or condition that starts a workflow. It is the "if this happens" component of automation — when the trigger fires, the workflow begins executing its action sequence. Without a trigger, a workflow never runs.
  </Accordion>

  <Accordion title="Why trigger filters matter">
    Filters narrow down which specific contacts or events activate the automation. An unfiltered trigger like "Contact Created" fires for every single new contact. Adding a filter — for example, "Tag Added = VIP Customer" — ensures the workflow only runs for the right people in the right context.
  </Accordion>

  <Accordion title="Multiple triggers in one workflow">
    A single workflow can have multiple triggers for different entry points. This is useful when the same automation should fire in response to different events — for example, both a form submission and a tag being added. Each trigger is an independent entry point into the same action sequence.
  </Accordion>

  <Accordion title="Trigger and filter combinations">
    The most effective automations use precise trigger plus filter combinations. For example: trigger = "Customer Replied," filter = "Channel: SMS, Reply Type: Exact Match, Value: GUIDE." This ensures the workflow fires only when someone texts your exact keyword — not for every SMS reply.
  </Accordion>
</AccordionGroup>

## Key benefits

<AccordionGroup>
  <Accordion title="Effortless automation">
    Triggers initiate workflows automatically without any manual intervention.
  </Accordion>

  <Accordion title="Personalized engagement">
    Filters ensure only the right contacts receive each automation, keeping messaging relevant.
  </Accordion>

  <Accordion title="Timely follow-ups">
    Triggers fire the moment the specified event occurs — enabling instant, timely responses.
  </Accordion>

  <Accordion title="Increased efficiency">
    Automating trigger-based tasks frees up time to focus on high-value activities.
  </Accordion>

  <Accordion title="Data-driven insights">
    Trigger events provide a record of contact behavior and engagement throughout their journey.
  </Accordion>
</AccordionGroup>
