User Call Forwarding Targets

A user call forwarding target refers to an external phone number, a device, or a co-worker (another user extension within the same account) that will ring—either sequentially or simultaneously—when the user receives an incoming call, in addition to the user’s own devices and RingCentral apps (mobile and desktop app).

This feature allows users to answer incoming calls on the device or app that best suits their needs. For example, a user can set their personal mobile number as a forwarding target, ensuring that their mobile phone rings alongside their RingCentral business number—even if the RingCentral mobile app is not installed on their mobile phone.

Common use cases include:

• External phone number – Forward incoming calls to an external phone number — for example, the user’s personal mobile number — allowing the user to answer calls without installing the RingCentral mobile app on their personal device.
• Co-worker’s extension – Forward calls to a colleague’s extension to ensure coverage when the user is temporarily having access to the colleague's business phone, or expects the co-worker to answer incoming calls on their behalf.

Call forwarding targets can be set separately for the following user call handling rules:

• The “work-hours” state call handling rule.
• The “after-hours” state call handling rule.
• The “agent” state call handling rule.
• Any custom call handling rule.

With the ability to configure different call forwarding targets for different call handling rules, users can optimize how their incoming calls are managed in various scenarios. This flexibility ensures that calls are answered in the most effective way based on the user’s schedule and preferences.

Call forwarding target configurations are managed through the “Ring Settings” of a call handling rule. These settings allow users to add or remove targets, define the ringing duration, group or ungroup the targets, enable or disable specific targets, and choose the ringing mode—either ringing all targets simultaneously or in a predefined order.

There is a special setting for desktop and mobile app targets that ensures they always ring for incoming calls alongside other enabled ring group targets, regardless of whether the dispatching type is set to "RingAtOnce" or "RingInOrder".

Example use case 1: Work hours vs. call queue

Alex works at a financial institution and uses both a RingCentral desk phone and a laptop with the RingCentral app installed. During work hours, Alex sits at his desk and can receive incoming calls on either device. In addition, Alex is a member of a call queue that handles new inquiries together with his colleagues, so he receives calls either directly to his business number or through the call queue.

To quickly distinguish between direct calls and call queue calls, Alex configures the call handling rules for the work-hours state and the agent state as follows:

• Work-hours state ring settings rule – Direct business calls ring only the RingCentral app on his laptop.

• Agent state ring settings rule – Call queue calls ring only his RingCentral desk phone.

This setup helps Alex easily identify the type of incoming call and respond appropriately.

Example use case 2: After hours

Outside of work hours, Alex wants to ensure he can still receive urgent direct calls without being tied to his desk, but he does not have the RingCentral mobile app installed on his personal phone. To address this, he sets up an after-hours rule so that incoming direct business calls ring his personal mobile phone. This allows Alex to stay reachable for important calls while maintaining flexibility after leaving the office. He also configures the rule to prevent his RingCentral desk phone from ringing after hours, which could disturb colleagues sitting nearby.

• After-hours state ring settings rule:

Configure call forwarding targets and ring settings via API

All of the configurations demonstrated in the examples above can be set programmatically through the platform APIs. This is done using the User Call Handling Configuration APIs, which allow developers to define state-based rules (e.g., work hours, after hours, agent state) as well as custom rules tailored to specific call handling requirements.

A call forwarding target's parameters are specified within a “RingGroupAction” dispatching action object. The "RingGroupAction" action is an object which contains information about a call forwarding target, where the target can be set enabled or disabled and the specified ringing duration.

Example of a “RingGroupAction” object

{
      "type": "RingGroupAction",
      "enabled": true,
      "targets": [
        {
          "type": "PhoneNumberRingTarget",
          "destination": {
            "phoneNumber": "+12093151072"
          },
          "name": "Personal Number"
        }],
      "duration": 20
}

RingGroupAction Object

Ring group targets Object

The targets object can be specified with one of the following target types:

