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

# Wait Steps

> Control timing between journey messages

Wait steps pause the journey for a specified duration before proceeding. Use them to space out messages appropriately.

## Configuring Wait Steps

### Duration

Set how long to wait:

```yaml theme={null}
Wait: 24 hours
Wait: 3 days
Wait: 120 minutes
```

### Available Units

| Unit    | Use Case                   |
| ------- | -------------------------- |
| Minutes | Testing, urgent follow-ups |
| Hours   | Same-day follow-up         |
| Days    | Standard spacing           |

## How Waits Work

When a contact reaches a wait step:

1. System calculates `next_step_at` = current time + duration
2. Contact pauses at the wait step
3. Background job checks for contacts past their `next_step_at`
4. Matching contacts proceed to the next step

<Note>
  The journey executor polls every 5 seconds. A "wait 1 hour" may have up to 5 seconds of variance.
</Note>

### Safety Limits

To prevent runaway journeys, the following limits are enforced:

* **1,000 max step executions** per enrollment — if a contact exceeds this, the enrollment is terminated
* **30-day max enrollment duration** — enrollments older than 30 days are automatically expired

## Best Practices

### Spacing Recommendations

| Journey Type   | Typical Spacing           |
| -------------- | ------------------------- |
| Welcome series | 1-3 days between messages |
| Onboarding     | 2-5 days                  |
| Re-engagement  | 3-7 days                  |
| Educational    | 1-2 weeks                 |

### Avoid Over-Messaging

Too many messages too quickly leads to opt-outs:

```
❌ Don't
Send → Wait 1 hour → Send → Wait 1 hour → Send

✅ Do
Send → Wait 24 hours → Send → Wait 3 days → Send
```

### Consider Subscriber Fatigue

After 5-7 messages, engagement typically drops. Either:

* End the journey
* Increase wait times significantly
* Transition to regular campaigns

## Wait Until Step

The `wait_until` step type is different from a regular wait. Instead of pausing for a duration, it holds the contact until a specific time of day:

```yaml theme={null}
Step: Wait Until
Time: "09:00"
```

This waits until the next occurrence of 9:00 AM **UTC**. If the contact reaches this step at 7:00 AM UTC, they wait 2 hours. If they reach it at 10:00 AM UTC, they wait until 9:00 AM UTC the next day.

<Note>
  Wait Until times are evaluated in **UTC**. The backend does not currently convert to the contact's local timezone for Wait Until evaluation. Plan your times accordingly.
</Note>

Use `wait_until` when you want messages to arrive at a consistent time of day regardless of when the contact entered the journey or completed the previous step.

## Time-of-Day Considerations

Regular wait steps don't account for time of day. A message sent at 3 AM may not be ideal.

**Current behavior**: Wait steps pause for a duration from whenever the previous step completed.

**Tip**: Use a `wait_until` step to ensure messages are delivered at an appropriate time of day (e.g., wait until 9:00 AM before sending).

## Wait + Campaign Interaction

Contacts in journeys may also receive scheduled campaigns. Use frequency capping to prevent overlap:

```
Campaign: Skip if sent within 12 hours
Journey: Uses natural wait spacing
```

This prevents a journey message right before/after a campaign.

## Editing Wait Duration

You can change wait duration on active journeys:

| Scenario           | Effect                                     |
| ------------------ | ------------------------------------------ |
| Increase wait      | Contacts currently waiting may wait longer |
| Decrease wait      | Contacts may proceed sooner                |
| Contacts past wait | Not affected, already moved on             |

## Examples

### Short Welcome (Aggressive)

```
Send → Wait 6 hours → Send → Wait 1 day → Send → Exit
```

3 messages in \~30 hours. Best for time-sensitive offers.

### Standard Welcome

```
Send → Wait 1 day → Send → Wait 3 days → Send → Wait 1 week → Send → Exit
```

4 messages over \~11 days. Balanced approach.

### Slow Nurture

```
Send → Wait 1 week → Send → Wait 2 weeks → Send → Wait 1 month → Send → Exit
```

4 messages over \~7 weeks. Gentle, long-term relationship building.

## Monitoring Wait Steps

In the journey dashboard, see:

* Contacts currently in each wait step
* Average time in wait
* Contacts that exited during wait (unsubscribed)

## Troubleshooting

<AccordionGroup>
  <Accordion title="Contacts stuck in wait">
    Check:

    * Is the job server running?
    * Is `next_step_at` in the past?
    * Are there database issues?
  </Accordion>

  <Accordion title="Waits not accurate">
    The journey executor polls every 5 seconds. Variances should be minimal (under 5 seconds).
  </Accordion>

  <Accordion title="Want time-of-day control">
    Use the `wait_until` step type to hold contacts until a specific HH:MM time before proceeding.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Journey Examples" icon="lightbulb" href="/guides/journeys/examples">
    Common patterns
  </Card>

  <Card title="Building Journeys" icon="hammer" href="/guides/journeys/building-journeys">
    Full setup guide
  </Card>
</CardGroup>