# Flows

Source: https://pushary.com/docs/web-push/server-sdk/flows
Last updated: 2026-05-11

> Automate notification sequences based on user behavior

## Overview [#overview]

Flows allow you to create automated notification sequences triggered by user actions. Build sophisticated engagement workflows that respond to subscriber behavior in real-time.

## Use Cases [#use-cases]

* **Welcome Series**: Send onboarding messages after subscription
* **Re-engagement**: Trigger notifications when users dismiss or ignore messages
* **Conversion Funnels**: Guide users through multi-step processes
* **Behavioral Campaigns**: Respond to user interactions automatically

## Flow Structure [#flow-structure]

A flow consists of:

1. **Trigger**: Event that starts the flow execution
2. **Steps**: Sequence of actions (notifications, delays, exits)
3. **Status**: Current state of the flow (draft, active, paused, archived)

## Trigger Types [#trigger-types]

Flows can be triggered by the following events:

| Trigger                   | Description                   |
| ------------------------- | ----------------------------- |
| `notification_click`      | User clicks a notification    |
| `notification_impression` | User views a notification     |
| `notification_dismiss`    | User dismisses a notification |
| `subscription`            | New subscriber joins          |
| `unsubscription`          | User unsubscribes             |

## Step Types [#step-types]

### Send Notification [#send-notification]

Send a push notification to the subscriber.

```typescript
{
  stepType: 'send_notification',
  config: {
    notification: {
      title: 'Welcome!',
      body: 'Thanks for subscribing',
      iconUrl: 'https://example.com/icon.png',
      imageUrl: 'https://example.com/banner.png',
      actionUrl: 'https://example.com/welcome'
    }
  }
}
```

### Delay [#delay]

Wait for a specified duration before continuing.

```typescript
{
  stepType: 'delay',
  config: {
    delay: {
      value: 24,
      unit: 'hours'
    }
  }
}
```

**Units**: `seconds`, `minutes`, `hours`, `days`

### Exit [#exit]

End the flow execution.

```typescript
{
  stepType: 'exit',
  config: {}
}
```

## Flow Example [#flow-example]

A complete welcome flow:

```typescript
{
  name: 'Welcome Series',
  description: 'Onboard new subscribers',
  triggerType: 'subscription',
  status: 'active',
  steps: [
    {
      stepOrder: 0,
      stepType: 'send_notification',
      config: {
        notification: {
          title: 'Welcome to Pushary!',
          body: 'Thanks for subscribing. Get started below.',
          actionUrl: 'https://example.com/get-started'
        }
      }
    },
    {
      stepOrder: 1,
      stepType: 'delay',
      config: {
        delay: { value: 1, unit: 'days' }
      }
    },
    {
      stepOrder: 2,
      stepType: 'send_notification',
      config: {
        notification: {
          title: 'Pro Tips',
          body: 'Here are some tips to get the most out of our service',
          actionUrl: 'https://example.com/tips'
        }
      }
    }
  ]
}
```

## Flow Status [#flow-status]

| Status     | Description                             |
| ---------- | --------------------------------------- |
| `draft`    | Flow is being created (not executing)   |
| `active`   | Flow is running and processing triggers |
| `paused`   | Flow is temporarily disabled            |
| `archived` | Flow is permanently disabled            |

## Execution Status [#execution-status]

When a flow is triggered for a subscriber, an execution is created:

| Status      | Description                             |
| ----------- | --------------------------------------- |
| `pending`   | Waiting to start                        |
| `active`    | Currently processing a step             |
| `waiting`   | In a delay step                         |
| `completed` | All steps finished                      |
| `cancelled` | Stopped early (subscriber unsubscribed) |
| `failed`    | Error occurred during execution         |

## Plan Limits [#plan-limits]

Flows respect your plan's notification limits:

* Each notification sent in a flow counts toward your monthly limit
* If limit is exceeded, flow execution is cancelled
* Subscriber must be `active` for flow to execute

## Best Practices [#best-practices]

1. **Start Simple**: Begin with 2-3 step flows
2. **Test First**: Use draft status to preview flow logic
3. **Monitor Performance**: Track execution counts and completion rates
4. **Respect Timing**: Don't send too many notifications too quickly
5. **Handle Failures**: Flows stop if subscriber unsubscribes

## API Integration [#api-integration]

Flows can be managed programmatically via the Server API. See [API Reference](/docs/web-push/server-sdk/api-reference) for REST endpoints.

```typescript
import { createPusharyServer } from '@pushary/server'

const pushary = createPusharyServer({
  apiKey: process.env.PUSHARY_API_KEY
})

const flow = await pushary.flows.create({
  name: 'Welcome Series',
  triggerType: 'subscription',
  steps: [
    {
      stepOrder: 0,
      stepType: 'send_notification',
      config: {
        notification: {
          title: 'Welcome!',
          body: 'Thanks for joining'
        }
      }
    }
  ]
})

await pushary.flows.activate(flow.id)
```

## Dashboard [#dashboard]

Flows can also be created and managed through the Pushary dashboard at `/dashboard/flows`.