Call Forwarding and Call Flipping

Last updated: 2024-01-31Contributors
Edit this page

Call Forwarding allows incoming phone calls to be directed to another phone number. This is handy when recipients have multiple phone numbers and/or a physical phone at which they can be reached. There are two primary ways calls are directed to other phones/numbers:

  • Call Forwarding applies to incoming calls, and allows those calls to ring at one or more numbers sequentially or simultaneously.

  • Call Flipping applies to active calls, and allows a speaker to instantly transfer an active call to another phone or device without having to terminate the call.

Phone Types

Type Description
PhoneLine This refers to a RingCentral device or hard-phone. When specifying this type when creating/registering a new call forwarding number, the developer must also specify the device id (see API Reference).
Home Home phone number.
Mobile Mobile phone number.
Work Work phone number.
Other A phone number of any other type.

Create a Forwarding Number

To create a forwarding number:

  • Specify the phoneNumber parameter. This is a phone number for an incoming call to be forwarded to.
  • Specify type parameter using one of the type's value from the table above. The default value is "Other"
  • Specify the label (title of the forwarding number object) parameter if the type is omitted or specified as "Other".
  • Specify the id for the device object if the type is specified as "PhoneLine".
  • Make a POST request to /restapi/v1.0/account/{accountId}/extension/{extensionId}/forwarding-number endpoint.

Important

The label will be ignored if the type value is different than "Other"!

The phoneNumber cannot be any direct number of any extension under the same account!

The device parameter cannot be specified together with the phoneNumber!

A list of valid device ids can be retrieved by calling the Get Extension Device List API.

Required permission(s): EditExtensions

Sample code to create a forwarding number object

The following code sample shows how to create a forwarding number object. The id value from the response can be used to specify a rule when creating a custom answering rule.

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

