Subscribing to events via WebSockets

WebSockets provide a medium by which event notifications can be delivered to an application via a persistent, low-latency network connection. This allows applications to receive notifications of events of interest to them in near real-time. In the guide that follows, we will describe how developers can subscribe to events over WebSockets, and how to process events that are received.

If you are new to Websockets, we recommend you to begin your learning journey with an online tutorial about the protocol and technology.

Assigning the WebSocketsSubscription app scope to your application

Before any application that wishes to subscribe to an event via WebSockets, the app must first possess the WebSocketsSubscription app scope. This will allow associated apps to call the necessary endpoints to establish a connection to a RingCentral WebSockets server.

Subscribing to events via an SDK

If you are using one of RingCentral's officially supported SDKs, then subscribing to events couldn't be easier as the SDKs manage much of the complexity for you. All you need to do is process events as they come in over the WebSocket. To learn how to subscribe to events using the SDKs, checkout our WebSockets Quick Start guide.

Subscribing to events manually

If you need to implement your own subscription layer for WebSockets, or if you simply want to better understand what is happening behind the scenes, then the follow material will help you.

Obtaining a WebSocket access token and server URL

A WebSocket access token is required in order to open up a connection with a RingCentral WebSockets server. To obtain a WebSocket access token, you must first obtain an API access token via one of our established authorization mechanisms (e.g. OAuth or JWT. Using that access token, you will request a WebSockets access token and server URL through the following request.

POST /restapi/oauth/wstoken HTTP/1.1
Authorization: Bearer <access token>

If successful, RingCentral will respond with something similar to the following:

HTTP/1.1 200 OK
Content-type: application/json

{
  "ws_access_token": "U0pDMDFQMDdQQxxxxxxxxx9pSU9OemVzakpn",
  "uri": "wss://servername.ringcentral.com/ws",
  "expires_in": 30
}

The WebSockets access token that is returned is good for a single-use only when connecting to the WebSockets server specified in the uri response property.

Connecting to the WebSockets server

With an access token and server URL in hand, you can now connect to the WebSockets server to begin receiving events. We recommend utilizing a freely available third-party WebSockets library to aid in the processing of incoming events.

To connect to the WebSockets server, you will need to compose the server URL by appending the server URI with the access token in the following way:

wss://servername.ringcentral.com/ws?access_token=U0pDMDFQMDdQQxxxxxxxxx9pSU9OemVzakpn

When a connection is successfully made, the WebSockets server will transmit a ConnectionDetails message similar to the following:

[
  {
    "type": "ConnectionDetails",
    "messageId": "156eec30-xxxx-xxxx-xxxx-005056bf7145",
    "status": 200,
    "wsc": {
      "token": "RTFhRG5nfExxxxxxxxxxxcHE3bXkyRURQVQ",
      "sequence": 1
    },
    "headers": {
      "RCRequestId": "156eec30-xxxx-xxxx-xxxx-005056bf7145"
    }
  },
  {
    "creationTime": "2020-09-07T21:50:02.737+0000",
    "maxConnectionsPerSession": 50,
    "recoveryBufferSize": 100,
    "recoveryTimeout": 180,
    "idleTimeout": 1800,
    "absoluteTimeout": 86400,
    "maxActiveRequests": 10
   }
 ]

Subscribe to events

With a connection to the WebSockets server now established, you can transmit your own message to the server specifying the events you wish to subscribe to. Unlike a webhook subscription which is a persistent and managed by RingCentral servers, a WebSockets event subscription is only valid while the WebSocket connection and client is active. If for whatever reason you lose your connection to the WebSockets server and need to re-establish connectivity, you will need to resubscribe to the events you are in need of.

To subscribe to events, you will need to transmit a ClientRequest specifying the event filters you wish to subscribe to. For example, the following will subscribe to incoming SMS and incoming voicemail events.

[
  {
    "type" : "ClientRequest",
    "messageId" : "11618510-987d-442e-8dcf-0640b82e4ff5",
    "method" : "POST",
    "path" : "/restapi/v1.0/subscription/"
  },
  {
    "eventFilters": [
      "/restapi/v1.0/account/~/extension/~/message-store/instant?type=SMS",
      "/restapi/v1.0/account/~/extension/~/voicemail"
    ],
    "deliveryMode": {
      "transportType": "WebSocket"
    }
  }
]