Call Forwarding and Call Flipping
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 thetype
is omitted or specified as "Other". - Specify the
id
for thedevice
object if thetype
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_APP_CLIENT_ID,
'clientSecret': process.env.RC_APP_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({ 'jwt': process.env.RC_USER_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_APP_CLIENT_ID'),
os.environ.get('RC_APP_CLIENT_SECRET'),
os.environ.get('RC_SERVER_URL') )
platform = rcsdk.platform()
try:
platform.login( jwt=os.environ.get('RC_USER_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
// Remember to modify the path ./../ pointing to the location where the RingCentral SDK was installed and the .env file was saved!
require('./../vendor/autoload.php');
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . './../');
$dotenv->load();
$rcsdk = new RingCentral\SDK\SDK( $_ENV['RC_APP_CLIENT_ID'],
$_ENV['RC_APP_CLIENT_SECRET'],
$_ENV['RC_SERVER_URL'] );
$platform = $rcsdk->platform();
$platform->login( [ "jwt" => $_ENV['RC_USER_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 async Task Main(string[] args)
{
restClient = new RestClient(
Environment.GetEnvironmentVariable("RC_APP_CLIENT_ID"),
Environment.GetEnvironmentVariable("RC_APP_CLIENT_SECRET"),
Environment.GetEnvironmentVariable("RC_SERVER_URL"));
await restClient.Authorize(Environment.GetEnvironmentVariable("RC_USER_JWT"));
await create_forwarding_number();
}
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_APP_CLIENT_ID"),
System.getenv("RC_APP_CLIENT_SECRET"),
System.getenv("RC_SERVER_URL") );
try {
rc.authorize( System.getenv("RC_USER_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_APP_CLIENT_ID'],
ENV['RC_APP_CLIENT_SECRET'],
ENV['RC_SERVER_URL'])
$rc.authorize(jwt: ENV['RC_USER_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.ringcentral.com/restapi/v1.0/account/178009004/extension/178009004/forwarding-number?page=1&perPage=100",
"records":[
{
"uri":"https://platform.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.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.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 theforwardingNumberId
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.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 theforwardingNumberId
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