var rcsdk = new RC({
    'server':       process.env.RC_SERVER_URL,
    'clientId':     process.env.RC_CLIENT_ID,
    'clientSecret': process.env.RC_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({ 'jwt':  process.env.RC_JWT })

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

async function create_forwarding_number_by_number() {
  try {
    var resp = await platform.post('/restapi/v1.0/account/~/extension/~/forwarding-number', {
      phoneNumber: "11235557890",
      type: "Other",
      label: "My ATT number"
    })
    var jsonObj = await resp.sjon()
    console.log("Forwarding number created.")
    console.log("Forwarding number id: " + jsonObj.id)
  } catch (e) {
    console.log(e.message)
  }
}
#!/usr/bin/python

# You get the environment parameters from your 
# application dashbord in your developer account 
# https://developers.ringcentral.com

import os
import sys

from dotenv import load_dotenv
from ringcentral import SDK
load_dotenv()

FORWARDING   = os.environ.get('RC_FORWARDING_NUMBER')

rcsdk = SDK( os.environ.get('RC_CLIENT_ID'),
             os.environ.get('RC_CLIENT_SECRET'),
             os.environ.get('RC_SERVER_URL') )
platform = rcsdk.platform()
try:
  platform.login( jwt=os.environ.get('RC_JWT') )
except Exception as e:
  sys.exit("Unable to authenticate to platform: " + str(e))

params = {
    'phoneNumber': FORWARDING,
    'type': 'Other',
    'label': 'My ATT number'
}
try:
    resp = platform.post('/restapi/v1.0/account/~/extension/~/forwarding-number', params)
    print( f'Forwarding number created. ID: {resp.json().id}')
except Exception as e:
    sys.exit( f'Unknown exception: {e}' )
else:
    sys.exit( 0 )
<?php
/* You get the environment parameters from your 
   application dashbord in your developer account 
   https://developers.ringcentral.com */

require('vendor/autoload.php');
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/../');
$dotenv->load();

$rcsdk = new RingCentral\SDK\SDK( $_ENV['RC_CLIENT_ID'],
                                  $_ENV['RC_CLIENT_SECRET'],
                                  $_ENV['RC_SERVER_URL'] );
$platform = $rcsdk->platform();
$platform->login( [ "jwt" => $_ENV['RC_JWT'] ] );

$params = array (
    'phoneNumber' => '11235557890',
    'type' => 'Other',
    'label' => 'My ATT number'
);
$resp = $platform->post('/account/~/extension/~/forwarding-number', $params);

print_r ("Forwarding number created.");
print_r ($resp->json()->id);
?>
using System;
using System.Threading.Tasks;
using RingCentral;

namespace Create_ForwardingNumber
{
class Program
{
    static RestClient restClient;
    static void Main(string[] args)
    {
    restClient = new RestClient(
        Environment.GetEnvironmentVariable("RC_CLIENT_ID"),
        Environment.GetEnvironmentVariable("RC_CLIENT_SECRET"),
        Environment.GetEnvironmentVariable("RC_SERVER_URL"));
    restClient.Authorize(
        Environment.GetEnvironmentVariable("RC_JWT")).Wait();
        create_forwarding_number().Wait();
    }
    static private async Task create_forwarding_number()
    {
        var parameters = new CreateForwardingNumberRequest();
        parameters.phoneNumber = "11235557890";
        parameters.type = "Other";
        parameters.label = "My ATT number";

        var response = await restClient.Restapi().Account().Extension().ForwardingNumber().Post(parameters);

        Console.WriteLine("Forwarding number created.");
        Console.WriteLine(response.id);
    }
}
}
package com.ringcentral;

import com.ringcentral.*;
import com.ringcentral.definitions.*;
import java.io.IOException;

public class CreateForwardingNumber {
    static RestClient rc;

    public static void main(String[] args) {
        var obj = new CreateForwardingNumber();
    rc = new RestClient( System.getenv("RC_CLIENT_ID"),
                 System.getenv("RC_CLIENT_SECRET"),
                 System.getenv("RC_SERVER_URL") );
    try {
        rc.authorize( System.getenv("RC_JWT") );
        obj.create_forwarding_number();
    } catch (RestException | IOException e) {
        e.printStackTrace();
    }
    }

    public static void create_forwarding_number() throws RestException, IOException {
        var parameters         = new CreateForwardingNumberRequest();
        parameters.phoneNumber = "11235557890";
        parameters.type        = "Other";
        parameters.label       = "My ATT number";

        var response =  rc.restapi().account().extension().forwardingNumber().post(parameters);
        System.out.println("Forwarding number created. ID: " + response.id);
    }
}
#!usr/bin/ruby

# You get the environment parameters from your 
# application dashbord in your developer account 
# https://developers.ringcentral.com

require 'ringcentral'
require 'dotenv/load'

$rc = RingCentral.new(ENV['RC_CLIENT_ID'],
                      ENV['RC_CLIENRT_SECRET'],
                      ENV['RC_SERVER_URL'])

$rc.authorize(jwt: ENV['RC_JWT'])

params = {
    phoneNumber: '11235557890',
    type: 'Other',
    label: 'My ATT number'
}
resp = $rc.post('/restapi/v1.0/account/~/extension/~/forwarding-number',
                payload: params)

puts 'Forwarding number created.'
puts resp.body['id']

Read all Forwarding Numbers

To read all forwarding numbers:

  • Make a GET request to /restapi/v1.0/account/{accountId}/extension/{extensionId}/forwarding-number endpoint.

Required permission(s): ReadExtensions

Upon successful API call completion, the response contains a list of predefined forwarding numbers

{
  "uri":"https://platform.devtest.ringcentral.com/restapi/v1.0/account/178009004/extension/178009004/forwarding-number?page=1&perPage=100",
  "records":[
    {
      "uri":"https://platform.devtest.ringcentral.com/restapi/v1.0/account/178009004/extension/178009004/forwarding-number/592178004",
      "id":"592178004",
      "phoneNumber":"+14135554674",
      "label":"RingCentral for Desktop",
      "features":["CallFlip"],
      "flipNumber":"1",
      "type":"PhoneLine",
      "device":{
        "id":"801553370004"
        }
    },{
      "uri":"https://platform.devtest.ringcentral.com/restapi/v1.0/account/178009004/extension/178009004/forwarding-number/711909004",
      "id":"711909004",
      "phoneNumber":"+16505550930",
      "label":"Mobile",
      "features":["CallForwarding","CallFlip"],
      "flipNumber":"2",
      "type":"Mobile"
    },{
      "uri":"https://platform.devtest.ringcentral.com/restapi/v1.0/account/178009004/extension/178009004/forwarding-number/711910004",
      "id":"711910004",
      "phoneNumber":"+16505555476",
      "label":"Work",
      "features":["CallForwarding","CallFlip"],
      "flipNumber":"3",
      "type":"Work"
    }
  ],
  ...

Read a Forwarding Number

To read a forwarding number:

  • Make a GET request to /restapi/v1.0/account/{accountId}/extension/{extensionId}/forwarding-number/[forwardingNumberId] endpoint, where the forwardingNumberId is the id of an existing forwarding number object.

Hint

A valid forwardingNumberId can be retrieved using the previous API to read all forwarding numbers.

Required permission(s): ReadExtensions

Upon successful API call completion, the response contains a detailed information of a forwarding number

{
  "uri": "https://platform.devtest.ringcentral.com/restapi/v1.0/account/178003454/extension/178003454/forwarding-number/712613004",
  "id": "712613004",
  "phoneNumber": "+14085554388",
  "label": "RingCentral for Desktop",
  "features": [
    "CallFlip",
    "CallForwarding"
  ],
  "flipNumber": "6",
  "type": "PhoneLine",
  "device": {
    "id": "801553625004"
  }
}

Update a Forwarding Number

To update an existing forwarding number:

  • Specify the parameters which need to be updated.
  • Make a PUT request to /restapi/v1.0/account/{accountId}/extension/{extensionId}/forwarding-number/[forwardingNumberId] endpoint, where the forwardingNumberId is the id of an existing forwarding number object.

Hint

A valid forwardingNumberId can be retrieved using the previous API to read all forwarding numbers.

Required permission(s): EditExtensions