RingOut Quick Start

Last updated: 2024-07-22Contributors
Edit this page

Calling the RingCentral API for the first time? We recommend you try out getting started experience.

In this quick start, we are going to help you connect two people in a live phone call using our RingOut API, which dials two phone numbers, and then connects the two people when they answer. Let's get started.

Create an app and obtain credentials

The first thing we need to do is create an app in the RingCentral Developer Console. This can be done quickly by clicking the "Create RingOut App" button below. Just click the button, enter a name and description if you choose, and click the "Create" button. If you do not yet have a RingCentral account, you will be prompted to create one.

Create RingOut App

  1. Login or create an account if you have not done so already.
  2. Go to Console/Apps and click 'Create App' button.
  3. Select "REST API App" under "What type of app are you creating?" Click "Next."
  4. Under "Auth" select "JWT auth flow."
  5. Under "Security" add the following permissions:
    • RingOut
  6. Under "Security" select "This app is private and will only be callable using credentials from the same RingCentral account."

When you are done, you will be taken to the app's dashboard. Make note of the Client ID and Client Secret. We will be using those momentarily.

Download and edit a .env file

Follow the instructions found in our guide to running Developer Guide code samples. Or:

  1. Download our env-template and save it as a file named .env.
  2. Edit your newly downloaded .env file, setting its variables with the proper values for the app you created above, paying close attention to the following:
    • RC_APP_CLIENT_ID - set to the Client ID of the app you created above
    • RC_APP_CLIENT_SECRET - set to the Client Secret of the app you created above
    • RC_USER_JWT - set to the JWT credential you created for yourself
    • RINGOUT_CALLER - set to a RingCentral phone number you wish to place the call from in this code sample
    • RINGOUT_RECIPIENT - set to a phone number you wish to call in this code sample

Place a Call

Select your preferred language below.

Install RingCentral JavaScript SDK

$ npm install @ringcentral/sdk --save

Create and edit ringout.js

Create a file called ringout.js. Be sure the values in your .env file have been set properly.

const RC_SDK = require('@ringcentral/sdk').SDK
const path = require('path')
// Remember to modify the path of your .env file location!
require('dotenv').config({ path: path.resolve(__dirname, '../.env') })

const CALLER       = process.env.RINGOUT_CALLER
const RECIPIENT    = process.env.RINGOUT_RECIPIENT

var rcsdk = new RC_SDK({
    '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, () => {
  call_ringout()
})

/*
* Place a ring-out call
*/
async function call_ringout() {
  try {
    var resp = await platform.post('/restapi/v1.0/account/~/extension/~/ring-out', {
      'from': { 'phoneNumber': CALLER },
      'to': { 'phoneNumber': RECIPIENT },
      'playPrompt': false
    })
    var jsonObj = await resp.json()
    console.log("Call placed. Call status: " + jsonObj.status.callStatus)
  } catch (e) {
    console.log("Unable to place a ring-out call.", e.message)
  }
}

Run your code

You are almost done. Now, load your variables into your local environment, and run your script.

$ source .env
$ node ringout.js

Install RingCentral Python SDK

$ pip install ringcentral python-dotenv

Create and edit ringout.py

Create a file called ringout.py. Be sure the values in your .env file have been set properly, including the RINGOUT_RECIPIENT variable.

from ringcentral import SDK
import os,sys,urllib.parse,json
from pathlib import Path
from dotenv import load_dotenv
load_dotenv()

CALLER    = os.environ.get('RINGOUT_CALLER')
RECIPIENT = os.environ.get('RINGOUT_RECIPIENT')

#
#  Place a ring-out call
#
def call_ring_out():
    try:
        bodyParams = {
            'from' : { 'phoneNumber': CALLER },
            'to'   : { 'phoneNumber': RECIPIENT },
            'playPrompt' : False
        }
        endpoint = "/restapi/v1.0/account/~/extension/~/ring-out"
        resp = platform.post(endpoint, bodyParams)
        jsonObj = resp.json()
        print(f'Call placed. Call status: {jsonObj.status.callStatus}')
    except Exception as e:
        print ("Unable to place a ring-out call. " + str(e))

# Instantiate the SDK and get the platform instance
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()

# Authenticate a user using a personal JWT token
def login():
    try:
      platform.login( jwt=os.environ.get('RC_USER_JWT') )
      #call_ring_out()
    except Exception as e:
      sys.exit("Unable to authenticate to platform. Check credentials." + str(e))

login()

Run your code

You are almost done. Now run your script.

$ python ringout.py

Install RingCentral PHP SDK

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

Create and edit ringout.php

Create a file called ringout.php. Be sure the values in your .env file have been set properly, including the RINGOUT_RECIPIENT variable.

<?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();

// Authenticate a user using a personal JWT token
try {
  $platform->login( [ "jwt" => $_ENV['RC_USER_JWT'] ] );
  //call_ring_out();
} catch (\RingCentral\SDK\Http\ApiException $e) {
  exit("Unable to authenticate to platform. Check credentials. " . $e->getMessage() . PHP_EOL);
}