• "AllDesktopRingTarget"
• "AllMobileRingTarget"
• "CoworkerRingTarget"
• "PhoneNumberRingTarget"
• "DeviceRingTarget"
• "HotdeskRingTarget"
• "ImsPhoneNumberRingTarget"
• "IntegrationRingTarget"

AllDesktopRingTarget object

Refers to all RingCentral apps (desktop, laptop, and web). This forwarding target is automatically created by the system as the user’s personal default forwarding target. It cannot be removed or deleted from the user’s personal call forwarding list; however, it can be enabled or disabled, and its ring duration can be modified.

This type of forwarding target can be added or removed when configured as a co-worker forwarding target. See the Requirements section for details on setting it up as a co-worker forwarding target.

AllMobileRingTarget object

Refers to all RingCentral mobile apps (Android and iOS). This forwarding target is automatically created by the system as the user’s personal default forwarding target. It cannot be removed or deleted from the user’s personal call forwarding list; however, it can be enabled or disabled, and its ring duration can be modified.

This type of forwarding target can be added or removed when configured as a co-worker forwarding target. See the Requirements section for details on setting it up as a co-worker forwarding target.

PhoneNumberRingTarget object

Refers to an external PSTN phone number.

CoworkerRingTarget object

Refers to a user extension within the same RingCentral account.

DeviceRingTarget object

Refers to a hard phone (a SIP device) registered and assigned to a user extension within the same RingCentral account.

This forwarding target is automatically created by the system as the user’s personal default forwarding target if a user is assigned with a device (usually a desk phone). It cannot be removed or deleted from the user’s personal call forwarding list; however, it can be enabled or disabled, and its ring duration can be modified.

This type of forwarding target can be added or removed when configured as a co-worker forwarding target. See the Requirements section for details on setting it up as a co-worker forwarding target.

HotdeskRingTarget object

Refers to a Hot Desk phone registered within the same RingCentral account.

ImsPhoneNumberRingTarget object

Refers to an IMS phone number. Requires the user to have an active IMS phone number.

IntegrationRingTarget object

Refers to an integration (MS-Team or FMC Lite). Required account special configurations!

Destination object

Refers to a PSTN phone number target

Extension object

Refers to a user extension who owns the forwarding target.

Device object

Refers to a user own device or a co-worker device

Integration object

RingAlwaysGroupAction Object

Refers to the user's own desktop app or mobile app configured to always ring.

Ring always group targets object

The targets object within a "RingAlwaysGroupAction" object can be specified with one of the following target types:

• "AllDesktopRingTarget". See the AllDesktopRingTarget object
• "AllMobileRingTarget". See the AllMobileRingTarget object

Read user call forwarding target configurations

As user’s call forwarding targets are set per call handling rule, developers can read the user's call forwarding targets for their "work-hours", "after-hours" and "agent" state-based rules and custom rules using the following APIs:

Read state-base rules:

GET /restapi/v2/accounts/~/extensions/~/comm-handling/voice/state-rules/work-hours

GET /restapi/v2/accounts/~/extensions/~/comm-handling/voice/state-rules/after-hours

GET /restapi/v2/accounts/~/extensions/~/comm-handling/voice/state-rules/agent

Read a custom rule:

GET /restapi/v2/accounts/~/extensions/~/comm-handling/voice/interaction-rules/{ruleId}

Example response with "RingGroupAction" and "RingAlwaysGroupAction" info

...
  {
    "type": "RingGroupAction",
    "enabled": true,
    "targets": [
      {
        "type": "AllDesktopRingTarget",
        "name": "My desktop"
      }
    ],
    "duration": 20
  },
  {
    "type": "RingGroupAction",
    "enabled": false,
    "targets": [
      {
        "type": "PhoneNumberRingTarget",
        "destination": {
          "phoneNumber": "+16501234567"
        },
        "name": "Temporary number"
      }
    ],
    "duration": 30
  },
  {
    "type": "RingGroupAction",
    "enabled": false,
    "targets": [
      {
        "type": "CoworkerRingTarget",
        "extension": {
          "id": "2465164005"
        }
      }
    ],
    "duration": 20
  },
  {
    "type": "RingAlwaysGroupAction",
    "enabled": true,
    "targets": [
      {
        "type": "AllMobileRingTarget",
        "name": "My mobile apps"
      }
    ]
  }
