Programmable voice communication with RingCentral RingOut capability

Published in

RingCentral Developers

5 min readMar 29, 2018

Introduction

For voice communications to be seamless, it needs to occur fluidly and easily across any desired device or endpoint . Programming an endpoint can be straight forward when creating one’s own custom endpoint, such as using RingCentral’s Embeddable Voice or JavaScript WebRTC SDK, however, it can be more challenging when attempting to program a non-programmable endpoint such as a 3rd party phone or a hard phone. This is where RingCentral’s RingOut API comes in to initiate calls from any phone number, regardless of the endpoint device.

RingOut is an API call to RingCentral’s communications cloud that connects any two phone numbers by initiating calls to each participant and connects them together in the RingCentral cloud. This approach requires no programmability on either device, allowing the caller to select any of their phones, e.g. mobile phone, desk phone, etc.

The API call can use an explicit caller ID or one that is configured for the user’s account. This is a 2-legged call, where in the first leg the RingCentral service will make a connection to your current phone from where you want to place the call and in the second leg it will call the To/Destination number and connect the call between the two numbers. To the Destination/receiver of the call, it appears as if you are calling from your RingCentral business phone, even if you are on a separate device like your personal mobile phone.

Overview

The RingOut API can be called in 2 ways

a. With the phoneNumber in ‘from’ field

Request :

POST /restapi/v1.0/account/~/extension/~/ring-out HTTP/1.1

{
    "from": {"phoneNumber": "+1XXXXXXXXX "},
    "to": {"phoneNumber": "+1YYYYYYYYY "},
    "callerId": {"phoneNumber": "+1YYYYYYYYY "},
    "playPrompt": true,
    "country": { "id" : "44" }
}

playPrompt : When this is true it means , you as the caller will first hear a voice prompt that will ask you to press 1, and then it will call the destination number and connect caller(your phone) and the destination number.

When playPrompt is false, it will simultaneously connect the two calls , however, it will still always call your (caller’s) phone first so that the destination number (which can be your client, customer, prospect) does not have to wait even for a second.

Note : The “from”: {“phoneNumber”: “+1XXXXXXXXX “} shown above should be a phone number that is setup as a Forwarding number in your RingCentral account Service Web. As can be seen in the screen shot below taken from Ring Central Service Web.

You can also use the API End point https://{{RC_SERVER_HOSTNAME}}/restapi/v1.0/account/~/extension/:extensionId/forwarding-number to get a list of forwarding-numbers to validate which phone numbers you can use. The API response will be as below , you need to make sure the “features” section has “CallForwarding” as one of the values.

{
  "uri": "https://platform.devtest.ringcentral.com/restapi/v1.0/account/232352004/extension/232352004/forwarding-number/654242004",
  "id”: “654242004”,
  "phoneNumber": "+XXXXXXXXX",
  "label": "CustomABC",
  "features": [
    "CallForwarding",
    "CallFlip"
  ],
  "flipNumber": "6",
  "type”: "Mobile"
}

Sample Illustration of a RingOut Call — with phoneNumber in the from field.

RingOut — With phoneNumber in the from field.

As seen in the video, you can also check the various stages of the call using an API call to the endpoint:

https://{{RC_SERVER_HOSTNAME}}/restapi/v1.0/account/~/extension/~/ring-out/{{RingOutID}}

You can get the RingOutID from the Response of your previous call. It will look as below:

{
  "uri": "https://platform.devtest.ringcentral.com/restapi/v1.0/account/XXXXXXXX/extension/XXXXXXXX/ring-out/Y3MxNjk2MTIzOTg3MzYxOTE5NUAxMC4yOC4yMC4xMTA",
  "id": "Y3MxNjk2MTIzOTg3MzYxOTE5NUAxMC4yOC4yMC4xMTA",
  "status": {
    "callStatus": "Success",
    "callerStatus": "Success",
    "calleeStatus": "Success"
  }
}

b. With the forwardingNumberId in ‘from’ field

Request :

POST /restapi/v1.0/account/~/extension/~/ring-out HTTP/1.1

{
    "from": {"forwardingNumberId": "XXXXXXXXXX"},
    "to": {"phoneNumber": "+YYYYYYYY "},
    "playPrompt": true,
    "country": { "id" : "1" }
}

To get the forwardingNumberId , call the API Endpoint:

https://{{RC_SERVER_HOSTNAME}}/restapi/v1.0/account/~/extension/~/forwarding-number

You will see a response as below, the id field is your forwarding numberId and the features should contain “CallForwarding” to make the make the RingOut call possible.

{
 "uri": "https://platform.devtest.ringcentral.com/restapi/v1.0/account/~/extension/~/forwarding-number/12334556666",
  "id": "12334556666",
  "phoneNumber": "+14083388064",
  "label": "CustomABC",
  "features": [
    "CallForwarding",
    "CallFlip"
  ],
  "flipNumber": "6",
  "type": "Mobile"
}

Sample Illustration of a RingOut Call — with forwardingNumberId in the from field.

RingOut — withforwardingNumberId

More details about the various RingOut stages can be found : http://ringcentral-api-docs.readthedocs.io/en/latest/ring_out/

Use Cases

Imagine you are on a hotel room and you want to make that one important call to your prospect , however you also want to make sure the prospect sees the callerID of your business phone so that , it looks professional and creates a better impression. RingOut is your solution. With RingOut now you can make sure you can call your important prospect using your cell phone or hotel phone and at the same time make sure your prospect views the call coming from your business phone.
You are a SalesRep and you log into your CRM solution and use RingOut feature from your custom App to call your customer/prospect , you can take the call from your cell phone/home phone, however your customer/prospect will view your business /RingCentral caller Id.

3. You are traveling and out of country, you want to make one important call to your colleague , however do not want to get charged for the high outgoing voice call. You can use RingCentral RingOut feature to make the call and since the way RingOut works you will be only charged for incoming call, which is way less that an international outbound call charge.

Can RingOut dial international numbers?

Yes and RingOut can also save you money. Numbers are dialed for you and connect you to an international number without misdials.
Save on outrageous charges in hotels while you’re traveling abroad. Use RingOut to make calls call to your phone, which in-turn connect you to outside parties, so you are charged for an inbound rather than an outbound call.

Benefits and Advantages

Ability to make a call to any number without any purchased RingCentral DL
Ability to show your business phone number even when you are out of office/on the go or using your home/personal phone
Reduce costs for international phones by only incurring inbound charges
Ability to programmatically do RingOuts using the RingOut REST API

Sample App & SDK Using RingOut

RingCentral WebWidget: https://github.com/ringcentral/ringcentral-web-widget

Chrome Extension: https://chrome.google.com/webstore/detail/ringcentral-for-google/fddhonoimfhgiopglkiokmofecgdiedb?hl=en

RingCentral Mobile Apps — Android and iOS

If you have not yet joined the RingCentral Developer Community , please visit the below link and Signup : https://developer.ringcentral.com/free-tier-sign-up.html