---
title: 'User forwards'
section: features
summary: "User forwards redirect a user's incoming calls to another destination when a specific event occurs, such as busy, no answer, or DND."
updated: '2026-08-12'
---

> A **user forward** redirects a user's incoming calls to a chosen destination when a trigger event occurs, such as when they are busy, unavailable, or have DND active.

## Overview

Forwards are sub-records on a user. Each rule combines a scope (internal or external calls), a trigger event, and a target. You can create multiple rules for the same user to cover different scenarios: forward internal calls to a colleague when busy while letting external calls ring to voicemail on timeout. The most common pattern is a "Timeout" rule pointing to voicemail so callers can always leave a message.

## What it does

The target field controls which additional fields appear. Voicemail targets also let you choose a greeting type.



## See also

- [Do not disturb](dnds.md) - create DND rules that pair with the "On DND" forward event.
- [Users](users.md) - the parent entity for forwarding rules.

```yaml fields
enabled:
  label: Enabled
  api: enabled
  tab: General
  hint: 'Whether this forwarding rule is active. Toggle off to pause without deleting the rule.'
type:
  label: Type
  api: type
  tab: General
  hint: 'Which call direction this rule applies to.'
  values:
    -
      value: internal
      label: Internal
      text: 'Forwards calls originating from within the PBX.'
    -
      value: external
      label: External
      text: 'Forwards calls arriving from outside the PBX.'
caller_identity_id:
  label: 'Phone number'
  api: caller_identity_id
  tab: General
  hint: 'The outgoing number shown to the forwarding destination when this rule fires.'
  when: 'Scope is External'
event:
  label: Event
  api: event
  tab: General
  hint: 'The condition that triggers this forward.'
  values:
    -
      value: always
      label: Always
      text: "Every incoming call is forwarded immediately. The user's phone never rings."
    -
      value: busy
      label: Busy
      text: 'Triggers when the user is already on a call.'
    -
      value: after_ten_seconds
      label: 'After 10 secs'
      text: 'Triggers if the phone rings but is not answered within 10 seconds.'
    -
      value: timeout
      label: Timeout
      text: 'Triggers when the PBX ring timeout expires without an answer.'
    -
      value: on_dnd
      label: 'On DND'
      text: 'Triggers when the user has Do not disturb active.'
    -
      value: on_logout
      label: 'On logout'
      text: 'Triggers when the user is logged out of all devices.'
target:
  label: Target
  api: target
  tab: General
  hint: 'Where the call goes when this rule fires.'
  values:
    -
      value: fix_number
      label: 'Phone number'
      text: 'Forwards to an external phone number.'
    -
      value: extension
      label: Extension
      text: 'Forwards to a PBX extension number.'
    -
      value: user
      label: User
      text: 'Forwards to another user on the PBX.'
    -
      value: voicemail
      label: Voicemail
      text: 'Forwards to a voicemail box.'
    -
      value: hangup
      label: 'Hangup / Ignore'
      text: 'Rejects the call immediately.'
target_option_fix_number:
  label: Number
  tab: 'Phone number'
  hint: 'The external phone number to forward the call to. Shown when Target is Phone number.'
  when: 'Target is Phone number'
target_option_extension_id:
  label: Extension
  tab: Extension
  hint: 'The PBX extension to forward the call to. Shown when Target is Extension.'
  when: 'Target is Extension'
target_option_user_id:
  label: User
  tab: User
  hint: 'The user to forward the call to. Shown when Target is User.'
  when: 'Target is User'
target_option_voicemail_user_id:
  label: User
  tab: Voicemail
  hint: 'The user whose voicemail box receives the forwarded call. Shown when Target is Voicemail.'
  when: 'Target is Voicemail'
target_option_voicemail_message_type:
  label: 'Message type'
  tab: Voicemail
  hint: 'The voicemail greeting played to the caller. Shown when Target is Voicemail.'
  when: 'Target is Voicemail'
```