/*
* Place a ring-out call
*/
function call_ring_out(){
  global $platform;
  $CALLER       = $_ENV['RINGOUT_CALLER'];
  $RECIPIENT    = $_ENV['RINGOUT_RECIPIENT'];

  try {
    $bodyParams = array(
      'from' => array('phoneNumber' => $CALLER ),
      'to' => array('phoneNumber' => $RECIPIENT),
      'playPrompt' => false
    );
    $endpoint = "/account/~/extension/~/ring-out";
    $resp = $platform->post($endpoint, $bodyParams);
    print_r ("Call placed. Call status: " . $resp->json()->status->callStatus);
  }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 place a ring-out call. ' . $e->apiResponse->response()->error() . PHP_EOL;
  }
}
?>

Run your code

You are almost done. Now run your script.

$ php ringout.php

Install RingCentral Ruby SDK

$ gem install ringcentral-sdk dotenv

Create and edit ringout.rb

Create a file called ringout.rb. Be sure the values in your .env file have been set properly, including the RINGOUT_RECIPIENT variable.

require 'ringcentral'
require 'dotenv'
require 'json'

# Remember to modify the path to where you saved your .env file!
Dotenv.load("./../.env")

CALLER    = ENV['RINGOUT_CALLER']
RECIPIENT = ENV['RINGOUT_RECIPIENT']

#
#  Place a ring-out call
#
def call_ring_out()
    bodyParams = {
        'from': { 'phoneNumber': CALLER },
        'to': { 'phoneNumber': RECIPIENT },
        'playPrompt': false
    }
    endpoint = "/restapi/v1.0/account/~/extension/~/ring-out"
    begin
      resp = $platform.post(endpoint, payload: bodyParams)
      body = resp.body
      puts "Call placed. Call status: " + resp.body['status']['callStatus']
    rescue StandardError => e
      puts ("Unable to place a ring-out call. " + e.to_s)
    end
end

# Instantiate the SDK and get the platform instance
$platform = RingCentral.new( ENV['RC_APP_CLIENT_ID'], ENV['RC_APP_CLIENT_SECRET'], ENV['RC_SERVER_URL'] )

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

login()

Run your code

You are almost done. Now run your script.

$ ruby ringout.rb

Create a Visual Studio project

  • Choose Console Application .Net Core -> App
  • Select Target Framework .NET Core 2.1
  • Enter project name "Call_Ringout"
  • Add NuGet package RingCentral.Net (4.1.0) SDK

Edit the file Program.cs

Be sure to edit the variables in ALL CAPS with your app and user credentials. Be sure to also set the recipient's phone number.

using System;
using System.Threading.Tasks;
using RingCentral;

namespace Call_Ringout
{
  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 call_ringout();
    }

    static private async Task call_ringout()
    {
      var parameters = new MakeRingOutRequest();
      parameters.from = new MakeRingOutCallerInfoRequestFrom {
        phoneNumber = Environment.GetEnvironmentVariable("RINGOUT_CALLER")
      };
      parameters.to = new MakeRingOutCallerInfoRequestTo {
        phoneNumber = Environment.GetEnvironmentVariable("RINGOUT_RECIPIENT")
      };
      parameters.playPrompt = false;

      var resp = await restClient.Restapi().Account().Extension().RingOut().Post(parameters);
      Console.WriteLine("Call Placed. Call status" + resp.status.callStatus);
    }
  }
}

Run Your App

You are almost done. Now run your app from Visual Studio.

Create a Java project (using Eclipse IDE)

  • Create a new Java project
  • Select the Gradle Project wizard
  • Enter project name "Call_RingOut"
  • Open the build.gradle file and add the RingCentral Java SDK to the project as shown below:
dependencies {
    // ...
    compile 'com.ringcentral:ringcentral:1.4.0'
}
  • Right-click the project in the Package Explorer and choose "Refresh Gradle Project" under the "Gradle" sub-menu

Create a new Java Class

Select "File -> New -> Class" to create a new Java class named "RingoutQuickStart"

package RingoutQuickStart;

public class RingoutQuickStart {

    public static void main(String[] args) {
        // TODO Auto-generated method stub

    }
}

Edit the file "RingoutQuickStart.java".

Be sure to edit the variables in ALL CAPS with your app and user credentials. Be sure to also set the recipient's phone number.

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

public class RingoutQuickStart {
    static String RINGOUT_CALLER    = System.getenv("RINGOUT_CALLER");
    static String RINGOUT_RECIPIENT = System.getenv("RINGOUT_RECIPIENT");
    static RestClient rc;

    public static void main(String[] args) {
        var obj = new RingoutQuickStart();
        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.call_ringout();
        } catch (RestException | IOException e) {
            e.printStackTrace();
        }
    }
    public void call_ringout() throws RestException, IOException {
        MakeRingOutRequest requestBody = new MakeRingOutRequest();
        requestBody.from(new MakeRingOutCallerInfoRequestFrom().phoneNumber(
              RINGOUT_CALLER ));
        requestBody.to(new MakeRingOutCallerInfoRequestTo().phoneNumber(
          RINGOUT_RECIPIENT));
        requestBody.playPrompt = false;

        var response = rc.restapi().account().extension().ringOut().post(requestBody);
        System.out.println("Call Placed. Call status: " + response.status.callStatus);
    }
}

Run Your App

You are almost done. Now run your app from Eclipse.

Need Help?

Having difficulty? Feeling frustrated? Receiving an error you don't understand? Our community is here to help and may already have found an answer. Search our community forums, and if you don't find an answer please ask!

Search the forums »

What's Next?

When you have successfully made your first API call, it is time to take your next step towards building a more robust RingCentral application.

Take your next step »