You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<asideclass="notice">This error section is stored in a separate file in `includes/_errors.md`. Slate allows you to optionally separate out your docs into many files...just save them to the `includes` folder and add them to the top of your `index.md`'s frontmatter. Files are included in the order listed.</aside>
4
-
5
-
The Kittn API uses the following error codes:
3
+
The RingCentral for Developers API uses the following error codes:
6
4
7
5
8
6
Error Code | Meaning
9
7
---------- | -------
10
-
400 | Bad Request -- Your request sucks
8
+
400 | Bad Request -- Your request is incorrectly formatted
11
9
401 | Unauthorized -- Your API key is wrong
12
-
403 | Forbidden -- The kitten requested is hidden for administrators only
13
-
404 | Not Found -- The specified kitten could not be found
14
-
405 | Method Not Allowed -- You tried to access a kitten with an invalid method
15
-
406 | Not Acceptable -- You requested a format that isn't json
16
-
410 | Gone -- The kitten requested has been removed from our servers
17
-
418 | I'm a teapot
18
-
429 | Too Many Requests -- You're requesting too many kittens! Slow down!
10
+
403 | Forbidden -- The resource requested is hidden for administrators only
11
+
404 | Not Found -- The specified resource could not be found
12
+
405 | Method Not Allowed -- You tried to access a resource with an invalid method
13
+
410 | Gone -- The resource requested has been removed from our servers
14
+
429 | Too Many Requests -- You're making too many requests! Slown down!
19
15
500 | Internal Server Error -- We had a problem with our server. Try again later.
20
-
503 | Service Unavailable -- We're temporarially offline for maintanance. Please try again later.
16
+
503 | Service Unavailable -- We're temporarially offline for maintanance. Please try again later.
Pager messages are RingCentral specific types of text messages which can be sent between extensions of one account. Unlike SMS, pager messages can be sent to multiple recipients, so the API allows several extension numbers in the **to** field. Another difference from SMS is that the pager message that is sent to the department extension is automatically forwarded to all department members. This allows setting up dedicated mailing lists within the organization. The endpoint **company-pager** is designed to handle pager messages.
293
+
248
294
# Getting Started
249
295
250
296
## Installing the SDK
@@ -282,7 +328,43 @@ var platform = rcsdk.getPlatform();
282
328
283
329
Now that you have your platform singleton and SDK has been configured with the correct server URL and API key, your application can log in so that it can access the features of the API.
284
330
285
-
## Login
331
+
## Login via 3-legged OAuth
332
+
333
+
~~~javascript
334
+
// Get user authorization URL
335
+
var myRedirectUri ='https://example.com/oauth';
336
+
var authorizeUrl =t.rcDemo.Core.rcSdk.getPlatform().getAuthURL({
337
+
redirectUri: myRedirectUri
338
+
});
339
+
// Open window for authorizeUrl
340
+
341
+
// In redirect URL, retrieve `code` from query string and exhange for access token.
342
+
// Get query string
343
+
var myRedirectUri ='https://example.com/oauth';
344
+
var qs =rcsdk.getPlatform().parseAuthRedirectUrl(window.location.href);
345
+
qs.redirectUri= myRedirectUri;
346
+
347
+
if ('code'in qs) {
348
+
var res =rcsdk.getPlatform().authorize(qs)
349
+
.then(function(response) {
350
+
// process response and close window (if popup)
351
+
window.open('', '_self', '');
352
+
window.close();
353
+
}).catch(function(e) {
354
+
console.log("Error: Authorization")
355
+
});
356
+
} else {
357
+
console.log("Error: No Code")
358
+
}
359
+
~~~
360
+
361
+
3-legged OAuth is the standard login approach for user applications via the web where the user will be presented with a standard RingCentral login. This approach also supports RingCentral customers that have deployed single sign-on (SSO) via 3-rd party identity providers (IdPs). To implement 3-legged OAuth, implement the following steps:
362
+
363
+
1. Configure a redirect URI for your service in the RingCentral Developer portal which will be used to send the authorization code upon success login and authorization.
364
+
2. Then use the redirect URI with the SDK to retrieve an OAuth authorization URL that can be used to open a browser window.
365
+
3. Finally, in the web page at your redirect URI, extract the authoriation code from the URL string's `code` query parameter and exchange the authorization code for an access token.
366
+
367
+
## Login via 2-legged OAuth
286
368
287
369
~~~javascript
288
370
platform.authorize({
@@ -294,13 +376,15 @@ platform.authorize({
294
376
}).catch(function(e) {
295
377
alert(e.message||'Server cannot authorize user');
296
378
});
297
-
~~~
379
+
~~~
380
+
381
+
Client-server applications can use the 2-legged OAuth approach which doesn't provide a user login page.
298
382
299
383
To log in to RingCentral, get the Platform object and call its authorize method, providing valid username, extension, and password values. Enter your phone number in E.164 format for username. The `+` may be omitted.
300
384
301
385
A Promise is returned, and you can use its then method to specify your continuation function, and its catch method to specify an error handling function.
@@ -314,7 +398,7 @@ To handle possible access or authentication exceptions that may occur while the
314
398
A recommended way to handle access or authentication exceptions is to direct the user to the login page or UI. The login page may attempt to automatically re-authenticate the user using stored authentication data (see below).
315
399
</aside>
316
400
317
-
## Determining Authn Status
401
+
## Determining Authorization Status
318
402
319
403
~~~javascript
320
404
// To check authentication status:
@@ -351,6 +435,111 @@ platform.logout().then(...)
351
435
352
436
Your application can log out the user by calling the `platform.logout()` method.
353
437
438
+
# Making Calls (RingOut)
439
+
440
+
Outbound calls using RingCentral can be made using the RingOut functionality.
441
+
442
+
## Two-Legged Calls
443
+
444
+
When making a call, the RingCentral system establishes two calls, one for each of the two parties being connected, and then connects them. This results in events for two calls (2-legged calls) when initiated a single click-to-call?
// also save ajax.data as, for example, prevRingoutData
478
+
console.log(ajax.data); // updated status of ringout
479
+
timeout =next(delay); // you can increase delay here
480
+
})
481
+
.catch(handleError);
482
+
483
+
}
484
+
485
+
var timeout =rcsdk.getUtils().poll(update, 3000); // stay in RPS limits
486
+
487
+
// To stop polling:
488
+
489
+
rcsdk.getUtils().stopPolling(timeout);
490
+
~~~
491
+
492
+
Use polling to get the status of an ongoing outbound call.
493
+
494
+
## Outbound Call Control
495
+
496
+
The RingCentral Connect Platform does not currently support control of outbound calls. However, you can cancel ringout call while callee party status is `InProgress`. To do that make a `DELETE` request to ringout URI.
497
+
498
+
## Outbound Call Statuses
499
+
500
+
* A 2-legged RingOut call is represented in events as an outbound call between `from` and `to` numbers provided in RingOut API request.
501
+
* There is the known issue: notification with `CallConnected` status comes after first leg is connected. So actually a call can be missed by callee but it won't be reflected in event flow; but it will be reflected in call log.
502
+
* Phone numbers in notification (`from` and `to`) may be either E.164 phone numbers (with or without `+`) or short extension numbers (e.g. '101') for calls between extensions
503
+
* For some RC phone system configurations when multiple devices are ringing for inbound call, you may get transitional notifications with `NoCall` status which will be immediately followed by `Ringing` or `CallConnected` (for the same `sessionId`).
504
+
505
+
## Polling & Events Notification
506
+
507
+
All RingOut calls will appear in event notifications and active calls endpoint. The difference between what RingOut polling provides is more granular status updates (application can track status of both parties). Normally it should be represented by two independent views/flows in application. In general there is no point to match ringout calls with any of active calls, those process may happen concurrently.
508
+
509
+
If the application needs to track outbound calls and save them somewhere, it is better to initiate the ringout and NOT poll it, but expect a notification and work only with notifications/active calls.
510
+
511
+
# Making Calls (URI Scheme)
512
+
513
+
In addition to making calls via the RingOut API, if the user has the RingCentral for Desktop softphone installed, it is possible to use a URI scheme to initiate a dial out from the application.
514
+
515
+
RingCentral supports both a custom `rcmobile` URI scheme will resolve the issue of competing applications using the same URI scheme and a standard `tel` URI scheme which is more common but subject to competing uses.
// For more info, see http://stackoverflow.com/questions/2330545/
529
+
~~~
530
+
531
+
The RingCentral `rcmobile` URI Scheme is specific to RingCentral and thus has a higher probability of workign as intended.
532
+
533
+
## Standard URI Scheme
534
+
535
+
~~~
536
+
// HTML URI Scheme
537
+
<a href="tel:1-650-111-2222">1-650-111-2222</a>
538
+
<a href="tel:16501112222">1-650-111-2222</a>
539
+
~~~
540
+
541
+
The standard `tel` URI Scheme is also supported but since multiple applications use this URI scheme, there may be competing applications resulting in a less desirable expeirence.
542
+
354
543
# Call Management
355
544
356
545
If you are integrating with a CRM or ERP system, use of the JavaScript SDK is highly recommended. Following is an example of a call management integration that includes monitoring of incoming calls and performing of RingOuts.
By default, the load request returns calls that were made during the last week. To alter the time frame, provide custom query.dateTo and query.dateFrom properties.
646
835
647
-
# Making Calls (RingOut)
648
-
649
-
Outbound calls using RingCentral can be made using the RingOut functionality.
650
-
651
-
## Two-Legged Calls
652
-
653
-
When making a call, the RingCentral system establishes two calls, one for each of the two parties being connected, and then connects them. This results in events for two calls (2-legged calls) when initiated a single click-to-call?
// also save ajax.data as, for example, prevRingoutData
669
-
})
670
-
.catch(handleError);
671
-
~~~
672
-
673
-
The application should stop polling the RingOut when its status changes to error or success because after that there will be no status updates.
836
+
# Call Recordings
674
837
675
-
## Polling Outbound Call Status
838
+
Call log records with recordings will have a `recording` object property which includes information on the recording including the `contentUri` string property which can be used to retrieve the recording.
676
839
677
840
~~~javascript
678
-
// Poll for the status of an ongoing outbound call
679
-
functionupdate(next, delay) {
680
-
681
-
if (!rcsdk.getRingoutHelper().isInProgress(ringout)) return;
var timeout =rcsdk.getUtils().poll(update, 3000); // stay in RPS limits
851
+
var recordingUrl = callLogRecord['recording']['contentUri'];
852
+
var recordingUrlWithToken =rcsdk.getPlatform().apiUrl(uri, {addToken:true});
853
+
~~~
695
854
696
-
// To stop polling:
697
855
698
-
rcsdk.getUtils().stopPolling(timeout);
699
-
~~~
700
-
701
-
Use polling to get the status of an ongoing outbound call.
702
-
703
-
## Outbound Call Control
704
-
705
-
The RingCentral Connect Platform does not currently support control of outbound calls. However, you can cancel ringout call while callee party status is `InProgress`. To do that make a `DELETE` request to ringout URI.
706
-
707
-
## Outbound Call Statuses
708
-
709
-
* A 2-legged RingOut call is represented in events as an outbound call between `from` and `to` numbers provided in RingOut API request.
710
-
* There is the known issue: notification with `CallConnected` status comes after first leg is connected. So actually a call can be missed by callee but it won't be reflected in event flow; but it will be reflected in call log.
711
-
* Phone numbers in notification (`from` and `to`) may be either E.164 phone numbers (with or without `+`) or short extension numbers (e.g. '101') for calls between extensions
712
-
* For some RC phone system configurations when multiple devices are ringing for inbound call, you may get transitional notifications with `NoCall` status which will be immediately followed by `Ringing` or `CallConnected` (for the same `sessionId`).
713
-
714
-
## Polling & Events Notification
715
-
716
-
All RingOut calls will appear in event notifications and active calls endpoint. The difference between what RingOut polling provides is more granular status updates (application can track status of both parties). Normally it should be represented by two independent views/flows in application. In general there is no point to match ringout calls with any of active calls, those process may happen concurrently.
717
-
718
-
If the application needs to track outbound calls and save them somewhere, it is better to initiate the ringout and NOT poll it, but expect a notification and work only with notifications/active calls.
0 commit comments