diff --git a/source/images/logo.png b/source/images/logo.png index 24e509952c5..ded09da3224 100644 Binary files a/source/images/logo.png and b/source/images/logo.png differ diff --git a/source/images/ringout.png b/source/images/ringout.png new file mode 100644 index 00000000000..5c7a8273d6b Binary files /dev/null and b/source/images/ringout.png differ diff --git a/source/index.md b/source/index.md index 401ece5fcd9..0cd13221c50 100644 --- a/source/index.md +++ b/source/index.md @@ -2,12 +2,11 @@ title: API Reference language_tabs: - - shell - - ruby - - python + - http + - javascript toc_footers: - - Sign Up for a Developer Key + - Sign Up for RingCentral for Developers - Documentation Powered by Slate includes: @@ -18,151 +17,961 @@ search: true # Introduction -Welcome to the Kittn API! You can use our API to access Kittn API endpoints, which can get information on various cats, kittens, and breeds in our database. +Welcome to the RingCentral CTI Developer Tutorial. This tutorial uses the [RingCentral JavaScript SDK](http://github.com/ringcentral/js-sdk). -We have language bindings in Shell, Ruby, and Python! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right. +Call management integration typically includes monitoring of incoming calls, listing calls and performing of RingOuts, all of which are covered in this tutorial. -This example API documentation page was created with [Slate](http://github.com/tripit/slate). Feel free to edit it and use it as a base for your own API's documentation. +# Quickstart -# Authentication +## Retrieve Call Logs -> To authorize, use this code: +```http +GET https://platform.ringcentral.com/restapi/v1.0/account/~/extension/~/call-log HTTP/1.1 +Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUFWZmY4ZXoxMlh +Accept: application/json +``` + +``` +HTTP/1.1 200 OK +Content-Language: en +Content-Type: application/json; charset=UTF-8 +Content-Length: 4145 + +{ + "uri": ".../account/401501489004/extension/401501489004/call-log?dateFrom=2013-01-01T00:00:00.000Z&page=1&perPage=100", + "records": [ + { + "uri": ".../account/401501489004/extension/401501489004/call-log/IXtVRs-3B7A_PfE", + "id": "IXtVRs-3B7A_PfE", + "sessionId": "404769762004", + "startTime": "2014-09-22T12:58:09.000Z", + "duration": 4, + "type": "Voice", + "direction": "Inbound", + "action": "Phone Call", + "result": "Accepted", + "to": { + "phoneNumber": "18662130006", + "name": "Rose White" + }, + "from": { + "phoneNumber": "16504445567", + "name": "Phillip Marco", + "location": "Palo Alto, CA" + } + }, + { + "uri": ".../account/401501489004/extension/401501489004/call-log/IXtVPRjQvSF5Pe4", + "id": "IXtVPRjQvSF5Pe4", + "sessionId": "404769755004", + "startTime": "2014-09-22T12:58:06.000Z", + "duration": 10, + "type": "Voice", + "direction": "Outbound", + "action": "VoIP Call", + "result": "Call connected", + "to": { + "phoneNumber": "16504445567", + "location": "Palo Alto, CA" + }, + "from": { + "phoneNumber": "16504445567", + "name": "Irene Fox" + } + }, + { + ... + } + ], + "paging": { + "page": 1, + "perPage": 100, + "pageStart": 0, + "pageEnd": 6 + }, + "navigation": { + "firstPage": { + "uri": ".../account/401501489004/extension/401501489004/call-log?dateFrom=2013-01-01T00:00:00.000Z&page=1&perPage=100" + } + } +} +``` + +To access a Call Log resource you will require this URI: + +`GET /restapi/v1.0/account/{accountId}/extension/{extensionId}/call-log` + +Send the request having specified particular accountId and extensionId or using simplified syntax with tilde characters. Please note, that if dateFrom parameter is not specified, server will return records for last week only. + +## Retrieve Filtered Call Logs + +```http +GET https://platform.ringcentral.com/restapi/v1.0/account/~/extension/~/call-log?dateFrom=2014-09-18&phoneNumber=16504445567&dateTo=2014-09-25&type=Voice HTTP/1.1 +Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUFWZmY4ZXoxMl +Accept: application/json +``` -```ruby -require 'kittn' +``` +HTTP/1.1 200 OK +Content-Language: en +Content-Type: application/json; charset=UTF-8 +Content-Length: 1725 -api = Kittn::APIClient.authorize!('meowmeowmeow') +{ + "uri": ".../account/401501489004/extension/401501489004/call-log?phoneNumber=16504445567&type=Voice&dateFrom=2014-09-18T00:00:00.000Z&dateTo=2014-09-25T00:00:00.000Z&page=1&perPage=100", + "records": [ + { + "uri": ".../account/401501489004/extension/401501489004/call-log/IXtVRs-3B7A_PfE", + "id": "IXtVRs-3B7A_PfE", + "sessionId": "404769762004", + "startTime": "2014-09-22T12:58:09.000Z", + "duration": 4, + "type": "Voice", + "direction": "Inbound", + "action": "Phone Call", + "result": "Accepted", + "to": { + "phoneNumber": "18662130006", + "name": "Steve Jones" + }, + "from": { + "phoneNumber": "16504445567", + "name": "Tony Black", + "location": "Palo Alto, CA" + } + }, + { + "uri": ".../account/401501489004/extension/401501489004/call-log/IXtVPRjQvSF5Pe4", + "id": "IXtVPRjQvSF5Pe4", + "sessionId": "404769755004", + "startTime": "2014-09-22T12:58:06.000Z", + "duration": 10, + "type": "Voice", + "direction": "Outbound", + "action": "VoIP Call", + "result": "Call connected", + "to": { + "phoneNumber": "16504445567", + "location": "Palo Alto, CA" + }, + "from": { + "phoneNumber": "18662130006", + "name": "Steve Jones" + } + } + ], + "paging": { + "page": 1, + "perPage": 100, + "pageStart": 0, + "pageEnd": 1 + }, + "navigation": { + "firstPage": { + "uri": ".../account/401501489004/extension/401501489004/call-log?phoneNumber=16504445567&type=Voice&dateFrom=2014-09-18T00:00:00.000Z&dateTo=2014-09-25T00:00:00.000Z&page=1&perPage=100" + } + } +} ``` -```python -import kittn +You may get exactly the records you require by setting a few filters. For example if you need the records over a week (dateFrom, dateTo) of voice calls (type) to/from a certain number (phoneNumber), sned the request having set the following query parameters: + +* `dateFrom` = 2014-09-18 +* `dateTo` = 2014-09-25 +* `type` = Voice +* `phoneNumber` = 16504445567 + +## Send SMS Message + +```http +POST https://platform.ringcentral.com/restapi/v1.0/account/~/extension/~/sms HTTP/1.1 +Authorization: Bearer U0pDMDFQMDFQQVMwMXxBQUFWZmY4ZXoxMlhvUFI5dmhYVzV +Content-Type: application/json +Accept: application/json +Content-Length: 323 + +{ + "to": [{"phoneNumber": "+18662130006"}], + "from": {"phoneNumber": "+16504445567"}, + "text": "Test SMS message from Platform server" +} +``` -api = kittn.authorize('meowmeowmeow') ``` +HTTP/1.1 200 OK +Content-Language: en +Content-Type: application/json; charset=UTF-8 +Content-Length: 926 -```shell -# With shell, you can just pass the correct header with each request -curl "api_endpoint_here" - -H "Authorization: meowmeowmeow" +{ + "uri": ".../account/401474882008/extension/401474882008/message-store/402206716008", + "id": 402206716008, + "to": [ + { + "phoneNumber": "+16505393204", + "location": "San Mateo, CA" + } + ], + "from": { + "phoneNumber": "+18004900003" + }, + "type": "SMS", + "creationTime": "2014-09-24T07:04:26.000Z", + "readStatus": "Read", + "priority": "Normal", + "attachments": [ + { + "id": 402206716008, + "uri": ".../account/401474882008/extension/401474882008/message-store/402206716008/content/402206716008", + "type": "Text", + "contentType": "text/plain" + } + ], + "direction": "Outbound", + "availability": "Alive", + "subject": "Test SMS message from Platform server", + "messageStatus": "Sent", + "smsSendingAttemptsCount": 1, + "conversationId": 5578972751633835268, + "lastModifiedTime": "2014-09-24T07:04:26.534Z" +} ``` -> Make sure to replace `meowmeowmeow` with your API key. +If you need to send a text message to somebody, you should use this URI: + +`POST /restapi/v1.0/account/{accountId}/extension/{extensionId}/sms` -Kittn uses API keys to allow access to the API. You can register a new Kittn API key at our [developer portal](http://example.com/developers). +Send `POST` request: Specify `accountId` and `extensionId` in the request URL or use simplified syntax with tilde characters. Specify the recipient phone number in the `to` field and one of your valid RingCentral phone numbers in the `from` field. Enter your message in the `text` field. -Kittn expects for the API key to be included in all API requests to the server in a header that looks like the following: +## Send Pager Message -`Authorization: meowmeowmeow` +# Getting Started + +## Installing the SDK + +To install the SDK, follow the online instructions posted at Github: + +[https://github.com/ringcentral/js-sdk#installation](https://github.com/ringcentral/js-sdk#installation) + +## Instantiating the SDK + +```javascript +var RC_SERVER_PRODUCTION = 'https://platform.ringcentral.com'; +var RC_SERVER_SANDBOX = 'https://platform.devtest.ringcentral.com'; + +var rcsdk = new RCSDK({ + server: RC_SERVER_SANDBOX, + appKey: 'yourAppKey', + appSecret: 'yourAppSecret' +}); +``` + +The SDK is represented by the global RCSDK constructor. Your application must create an instance of this object. + +In order to bootstrap the RingCentral JavaScript SDK, you have to first get a reference to the Platform singleton and then configure it. Before you can do anything using the Platform singleton, you need to configure it with the server URL (this tells the SDK which server to connect to) and your unique API key (this is provided by RingCentral’s developer relations team). -# Kittens +## Getting the Platform Singleton + +```javascript +var platform = rcsdk.getPlatform(); +``` + +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. + +## Login -## Get All Kittens +```javascript +platform.authorize({ + username: '+18001234567', // your phone number in E.164 format + extension: '101', // leave blank if direct number is used + password: 'yourpassword' +}).then(function(ajax) { + // your code here +}).catch(function(e) { + alert(e.message || 'Server cannot authorize user'); +}); +``` + +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. -```ruby -require 'kittn' +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. -api = Kittn::APIClient.authorize!('meowmeowmeow') -api.kittens.get +## Handling Authn Exceptions + +```javascript +platform.on(platform.events.accessViolation, function(e){ + // do something +}); ``` -```python -import kittn +To handle possible access or authentication exceptions that may occur while the application is running (after the user has successfully logged in), you can provide a handler for the `accessViolation` platform event. + + + +## Determining Authn Status + +```javascript +// To check authentication status: +platform.isAuthorized() + .then(function(){ ... }) + .catch(function(e){ ... }); + +// Checking authn status synchronously +// without auto-refresh of the access token +if (platform.isTokenValid()) {...} +``` + +The `isAuthorized` method will automatically perform a refresh of the access token, if needed. This method may be used in the login page of your application for automatic login. + +There is also a synchronous method for checking the authentication status that does not automatically perform a refresh of the access token. + +## Manual Access Token Refresh -api = kittn.authorize('meowmeowmeow') -api.kittens.get() +```javascript +// Refreshing the access token manually +platform.refresh().then(...) ``` -```shell -curl "http://example.com/api/kittens" - -H "Authorization: meowmeowmeow" +Access token refresh normally happens automatically for common use cases. On rare occasions, you may perform a refresh of the access token manually by calling the refresh method using the `platform.refresh()` method. + +## Logout + +```javascript +// without callback +platform.logout() +// with callback +platform.logout().then(...) ``` -> The above command returns JSON structured like this: +Your application can log out the user by calling the `platform.logout()` method. + +# Call Management + +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. + +A call management integration usually consists of the following tasks: + +* Track the telephony status +* View the list of active calls +* View the recent calls + +## Call States -```json -[ - { - "id": 1, - "name": "Fluffums", - "breed": "calico", - "fluffiness": 6, - "cuteness": 7 +```javascript + +// 1) Missed inbound call (Ringing -> No Call) +{ + "body": { + "telephonyStatus": "Ringing", + "extensionId": 607457016, + "activeCalls": [{"direction": "Inbound", "from": "13027430863", "telephonyStatus": "Ringing", "to": "18885434778", "sessionId": "67029198021", "id": "8ad4d5ea165f4e2aa00474a666368728"}], + "sequence": 133702 }, - { - "id": 2, - "name": "Isis", - "breed": "unknown", - "fluffiness": 5, - "cuteness": 10 - } -] + "timestamp": "2015-04-10T18:48:55.133+0000", + "uuid": "2b5bb8c0-c36c-46af-bd93-fb41e330d87c", + "event": "/restapi/v1.0/account/~/extension/607457016/presence?detailedTelephonyState=true" +} + +{ + "body": { + "telephonyStatus": "NoCall", + "extensionId": 607457016, + "activeCalls": [{"direction": "Inbound", "from": "13027430863", "telephonyStatus": "NoCall", "to": "18885434778", "sessionId": "67029198021", "id": "8ad4d5ea165f4e2aa00474a666368728"}], + "sequence": 133857 + }, + "timestamp": "2015-04-10T18:49:14.679+0000", + "uuid": "a5a876ab-3356-41e5-b1fe-fff91da3a281", + "event": "/restapi/v1.0/account/~/extension/607457016/presence?detailedTelephonyState=true" +} + +// 2) Answered inbound call (Ringing -> CallConnected -> NoCall) + +{ + "body": { + "telephonyStatus": "Ringing", + "extensionId": 607457016, + "activeCalls": [{"direction": "Inbound", "from": "13027430863", "telephonyStatus": "Ringing", "to": "18885434778", "sessionId": "67029198021", "id": "61803278cbf74d7490539a6174a6c094"}], + "sequence": 133897 + }, + "timestamp": "2015-04-10T18:49:20.858+0000", + "uuid": "c394ccf6-85dd-4da4-a87e-d31fac7f1283", + "event": "/restapi/v1.0/account/~/extension/607457016/presence?detailedTelephonyState=true" +} + +{ + "body": { + "telephonyStatus": "CallConnected", + "extensionId": 607457016, + "activeCalls": [{"direction": "Inbound", "from": "13027430863", "telephonyStatus": "CallConnected", "to": "18885434778", "sessionId": "67029198021", "id": "61803278cbf74d7490539a6174a6c094"}], + "sequence": 133942 + }, + "timestamp": "2015-04-10T18:49:26.687+0000", + "uuid": "96df6fdd-a2a4-42fb-bc34-cffb5d637754", + "event": "/restapi/v1.0/account/~/extension/607457016/presence?detailedTelephonyState=true" +} + +{ + "body": { + "telephonyStatus": "NoCall", + "extensionId": 607457016, + "activeCalls": [{"direction": "Inbound", "from": "13027430863", "telephonyStatus": "NoCall", "to": "", "sessionId": "67029198021", "id": "61803278cbf74d7490539a6174a6c094"}], + "sequence": 134051 + }, + "timestamp": "2015-04-10T18:49:41.828+0000", + "uuid": "7fa7ac3c-5b7b-4127-88ec-9734f478d4a3", + "event": "/restapi/v1.0/account/~/extension/607457016/presence?detailedTelephonyState=true" +} + +// 3) 2-legged Ringout +{ + "body": { + "telephonyStatus": "Ringing", + "extensionId": 255537016, +"activeCalls": [{"to": "16502008440", "direction": "Outbound", "from": "16509540334", "sessionId": "915021981016", "telephonyStatus": "Ringing"}], + "sequence": 46061598 + }, + "timestamp": "2015-04-17T19:38:59.718+0000", + "uuid": "305b8075-5dad-4686-b22a-d26744802566", "event": "/restapi/v1.0/account/~/extension/255537016/presence?detailedTelephonyState=true" +} + +{ + "body": { + "telephonyStatus": "CallConnected", + "extensionId": 255537016, + "activeCalls": [{"direction": "Outbound", "from": "16509540334", "telephonyStatus": "CallConnected", "to": "16502008440", "sessionId": "915021981016", "id": "b5ea44d61b6a4658aadf948348db069c"}], + "sequence": 46062162 + }, + "timestamp": "2015-04-17T19:39:12.950+0000", + "uuid": "71673991-dad0-4c8e-9c22-78b0244c790c", + "event": "/restapi/v1.0/account/~/extension/255537016/presence?detailedTelephonyState=true" +} + +{ + "body": { + "telephonyStatus": "NoCall", + "extensionId": 255537016, + "activeCalls": [{"direction": "Outbound", "from": "16509540334", "telephonyStatus": "NoCall", "to": "16502008440", "sessionId": "915021981016", "id": "b5ea44d61b6a4658aadf948348db069c"}], + "sequence": 46063265 + }, + "timestamp": "2015-04-17T19:39:40.172+0000", + "uuid": "97b01949-1438-45f2-856a-54f89e83367f", + "event": "/restapi/v1.0/account/~/extension/255537016/presence?detailedTelephonyState=true" +} ``` -This endpoint retrieves all kittens. +* A call may consist of multiple call legs. Top-level telephonyStatus should be aggregated across these multiple call legs. +* A call is identified by its sessionId. For tracking a call, application should match by sessionId across activeCall items from multiple notifications. +* In some rare cases notifications can be delivered in incorrect order. Application should remember largest “sequence” value from an event for a given call (identified by its sessionId) and ignore any events which come later with smaller “sequence” -### HTTP Request +Some typical event flows for inbound calls are listed for the following scenarios: -`GET http://example.com/kittens` +1. Missed inbound call (Ringing -> No Call) +1. Answered inbound call (Ringing -> CallConnected -> NoCall) +1. 2-legged Ringout -### Query Parameters +## Call Notification -Parameter | Default | Description ---------- | ------- | ----------- -include_cats | false | If set to true, the result will also include cats. -available | true | If set to false, the result will include kittens that have already been adopted. +```javascript +var subscription = rcsdk.getSubscription(); -