...

Set user call forwarding target configurations

As user’s call forwarding targets are set per call handling rule, developers can update the user's call forwarding targets for their "work-hours", "after-hours" and "agent" state-based rules and custom rules using the following APIs:

Update state-base rules:

PATCH /restapi/v2/accounts/~/extensions/~/comm-handling/voice/state-rules/work-hours

PATCH /restapi/v2/accounts/~/extensions/~/comm-handling/voice/state-rules/after-hours

PATCH /restapi/v2/accounts/~/extensions/~/comm-handling/voice/state-rules/agent

Update a custom rule:

PATCH /restapi/v2/accounts/~/extensions/~/comm-handling/voice/interaction-rules/{ruleId}

The recommended approach to updating call forwarding targets is to first retrieve the current call handling settings, then modify, add, or remove the "RingGroupAction" or "RingAlwaysGroupAction" within the actions list as needed, and finally update the entire call handling dispatching object.

Example of setting the work-hours state-based call forwarding targets

The following example demonstrates how to add a new call forwarding target of type "PhoneNumberRingTarget" to the work-hours state-based rule.

$ npm install @ringcentral/sdk --save

const RC = require('@ringcentral/sdk').SDK

// Instantiate the SDK and get the platform instance
var rcsdk = new RC({
    server: 'https://platform.ringcentral.com',
    clientId: 'RC_APP_CLIENT_ID',
    clientSecret: 'RC_APP_CLIENT_SECRET'
});
var platform = rcsdk.platform();

/* Authenticate a user using a personal JWT token */
platform.login({ jwt: 'RC_USER_JWT' })

platform.on(platform.events.loginSuccess, () => {
    read_user_workhours_state_rules()
})

platform.on(platform.events.loginError, function(e){
    console.log("Unable to authenticate to platform. Check credentials.", e.message)
    process.exit(1)
});

/*
* Read existing rules
*/
async function read_user_workhours_state_rules() {
  try {
    let endpoint = '/restapi/v2/accounts/~/extensions/~/comm-handling/voice/state-rules/work-hours'
    var resp = await platform.get(endpoint)
    var jsonObj = await resp.json()
    await update_user_workhours_state_rules(jsonObj.dispatching)
  } catch (e) {
    console.log("Unable to read user Work-Hours state rules. ", e.message);
  }
}

/*
* Update the Work-Hours state rules with new values
*/
async function update_user_workhours_state_rules(dispatching){
  try {
    // new phone number forwarding target
    let newTarget = {
        type: "RingGroupAction",
        enabled: true,
        targets: [
          {
            type: "PhoneNumberRingTarget",
            destination: {
                phoneNumber: "+13121234567"
            },
            name: "Temporary number"
          }
        ],
        duration: 25 // 5 rings
    }
    dispatching.actions.unshift(newTarget)

    // Update the entire dispatching configurations
    console.log(JSON.stringify(dispatching, null, 4))
    let bodyParams = {
        dispatching: dispatching
      }
    let endpoint = '/restapi/v2/accounts/~/extensions/~/comm-handling/voice/state-rules/work-hours'
    var resp = await platform.patch(endpoint, bodyParams)
    var jsonObj = await resp.json()
    console.log(JSON.stringify(jsonObj, null, 4))
  } catch (e) {
    console.log("Unable to update user Work-Hours state rules. ", e.message);
  }
}

$ curl -sS https://getcomposer.org/installer | php
$ php composer.phar require ringcentral/ringcentral-php

<?php
require('vendor/autoload.php');

// Instantiate the SDK and get the platform instance
$rcsdk = new RingCentral\SDK\SDK( 'RC_APP_CLIENT_ID', 'RC_APP_CLIENT_SECRET', 'https://platform.ringcentral.com' );
$platform = $rcsdk->platform();

