11/16/17 04:54 AM  

Using the RingCentral RingOut API

Printable View
« Go Back

Article

 
SummaryHow do I use the RingOut API?
Details

The RingOut API (Application Programming Interface) allows RingCentral customers to invoke the RingOut functionality from a third party application, such as a custom-built database.


How Does It Work

The User selects a certain number from the forwarding number list, starts RingOut, then enters the required called number. RingCentral calls the specified forwarding number, then connects the User with the called number. See RingCentral RingOut for more information. 
 

RingOut API commands

Click on the links below to learn more.

   RingOut API commands using HTTP GET or HTTP POST
   RingOut API commands using POST, GET, DELETE methods 
   Other RingOut Options

 

RingOut API commands using HTTP GET or HTTP POST

There are 4 commands accessible via a standard HTTP GET or POST call.

These commands are invoked using secure ASP script located at https://service.ringcentral.com/ringout.asp.

IMPORTANT: Clients are required to store HTTP cookies returned by the API server and send them in all subsequent requests during the session.
 


   List 
 
   Get a list of all the numbers you can use to place the call (the phone numbers in the specified users account).
 

   Call
 
   Place call.
 

   Status 
 
   Get current call status. 
 

   Cancel
 
   Cancel call.
 


The examples below show how to call API commands using the HTTP GET method with parameters passed in the URL query string. The commands can also be called using the HTTP POST method with exactly the same parameters passed in the request body.
 

List command

This command returns a semicolon-separated list of phone numbers from which you can make outbound calls. One of these numbers should be used for the "From" parameter in the "Call" command.
 


PARAMETER
 
DESCRIPTION
 

   Cmd
 
   Command identification: "list"
 

   Username
 
   RingCentral Main Phone Number in full format that includes the country code
 

   Ext
 
   Extension number
 

   Password
 
   Account's password
 


Responses 

   
   Success:
OK <list of phone numbers and labels separated by a semicolon>
   Error: all other responses which do not include OK.

 

Sample command and response 


   Command: 
https://service.ringcentral.com/ringout.asp?cmd=list&username=18889363711&ext=101&password=1234
   Response: OK 6505553711;Home;6505551550;Business;6505551233;Mobile

 

 

Call command

This command places a call and returns a Session ID call and WS if successful. 
 


PARAMETER
 
DESCRIPTION
 

   Cmd
 
   Command identification: "call"
 

   Username
 
    RingCentral Main Phone Number in full format that includes the country code
 

   Ext
 
   Extension number
 

   Password
 
   Account's password
 

   To
 
   Destination number
 

   From
 
   Call back number
 

   CLID
 
   Caller ID number
 

   Prompt
 
   "1" to prompt user to press "1" to connect
 


Responses 


   Success:
OK <Session ID> <WS>
   Error: all other responses which do not include OK.

 

Sample command and response 


   Command: 
https://service.ringcentral.com/ringout.asp?cmd=call&username=18889363711&ext=101&password=1234&
to=6505551230&from=6505551231&clid=8889363711&prompt=1
   Response: OK 18 3


[Back to RingOut API commands using HTTP GET or HTTP POST]
[Go to RingOut API commands using POST, GET, DELETE methods]

 

Status command

This command returns current status of a call. 
 


PARAMETER
 
DESCRIPTION
 

   Cmd
 
   Command identification: "status"
 

   SessionID
 
   <Session ID> received from server
 


Responses 


   Completed calls:
OK <Session ID> <space>
   In other cases: OK <Session ID> followed by 5 groups separated by ';':


1. General call status number: 

• 0 - Success
• 1 - In Progress
• 2 - Busy
• 3 - No Answer
• 4 - Rejected
• 5 - Generic Error
• 6 - Finished
• 7 - International calls disabled
• 8 - Destination number prohibited

