​
Overview

Journey triggers in Masivo enable developers to create sophisticated automated workflows that respond to customer behavior in real-time. By sending events through the API, you can trigger journey transitions that move customers through personalized experiences based on their actions and attributes.
Journey triggers work by matching events to journey edge configurations. When an event matches the specified event type and conditions, customers automatically progress to the next step in the journey.

​
Understanding Journey Triggers

​
How Journey Triggers Work

Journey triggers operate through a three-step process:
  1. Event Emission: Developer sends an event via the POST /behavior/events endpoint
  2. Journey Evaluation: Masivo evaluates all active journeys to find matching trigger conditions
  3. Customer Progression: Qualifying customers automatically move to the next journey step

​
Journey Edge Configuration

Each journey transition (edge) can be configured with:
  • Event Type: The specific event that triggers the transition (e.g., ADD_TO_CART, PURCHASE)
  • Conditions: Additional criteria that must be met for the transition to occur
  • Wait Time: Delay in minutes before the next action is executed

​
1. Sending Events to Trigger Journeys

​
Basic Event Structure

Use the POST /behavior/events endpoint to send events that can trigger journey transitions: 
const triggerJourneyEvent = async (eventData: {
  type: string;
  customer_id: string;
  brand_id: string;
  [key: string]: any;
}) => {
  const response = await fetch(
    "https://app.masivo.ai/api/storefront/v1/behavior/events",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(eventData)
    }
  );

  if (response.ok) {
    const result = await response.json();
    console.log("Event sent successfully:", result.data);
    return result.data;
  } else {
    const error = await response.json();
    console.error("Event failed:", error.details);
    throw new Error(error.details);
  }
};

​
Event Processing for Journeys

When you send an event, Masivo automatically:
  1. Enqueues for Journey Processing: Events are added to the journeys_events queue
  2. Evaluates Active Journeys: Checks all active journeys for matching trigger conditions
  3. Processes Customer Transitions: Moves qualifying customers to the next journey step
  4. Applies Wait Times: Schedules future actions based on configured delays

​
2. Cart Abandonment Journey Example

​
Scenario: E-commerce Cart Abandonment Recovery

Let’s build a complete cart abandonment journey that triggers when customers add items to cart but don’t complete purchase within 30 minutes.

​
Step 1: Send ADD_TO_CART Event

const sendAddToCartEvent = async (customerId: string, productData: any) => {
  const eventData = {
    type: "ADD_TO_CART",
    customer_id: customerId,
    brand_id: "your-brand-id",
    product: {
      sku: productData.sku,
      amount: productData.quantity,
      value: productData.price,
      tags: {
        category: productData.category,
        brand: productData.brand
      },
      metadata: {
        product_name: productData.name,
        image_url: productData.image
      }
    },
    tags: {
      cart_value: productData.price * productData.quantity,
      cart_items_count: 1,
      last_cart_update: new Date().toISOString()
    }
  };

  return await triggerJourneyEvent(eventData);
};

// Example usage
await sendAddToCartEvent("customer-123", {
  sku: "PROD-001",
  name: "Premium Headphones",
  price: 199.99,
  quantity: 1,
  category: "electronics",
  brand: "AudioTech",
  image: "https://example.com/headphones.jpg"
});

​
Step 2: Journey Configuration

The journey would be configured with these transitions: Trigger Edge (Root → Wait Node):
  • Event Type: ADD_TO_CART
  • Conditions: None (triggers for any cart addition)
  • Wait Time: 30 minutes
Follow-up Edge (Wait Node → Email Node):
  • Event Type: null (time-based transition)
  • Conditions: Customer has not made a purchase
  • Wait Time: 0 minutes (fires immediately after wait period)

​
Step 3: Handle Purchase Completion

const sendPurchaseEvent = async (customerId: string, orderData: any) => {
  const eventData = {
    type: "PURCHASE",
    customer_id: customerId,
    brand_id: "your-brand-id",
    order: {
      purchase_id: orderData.orderId,
      value: orderData.total,
      products: orderData.items.map(item => ({
        sku: item.sku,
        amount: item.quantity,
        value: item.price
      })),
      payment_method: orderData.paymentMethod
    },
    tags: {
      order_completed: true,
      purchase_value: orderData.total,
      purchase_date: new Date().toISOString()
    }
  };

  return await triggerJourneyEvent(eventData);
};
When a PURCHASE event is received, customers are automatically removed from the cart abandonment journey, preventing them from receiving the abandonment email.

​
Conclusion

Journey triggers in Masivo provide a powerful way to create responsive, automated customer experiences. By strategically sending events and configuring journey transitions with appropriate wait times and conditions, you can build sophisticated workflows that engage customers at the perfect moments. The combination of real-time event processing, flexible timing controls, and condition-based branching enables you to create personalized customer journeys that adapt to individual behavior and preferences, driving engagement and conversions at scale. For more information about creating and managing journeys, see the Create Journeys Guide.