/* Authenticate a user using a personal JWT token */
$platform->login(["jwt" => 'RC_USER_JWT']);

read_user_workhours_state_rules();

/*
* Read existing rules
*/
function read_user_workhours_state_rules() {
  global $platform;
  try {
    $endpoint = "/restapi/v2/accounts/~/extensions/~/comm-handling/voice/state-rules/work-hours";
    $resp = $platform->get($endpoint);
    update_user_workhours_state_rules($resp->json()->dispatching);
  }catch (\RingCentral\SDK\Http\ApiException $e) {
    // Getting error messages using PHP native interface
    print 'HTTP Error: ' . $e->getMessage() . PHP_EOL;
    // Another way to get message, but keep in mind, that there could be no response if request has failed completely
    print "Unable to read user Work-Hours state rules. " . $e->apiResponse->response()->error() . PHP_EOL;
  }
}

/*
* Update the Work-Hours state rules with new values
*/
function update_user_workhours_state_rules($dispatching){
  global $platform;
  try {
    // new phone number forwarding target
    $newTarget = [
        "type" => "RingGroupAction",
        "enabled" => true,
        "targets" => [
          [
            "type" => "PhoneNumberRingTarget",
            "destination" => [
                "phoneNumber" => "+13121234567"
            ],
            "name" => "Temporary number"
          ]
        ],
        "duration" => 25 // 5 rings
    ];
    array_unshift($dispatching->actions, $newTarget);
    $bodyParams = array( 'dispatching' =>  $dispatching );
    $endpoint = "/restapi/v2/accounts/~/extensions/~/comm-handling/voice/state-rules/work-hours";
    $resp = $platform->patch($endpoint, $bodyParams);
    print_r ($resp->json());
  }catch (\RingCentral\SDK\Http\ApiException $e) {
    // Getting error messages using PHP native interface
    print 'HTTP Error: ' . $e->getMessage() . PHP_EOL;
    // Another way to get message, but keep in mind, that there could be no response if request has failed completely
    print "Unable to update user Work-Hours state rules. " . $e->apiResponse->response()->error() . PHP_EOL;
  }
}
?>

$ pip install ringcentral

from ringcentral import SDK
import json

#
# Read existing rules
#
def read_user_workhours_state_rules():
    try:
        endpoint = '/restapi/v2/accounts/~/extensions/~/comm-handling/voice/state-rules/work-hours'
        resp = platform.get(endpoint)
        jsonObj = resp.json_dict()
        update_user_workhours_state_rules(jsonObj['dispatching'])
    except Exception as e:
        print ("Unable to read user Work-Hours state rules. " + str(e))

#
# Update the Work-Hours state rules with new values
#
def update_user_workhours_state_rules(dispatching):
    try:
        # new phone number forwarding target
        newTarget = {
            "type": "RingGroupAction",
            "enabled": True,
            "targets": [
              {
                "type": "PhoneNumberRingTarget",
                "destination": {
                    "phoneNumber": "+13121234567"
                },
                "name": "Temporary number"
              }
            ],
            "duration": 25 # 5 rings
        }
        dispatching['actions'].insert(0, newTarget)
        bodyParams = {
            'dispatching': dispatching
          }
        endpoint = '/restapi/v2/accounts/~/extensions/~/comm-handling/voice/state-rules/work-hours'
        resp = platform.patch(endpoint, bodyParams)
        jsonObj = resp.json_dict()
        print(json.dumps(jsonObj, indent=2, sort_keys=True))
    except Exception as e:
      print ("Unable to update user Work-Hours state rules. " + str(e))


# Authenticate a user using a personal JWT token
def login():
  try:
      platform.login( jwt= "RC_USER_JWT" )
      read_user_workhours_state_rules()
  except Exception as e:
      print ("Unable to authenticate to platform. Check credentials. " + str(e))

# Instantiate the SDK and get the platform instance
rcsdk = SDK("RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com")
platform = rcsdk.platform()

login()

$ gem install ringcentral-sdk dotenv

