Triggers & Events

This document defines how Triggers and Events work in QuickReply.ai and how they should be designed to build scalable, low-error Journeys and Campaigns.

---

What Is a Trigger?

A Trigger is an incoming webhook action sent to QuickReply.ai via a POST request.

Key Characteristics

• Receives raw data (JSON payload)

• Has no filters or business logic

• Cannot trigger messages on its own

• Can power multiple Events

A Trigger is only a data ingestion mechanism. No action can be performed in QuickReply.ai without an Event.

---

What Is an Event?

An Event is a logical layer created on top of a Trigger.

Key Characteristics

• Uses identifiers and attributes from the payload

• Applies filters and conditions

• Acts as the only entry point to:

  • Journeys

  • Campaigns

• Can be reused across multiple modules

Important: No action can be performed in QuickReply.ai without an Event.

---

Trigger → Event → Journey / Campaign Flow

Relationship Model

• Trigger (1 → many) Events

• Event (1 → many) Journeys

• Event (1 → many) Campaigns

---

Visual Architecture

---

Example Webhook Payload

A CRM sends the following payload to a QuickReply.ai webhook:

{
  "event_name": "new_lead_created",
  "lead_type": "hot",
  "lead_details": {
    "name": "Utkarsh",
    "phone": "[phone]",
    "age": 24,
    "orders": [
      { "id": 123, "amount": 1400 },
      { "id": 456, "amount": 999 }
    ]
  }
}

This payload is received by a Trigger.

How it looks like on QuickReply.ai

---

Why Triggers Alone Have No Value

Triggers:

• Do not segment users

• Do not evaluate conditions

• Do not trigger Journeys or Campaigns

To perform any action, an Event must:

• Identify what happened (event_name)

• Qualify who it happened to (lead_type)

• Decide when execution should start

---

Event Design Patterns

❌ Pattern 1: One Event + Journey-Level Filters (Not Recommended)

Structure

• One Trigger → One Event → Multiple Journeys

• Filtering done inside Journeys or via conditional branches

Issues

• Manual filter setup for every journey

• High risk of human error

• Analytics are mixed

• Hard to scale

This pattern introduces operational dependency and should be avoided.

---

✅ Pattern 2: Multiple Events with Pre-Filled Filters (Recommended)

Structure

• One Trigger → Multiple Events

• Filters defined once at Event level

Example Events

• Hot Lead Created → lead_type = hot

• Warm Lead Created → lead_type = warm

• Cold Lead Created → lead_type = cold

Benefits

• Clean journey configuration

• Faster execution

• Independent analytics per Event

• Lower error probability

---

Pro Tip: Centralise Logic at the Event Level

Because filters are defined on Events, not on Journeys:

• Updating an Event automatically updates:

  • All connected Journeys

  • All connected Campaigns

• No need to edit individual journeys

• Changes reflect in real time

This is especially useful when:

• CRM logic changes

• Lead qualification rules evolve

• Multiple journeys depend on the same Event

---

Handling Multiple Business Actions in One Trigger

A single webhook may contain multiple business actions:

• new_lead_created

• lead_abandoned

• lead_converted

Recommended Setup

Trigger

• CRM – Events

Events

• Hot Lead Created

  • event_name = new_lead_created

  • lead_type = hot

  
• Warm Lead Created

  • event_name = new_lead_created

  • lead_type = warm

  
• Cold Lead Created

  • event_name = new_lead_created

  • lead_type = cold

• Hot Lead Abandoned

  • event_name = lead_abandoned

  • lead_type = hot

  
• Warm Lead Abandoned

  • event_name = lead_abandoned

  • lead_type = warm

  
• Cold Lead Abandoned

  • event_name = lead_abandoned

  • lead_type = cold

  

This keeps:

• Triggers minimal

• Events explicit

• Journeys reusable and clean

Triggers and Events as shown in Journeys

---

Recommended Best Practices Checklist

• Use fewer Triggers

• Create many specific Events

• Avoid journey-level filtering

• Reuse Events across Journeys and Campaigns

• Treat Events as the single source of truth

Triggers ingest data. Events define meaning. Journeys execute logic.

---

Decision Framework: When to Create a New Event

Use this table as a reference guideline:

Scenario	Create New Event?	Reason
Different event_name	✅ Yes	Different business action
Different lead_type	✅ Yes	Different segmentation
Different analytics needed	✅ Yes	Clean reporting
Only message content differs	❌ No	Same Event, different Journey
Same logic reused in many journeys	❌ No	Reuse Event

---

Anti-Patterns to Avoid

❌ Too Many Triggers

• Harder to maintain

• Duplicated webhook logic

• Poor visibility

❌ Journey-Level Filtering

• High human dependency

• Inconsistent behaviour

• Difficult debugging

❌ Generic Events

Example: CRM Event Received This provides no operational clarity and defeats the Event layer.

---

Naming Conventions (Strongly Recommended)

Clear naming is critical once you scale beyond a few Events.

Trigger Naming

Format

<Source System> – <Payload Scope>

Examples

• CRM – Events

• Shopify – Order Webhooks

• Backend – User Lifecycle

Why

• Identifies where data is coming from

• Prevents duplicate triggers for the same system

Triggers should never encode business logic in their names.

---

Event Naming

Format

<Business Action> - <Qualifier (optional)>

Examples

• Lead Created - Hot

• Lead Abandoned - Warm

• Lead Converted - Cold

• Order Placed - High Value

Rules

• Use human-readable names

• Reflect filters applied inside the Event

• Avoid technical field names in Event titles

If a non-technical user cannot understand the Event name, it is poorly named.

---

Journey Naming

Format

<Objective> – <Event Name>

Examples

• Lead Nurture – Hot Lead Created

• Re-Engagement – Warm Lead Abandoned

• Upsell Flow – High Value Order Placed

Why

• Makes analytics self-explanatory

• Easier debugging and audits

Journey Usage Example

Journey: Warm Lead Re-Engagement

• Start Condition: Event → Warm Lead Abandoned

• Actions:

  • WhatsApp reminder after 30 minutes

  • Follow-up message after 24 hours

  • Escalation to agent if no response

Result

• No filters inside Journey

• Clean analytics

• Easy to replicate for Hot / Cold leads

---

Analytics & Reporting Impact

Because Events are granular:

• Conversion rates per lead type are visible

• Drop-offs can be isolated

• Campaign vs Journey performance is comparable

Event-level separation directly improves reporting accuracy.

Final Architectural Summary

Design Once, Scale Forever

• Few Triggers

• Many explicit Events

• Simple Journeys

• Centralised logic

• Reliable analytics

If your Events are correct, everything else becomes easy.