2. Destination number (the same as #1)
3. Destination status
4. Call back number
5. Call back status (the same as #1)
 

Sample command and response 


   Command: 
https://service.ringcentral.com/ringout.asp?cmd=status&sessionid=18
   Response: OK 18 4;6505551230;5;6505551231;5

 

 

Cancel command

This command cancels a call.
 

PARAMETER
 
DESCRIPTION
 

   Cmd
 
   Command identification: "cancel"
 

   SessionID
 
   <Session ID> received from server
 

 

Sample command and response 


   Command: 
https://service.ringcentral.com/ringout.asp?cmd=cancel&sessionid=18
   Response: OK 18 

 

 

RingOut API commands using POST, GET, DELETE methods

The API treats a two-legged RingOut call as a resource that can be created, retrieved, or deleted via the POST, GET and DELETE methods correspondingly.

   Making a Call
   Polling Call Status
   Call Control
   Caller ID 

 

Making a Call

A RingOut call can be created using the following request:
 


   POST /restapi/v1.0/account/~/extension/~/ringout
   Content-Type: application/json
   Authorization: Bearer <access-token> 

   {
"from": {"phoneNumber": "13443334444  "}, /* from parameter is optional if there is a default number in user's forwarding numbers */ 
"to": {"phoneNumber": "13453443434  "}, /* to parameter is required */ 
"playPrompt": true /* optional field */
   }
 


Where: 

 
   from
 


Refers to the number of the calling party. This is a required field only if there is no default number in the User's forwarding number list. The phoneNumber attribute should comply with the E.164 standard.

As a result of validation of the phoneNumber attribute, the server may return the error code:
400 Bad Request - phoneNumber specified in the field is empty or invalid.
 


   to
 


Refers to the called party number. This field is required. If this field is missing from the request, the 400 Bad Request error is returned. The phoneNumber attribute should comply with the E.164 standard.

As a result of validation of the phoneNumber attribute the server may return the error code:
400 Bad Request - phoneNumber specified in the field is empty or invalid.
 


   playPrompt
 


Pertains to the audio prompt that the calling party hears when the call is connected. This field is optional. It corresponds to the setting in the RingCentral application "Prompt me to dial 1 before connecting" (When selected, the system will ask you to press "1" on your phone's keypad before connecting to the destination number).
 


Response

The response can be as follows:
 


   200 OK
   Content-Type: application/ json  

   {
    "id": 234343434, 
    "uri": "/restapi/v1.0/account/~/extension/~/ringout/234343434", 
    "status": {  
        "callStatus": "Success",  
        "callerStatus": "Success",  
        "calleeStatus": "Success"   
    }
   }
 


Where:


callStatus can take the following values:
 


VALUE
 


DESCRIPTION
 


   InProgress
 


   Connection is being established
 


   Success
 


   Both legs connected (Answered)
 


   CannotReach
 


   Failure state (one or both legs are in invalid state for call connection)
 


   NoAnsweringMachine
 


   Internal server failure
 


The Call status is generated as a combination of both call legs statuses (caller and callee):

The Call status is generated as a combination of both call legs statuses (caller and callee):

 

callerStatus, calleeStatus can take the following values:
 


VALUE
 


DESCRIPTION
 


   InProgress
 


Connection to the target leg is being established
 


   Busy
 


Target device is busy
 


   NoAnswer
 


The call has been dropped because of timeout
 


   Rejected
 


RingOut command was canceled by user or RingOut initiated, 1st leg answered, 2nd is ringing, user drops call on the 1st leg - 2nd leg gets 'Rejected'
 


   Success
 


Call party has answered the call
 


   Finished
 


The call was terminated (In Progress > Success > Finished)
 


   GenericError
 


Error code received from PSTN or Internal server error
 


   InternationalDisabled
 


International calling disabled (Call to International number) or
Domestic calling disabled (Call with local Country code) or
Internal calling disabled (Call within one account)
 


   NoSessionFound
 


RingOut status was requested for RingOut session which does not exist (e.g was already Closed)
 


   Invalid
 


RingOut session state is unknown due to internal failure
 


The Caller or Callee statuses are separately generated for the target call party:

The Caller or Callee statuses are separately generated for the target call party:

 

RingOut Flow

The statuses are changing statuses are changing during a successful call.

The statuses are changing during a successful call. 

A failed call can be illustrated as follows.

A failed call can be illustrated as follows.

[Back to RingOut API commands using POST, GET, DELETE methods]
[Go to RingOut API commands using HTTP GET or HTTP POST]
 

Polling Call Status

Use polling to get the status of an ongoing outbound call.
 

   GET/restapi/v1.0/account/~/extension/~/ringout/234343434


Response

The response is as follows:
 


   200 OK
   Content-Type: application/ json

   {  
    "id": 234343434, 
    "uri": "/restapi/v1.0/account/~/extension/~/ringout/234343434", 
    "status": {  
        "callStatus": "Success",  
        "callerStatus": "Success",  
        "calleeStatus": "Success"   
    }
   }
 


[Back to RingOut API commands using POST, GET, DELETE methods]
[Go to RingOut API commands using HTTP GET or HTTP POST]

 

Call Control

Currently, the RingCentral Connect Platform does not support the control of outbound calls. However, you can cancel a RingOut call while the callee party status is InProgress. You will need to make a DELETE request to ringout URI.
 


   DELETE /restapi/v1.0/account/~/extension/~/ringout/234343434  

   204 No Content
 


[Back to RingOut API commands using POST, GET, DELETE methods]
[Go to RingOut API commands using HTTP GET or HTTP POST]


Caller ID 

RingCentral allows Users to select a number to use for their Caller ID Name (CNAM) value when making calls. You need to set the "RingOut from Web" value as available in the RingCentral Online account. in order to set the CallerId for the RingOut API.

See Outbound Caller ID Name Overview and Frequently Asked Questions for more information.
 

Other RingOut Options

The RingOut feature is available on the RingCentral Online account, RingCentral Desktop app, and RingCentral Mobile app. For more information, click on the links below:

   Using the RingOut from your RingCentral Online Account 
   Using RingOut on the RingCentral Desktop App 
   Enabling RingOut on your RingCentral Mobile app 
 

See Also

Tools for Developers 
RingCentral RingOut 
 
Ranking
Was this information helpful?
Yes
No
Somewhat

Tell us why and what can we do to improve this information