Getting started with the Cloud Phone SDK
The primary task in getting started using the Cloud Phone SDK is to obtaining the necessary credentials and information for the Cloud Phone SDK to connect to your device.
Install the SDK
The SDK is available from npmjs and can be installed by the standard mechanisms.
yarn install ringcentral-softphone
Obtaining credentials
There are two ways to find the credentials needed to connect to a device using the Soft Phone SDK. You can navigate the RingCentral application and obtain credentials through our user interface, or you can fetch them programmatically via the API.
Using the Admin Portal to obtain credentials
-
Login to the RingCentral Admin Portal
-
Then, navigate to the user or extension that you will be binding the Cloud Phone SDK to.
-
Expand the section called "Devices & Numbers"
-
In the list of phones found under "Devices & Numbers," select the device you want to use.
!!! warning "The phone type must be 'Existing Phone'" If the user does not
have a phone of this type, you may need to create one. The Cloud Phone SDK
will not work with "RingCentral Desktop app" phone types.
-
Click the "Set Up and Provision" button
-
Click the link "Set up manually using SIP"
On the resulting page you will find the following fields:
- SIP Domain
- Outbound Proxy
- User Name
- Password
- Authorization ID
!!! info "The SIP Domain's port number is not necessary to connect" On the credentials page you will observe that the "SIP Domain" field shows a port number. You can safely ignore this port number when connecting to a device.
Obtaining Cloud Phone credentials via the API
Alternatively, you can obtain the connection and credential information you need via a RingCentral REST API.
Please note: this technique requires familiarity with the RingCentral REST API. If you have never used this API, please consult our getting started guide.
Find appropriate device
You will first need to obtain a list of devices for an extension using the list extension devices endpoint. In the response you will find the devices type:
{
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/1508191004/extension/1508193004/device?page=1&perPage=1",
"records" : [ {
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/1508191004/device/228113004",
"id" : "228113004",
"type" : "HardPhone",
"sku" : "HP-37",
"model" : {
"id" : "37",
"name" : "Polycom IP 6000 Conference Phone",
"lineCount" : 2,
"addons" : [ ],
"features" : [ ]
},
"name" : "Polycom IP 6000 Conference Phone",
"status" : "Offline",
// truncated for brevity
}]
}
!!! warning "Only 'Other Phone' types are supported by Cloud Phone SDK" As
stated previously, not every device can be used with the Cloud Phone SDK. Only
devices with a type of Other Phone
are supported. Any other type will not work
with the SDK.
!!! info "'Other Phone' type is equivalent to 'Existing Phone' as seen in Admin Portal"
If you cannot find an appropriate device via the API, then you will need to create a device manually. Please refer to previous section.
Read device info
Using the id
of the selected device, call the
read device SIP info
REST API. A response from this API has the following information you will need:
userName
password
authorizationId
proxy
{
"domain": "sip.ringcentral.com",
"userName": "16501234567",
"password": "password",
"authorizationId": "802512345678",
"outboundProxies": [
{
"region": "NA",
"proxy": "sip20.ringcentral.com:5090",
"proxyTLS": "sip20.ringcentral.com:5096"
},
{
"region": "EMEA",
"proxy": "sip40.ringcentral.com:5090",
"proxyTLS": "sip40.ringcentral.com:5096"
},
{
"region": "APAC",
"proxy": "sip71.ringcentral.com:5090",
"proxyTLS": "sip71.ringcentral.com:5096"
},
{
"region": "LATAM",
"proxy": "sip80.ringcentral.com:5090",
"proxyTLS": "sip80.ringcentral.com:5096"
}
...
]
}
View demo source code{ .md-button }
You will need to choose a outboundProxy value based on your location. And please
choose the proxyTLS
value because this SDK uses TLS. For example if you live
in north America, choose sip10.ringcentral.com:5096
.
Initializing the SDK
Once you have obtained your device's credentials, you can connect to the device and begin receiving events.
import Softphone from "ringcentral-softphone";
const softphone = new Softphone({
domain: process.env.SIP_DOMAIN,
outboundProxy: process.env.SIP_OUTBOUND_PROXY,
username: process.env.SIP_USERNAME,
password: process.env.SIP_PASSWORD,
authorizationId: process.env.SIP_AUTHORIZATION_ID,
});
softphone.enableDebugMode(); // Optionally enable debug mode to print all SIP messages
await softphone.register();
// at this point the phone is ready
Creating multiple instances with the same credentials
One can run multiple instances of a cloud phone using the same credentials without causing an error. However, only the most recently created instance will receive inbound calls.