require 'ringcentral'

#
# Read existing rules
#
def read_user_workhours_state_rules()
  begin
    endpoint = '/restapi/v2/accounts/~/extensions/~/comm-handling/voice/state-rules/work-hours'
    resp = $platform.get(endpoint)
    jsonObj = resp.body()
    update_user_workhours_state_rules(jsonObj['dispatching'])
  rescue StandardError => e
    puts ("Unable to read user Work-Hours state rules. " + e.to_s)
  end
end

#
# Update the Work-Hours state rules with new values
#
def update_user_workhours_state_rules(dispatching)
  begin
    # new phone number forwarding target
    newTarget = {
      "type" => "RingGroupAction",
      "enabled" => true,
      "targets" => [
        {
          "type" => "PhoneNumberRingTarget",
          "destination" => {
            "phoneNumber" => "+13121234567"
          },
          "name" => "Temporary number"
        }
      ],
      "duration" => 25 # 5 rings
    }
    dispatching["actions"].unshift(newTarget)

    bodyParams = {
          dispatching: dispatching
        }
    endpoint = '/restapi/v2/accounts/~/extensions/~/comm-handling/voice/state-rules/work-hours'
    resp = $platform.patch(endpoint, payload: bodyParams)
    puts(resp.body)
  rescue StandardError => e
    puts ("Unable to update user Work-Hours state rules. " + e.to_s)
  end
end

# Authenticate a user using a personal JWT token
def login()
  begin
    $platform.authorize( jwt: "RC_USER_JWT" )
    read_user_workhours_state_rules()
  rescue StandardError => e
    puts ("Unable to authenticate to platform. Check credentials. " + e.to_s)
  end
end

# Instantiate the SDK and get the platform instance
$platform = RingCentral.new( "RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com" )

login()

Sample response

{
    "id": "work-hours",
    "displayName": "Work Hours",
    "dispatching": {
        "actions": [
            {
                "type": "PlayWelcomePromptAction",
                "greeting": {
                    "effectiveGreetingType": "Preset",
                    "preset": {
                        "id": "66048"
                    }
                },
                "enabled": true
            },
            ...
            {
                "type": "RingGroupAction",
                "enabled": true,
                "targets": [
                    {
                        "type": "PhoneNumberRingTarget",
                        "destination": {
                            "phoneNumber": "+13121234567"
                        },
                        "name": "Temporary number"
                    }
                ],
                "duration": 25
            },
            ...

Co-worker forwarding target configurations requirements

To configure co-worker forwarding targets for the following target types, the "CoworkerLineAndAppsForwarding" feature must be enabled on the account before these targets can be set up:

• "AllMobileRingTarget"
• "AllDesktopRingTarget"
• "DeviceRingTarget"

The following API allows developers to verify whether the required feature is enabled for their account.

GET `/restapi/v1.0/account/~/extension/[extId]/features?featureId=CoworkerLineAndAppsForwarding`

Example response

{
  "records" : [ {
    "id" : "CoworkerLineAndAppsForwarding",
    "available" : false,
    "reason" : {
      "code" : "AccountLimitation",
      "message" : "The feature is turned off for the current account"
    }
  } ]
}

To enable this feature for an account, the customer can submit a request to RingCentral Customer Support or contact their RingCentral Account Manager.

Read user call forwarding targets

To list all call forwarding targets configured across a user’s state-based and custom call handling rules, developers can use the Get Forwarding Targets API. This endpoint returns detailed information about each forwarding target; however, it does not include the associated rule identity.

Delete user call forwarding targets

If a call forwarding target is no longer available or no longer needed, it can be removed from the user's call forwarding targets list.

While a call forwarding target can be removed from an individual call handling rule (state-based or custom) using the User Call Handling Rule API, developers can remove the target from all rules (if configured for multiple rules) by calling the Delete Forwarding Targets API. This is equivalent to selecting “Yes, all rules” in the RingCentral app (Settings -> Phone -> Incoming call rules) or user admin portal when manually deleting a forwarding target.