Stories by Tyler Liu on Medium

Minimum code to run a WebPhone SDK project

Tyler Liu — Tue, 17 Mar 2026 22:28:34 GMT

Let’s be honest: modern web development can sometimes feel like an endless maze of configuration. Between Webpack, Vite, Parcel, TypeScript, and endless npm install commands, just getting a simple "Hello World" off the ground can take longer than writing the actual code.

But it doesn’t have to be that way.

If you want to integrate voice calling into your browser using the RingCentral WebPhone SDK, you don’t need a massive tech stack. You don’t need a build step. You don’t even need a bundler.

Here is the absolute simplest, minimal code required to get a WebPhone running in a single HTML file using pure Vanilla JavaScript.

The Code

Save the following code into an index.html file:

Breaking It Down

That’s it. 30 lines of code. Here is exactly why this is so simple:

No Bundlers: We pull the SDK directly from the jsdelivr CDN. No Node modules required.
Initialization: We instantiate the WebPhone class and pass it a sipInfo object.
Action: We wire up a single HTML button to toggle between making a call (webPhone.call()) and hanging up (activeSession.hangup()). The SDK handles the heavy lifting of WebRTC under the hood.

Two Crucial Things to Know

Before you test this out, there are two important rules you need to follow for this to work perfectly.

1. You Must Use a Local Server You cannot simply double-click the index.html file and open it in your browser via the file:// protocol. While Safari might forgive you, Chrome and most other modern browsers will block microphone access and WebRTC features due to strict security and permission restrictions.

The Fix: Host the file using a simple local server. If you have Python installed, run python -m http.server in your folder. If you have Node, run npx http-server. Then navigate to http://localhost:8000.

2. The Magic of the sipInfo Object You might have noticed that there are no client IDs, client secrets, JWTs, usernames, or passwords in this code. The frontend only cares about one thing: the sipInfo object.

How to get it: You will need your API credentials temporarily to generate a sipInfo object via the RingCentral SIP Registration API.
The best part: The sipInfo object does not expire. Once you generate it (perhaps via an API testing tool like Postman or a quick backend script), you can hardcode it into this vanilla HTML project and never worry about auth tokens or login flows in your UI.

Conclusion

Integrating a web phone doesn’t require a heavy, complex architecture. By stripping away the build tools and focusing on the core SDK, you can have a functional, browser-based phone ready to make calls in just a few minutes.

Happy coding!

Be the First to Say Happy Birthday — Automatically

Tyler Liu — Tue, 10 Jun 2025 15:02:19 GMT

Be the First to Say Happy Birthday, Automatically

Have you ever received a call at exactly 12:00 AM on your birthday? I have, and let me tell you, it’s unforgettable. That moment becomes your very first memory of the day, and it sets the tone. Whether it’s a birthday or New Year’s Eve, being the first to send heartfelt wishes makes a lasting impact.

Now imagine you being that person for your loved ones, without even staying up late.

The Problem: Midnight Wishes Are Easy to Miss

We all have good intentions. You want to call your friend or family member at midnight, just like they did for you. But life gets in the way. You fall asleep. You forget. Or you look at the clock and it’s already 12:05, missed your chance to be the first.

The Solution: Let Code Do It for You

What if a simple program could call your loved one at midnight and deliver your birthday wishes, automatically? With less than 30 lines of code, you can make it happen.

Here’s how:

import Softphone from "ringcentral-softphone";
import waitFor from "wait-for-async";
import fs from "fs";

const softphone = new Softphone({
  domain: process.env.SIP_INFO_DOMAIN!,
  outboundProxy: process.env.SIP_INFO_OUTBOUND_PROXY!,
  username: process.env.SIP_INFO_USERNAME!,
  password: process.env.SIP_INFO_PASSWORD!,
  authorizationId: process.env.SIP_INFO_AUTHORIZATION_ID!,
});
softphone.enableDebugMode();

const main = async () => {
  await softphone.register();
  const callSession = await softphone.call(process.env.YOUR_FRIENDS_NUMBER!);
  callSession.once("answered", async () => {
    await waitFor({ interval: 1000 });
    const streamer = callSession.streamAudio(
      fs.readFileSync("test.wav"),
    );
  });
};
main();

This code uses the RingCentral Softphone SDK, soon to be known as Cloud Phone SDK. It allows you to place automated VoIP calls and stream audio messages, perfect for surprise greetings.

What Does the Code Do?

Initializes the softphone using your SIP credentials
Registers with the RingCentral SIP server
Dials your friend’s number
Waits for them to answer
Streams a pre-recorded birthday greeting

That’s it. No GUI. No distractions. Just pure automation magic.

Fully runnable code is hosted here.

Creating the Greeting Audio File

You don’t need a fancy studio to make your message. You can generate it from the command line using macOS’s say command:

say "Hey Tyler\! Just wanted to give you a quick call to wish you a very happy birthday\! Hope you're having an amazing day, filled with fun, laughter, and everything you love. You deserve the best - enjoy your day and celebrate big\! Talk to you soon\!" -o test.wav --data-format=LEI16@16000

This creates a .wav file in the format required by the SDK. You can record your own voice if you'd rather make it more personal.

How to Run the App

From your terminal:

yarn test

Make sure your environment variables (SIP_INFO_*, YOUR_FRIENDS_NUMBER) are properly set.

How to Schedule the App to Run on Your Friend’s Birthday

To make sure the birthday call goes out at exactly 12:00 AM on your friend’s special day, use a cron job that runs once a year.

For example, if your friend’s birthday is July 15, add this to your crontab:

0 0 15 7 * cd /home/tyler/happy-birthday-caller && /usr/bin/env yarn test >> /home/tyler/happy-birthday-caller/birthday.log 2>&1

00 — run at 12:00 AM
15 — on the 15th day
7 — of the 7th month (July)
* — every day of the week (no restriction)

To edit your crontab:

crontab -e

Paste the line above, and save.

That’s it. Your app will run automatically every year on your friend’s birthday, right at midnight, no alarms, no missed moments.

Test It First

Before relying on it for an actual birthday, test your setup. Temporarily change the caller number to your own number and change the cron schedule to run every minute:

* * * * * cd /home/tyler/happy-birthday-caller && /usr/bin/env yarn test >> /home/tyler/happy-birthday-caller/test.log 2>&1

Watch the logs and confirm that the call is placed and audio is played as expected.

Once confirmed, change it back to the real date and your friend’s phone number.

Behind the Scenes: Powered by Softphone SDK

This birthday greeting example is more than just a fun automation project, it’s a powerful demonstration of what the RingCentral Softphone SDK (soon to be rebranded as Cloud Phone SDK) can do.

With just a few lines of JavaScript, you can:

Programmatically register a SIP client
Place outbound VoIP calls
Detect when the call is answered
Stream pre-recorded audio to the callee

All with full control and event handling, no need to deal with low-level SIP or media stack complexities.

This birthday call is just one example. The same functionality can power real-world use cases like:

Automated appointment reminders
Delivery or pickup voice alerts
Emergency callouts or school closure notices
Interactive voice menus (IVRs)

Whether you’re a hobbyist or building enterprise-grade tools, the Softphone SDK makes it easy to bring voice automation into your apps.

Try It for Yourself

If this inspired you, imagine what else you can create. With the Softphone SDK, voice is no longer just for phones, it’s programmable, flexible, and ready for your ideas.

Voice is powerful. With the right SDK, it’s programmable too.

RingCentral Softphone SDK (soon to be rebranded as Cloud Phone SDK).

Start building today. 🎉

Be the First to Say Happy Birthday — Automatically was originally published in RingCentral Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Empower Your AI with Real-Time Phone Call Intelligence: RingCentral Softphone SDK

Tyler Liu — Tue, 03 Jun 2025 15:24:58 GMT

For AI startups building the future of voice-driven solutions, accessing real-time phone audio is mission-critical. RingCentral’s Softphone SDK cuts through the complexity, giving developers instant access to call audio streams, so you can focus on what matters: building groundbreaking AI features.

Why AI Startups Choose RingCentral

1️⃣ Instant Access to Call Audio Streams

Capture inbound/outbound call audio in real time for transcription, emotion detection, live translation, or AI agent training.
Plug-and-play TypeScript SDK: Skip SIP protocol headaches. Focus on your AI models, not telephony infrastructure.
Multi-Codec Support (OPUS, PCMU): Process high-fidelity audio optimized for AI/ML pipelines.

// Stream call audio directly to your AI model  
callSession.on("rtpPacket", (rtpPacket) => {  
  if (rtpPacket.header.payloadType === softphone.codec.id) {  
    yourAIPipeline.analyze(rtpPacket.payload); // 🚀 Unlock real-time insights  
  }  
});

2️⃣ Build Fast, Scale Faster

Zero per-minute fees: Predictable pricing for startups scaling AI call solutions.
Programmatic SIP setup: Automate credentials via REST API — no manual config.
Active call management: Run concurrent instances to handle high-volume AI workflows.

3️⃣ AI-Ready Features

Inbound/outbound call control: Create AI agents, call coaches, or automated QA tools.
DTMF support: Integrate voice + touch-tone interactions (e.g., IVR + AI assistants).
Call transfer/hangup: Dynamically route calls based on AI decisions.

Get Started in 5 Minutes

yarn install ringcentral-softphone  # Install

👉 Explore Demos: GitHub Examples

Why Reinvent the Wheel?

While others force you to wrestle with telephony protocols, RingCentral gives you:

✅ TypeScript-first SDK: Modern, type-safe, and battle-tested.
✅ Enterprise-grade reliability: Built by a leader in cloud communications.
✅ End-to-end audio pipelines: From codec decoding to real-time streaming — it’s all handled.

Your AI, Their Voices — No Limits.
Start Building Today

AI startups: Turn every phone call into a data goldmine. With RingCentral, the future of voice intelligence is just a line of code away. 🧠🔊

Empower Your AI with Real-Time Phone Call Intelligence: RingCentral Softphone SDK was originally published in RingCentral Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

RingCentral Web Phone SDK 2.0

Tyler Liu — Fri, 25 Oct 2024 21:29:53 GMT

It is a complete rewrite of the SDK compared to 1.x versions.

Why rewrite?

The rewriting is to get rid of SIP.js.

SIP.js is no longer actively maintained

The last release of SIP.js was in October 2022, and it hasn’t been updated since. Depending on an unmaintained library poses risks, including potential incompatibility with future browser updates and WebRTC changes. By moving away from SIP.js, we ensure that our SDK remains compatible with evolving web standards.

SIP.js lacks support for essential RingCentral features

SIP.js was not built with RingCentral’s specific requirements in mind. To support critical functionalities like confirming receipt, sending calls to voicemail, declining, forwarding, replying, call recording (start/stop), call flipping, and parking, we had to patch SIP.js heavily. Managing these patches was inefficient, and developing our own signaling library is a more sustainable approach.

SIP signaling is simple enough to implement in-house

SIP signaling itself is a relatively straightforward protocol. By implementing the SIP signaling in-house, we can avoid the overhead and complexity introduced by SIP.js while gaining full control over the signaling flow.

Decoupling SIP signaling from WebRTC

SIP.js tightly couples SIP signaling with WebRTC. By decoupling these two components, we allow you to run a web phone with a real/dummy SIP client, which is essential for scenarios where you need to run multiple web phones in multiple tabs.

Breaking changes

API changes

2.x version is a complete rewrite of the RingCentral Web Phone SDK. The API is completely different from 1.x version.

ringing audio

This SDK doesn’t play ringing audio when there is incoming call or outgoing call. It’s up to the developer/app to play the audio. It’s a by design change. We made this change because we want to give the developer/app more flexibility. And playing ringing audio is not a core feature of the SDK. It’s more about how the app interacts with end users.

call forward

SDK 1.x treats forwarding as answering the call and then transfer the call. SDK 2.x treats forwarding as sending a SIP message to the SIP server to forward the call. I would like to say this is more like a bug fix than a behavior change.

SDK 1.x requires you to provide elements to play remote audio. SDK 2.x will create elements on demand. You don’t need to provide elements.

Summary

In this article, I included information about why we released a brand new 2.0 version and I also listed all the breaking changes.

How to disable auto token refreshment for RingCentral JavaScript SDK

Tyler Liu — Mon, 22 Apr 2024 22:52:40 GMT

Give you all the control over token management

RingCentral JavaScript SDK is available here: https://www.npmjs.com/package/@ringcentral/sdk

It’s source code is here: https://github.com/ringcentral/ringcentral-js/tree/master/sdk

The SDK

A sample application is like this:

import { SDK } from '@ringcentral/sdk';

const sdk = new SDK({
  server: process.env.RINGCENTRAL_SERVER_URL,
  clientId: process.env.RINGCENTRAL_CLIENT_ID,
  clientSecret: process.env.RINGCENTRAL_CLIENT_SECRET,
});

// we print all the HTTP requests
const client = sdk.client();
client.on(client.events.requestSuccess, (apiResponse) => {
  console.log('We made an API call to', apiResponse.url);
});

const platform = sdk.platform();

const main = async () => {
  await platform.login({
    jwt: process.env.RINGCENTRAL_JWT_TOKEN,
  });
  await platform.get('/restapi/v1.0/account/~/extension/~');
};
main();

Sample output:

We made an API call to https://platform.ringcentral.com/restapi/oauth/token
We made an API call to https://platform.ringcentral.com/restapi/v1.0/account/~/extension/~

The first line of output is generated by this API call:

await platform.login({
  jwt: process.env.RINGCENTRAL_JWT_TOKEN,
});

The second line of output is generated by this API call:

await platform.get('/restapi/v1.0/account/~/extension/~');

The interesting fact

RingCentral access token expires in 1 hour. What will happen if we invoke an API after 2 hours? You may expect an exception. Because you cannot invoke RingCentral API with an expired access token. Will there be an exception?

Let’s try:

import { SDK } from '@ringcentral/sdk';
import waitFor from 'wait-for-async';

...
await pltaform.login({
  jwt: process.env.RINGCENTRAL_JWT_TOKEN
});
await platform.get('/restapi/v1.0/account/~/extension/~');
await waitFor({ interval: 7200000 }); // 2 hours
await platform.get('/restapi/v1.0/account/~/extension/~');

The output is:

We made an API call to https://platform.ringcentral.com/restapi/oauth/token
We made an API call to https://platform.ringcentral.com/restapi/v1.0/account/~/extension/~
We made an API call to https://platform.ringcentral.com/restapi/oauth/token
We made an API call to https://platform.ringcentral.com/restapi/v1.0/account/~/extension/~

Surprisingly, there is no exception! The first two lines of output are same as before. There are two more lines of output. The last line of output is for our API call, there is no exception. What is the 3rd line? It says so:

We made an API call to https://platform.ringcentral.com/restapi/oauth/token

It turns out that the SDK automatically refreshed the access token for us! It’s magic! Let’s dive into the source code of the SDK and see how it work:

When we invoke the API, we use the platform.get(...) method: https://github.com/ringcentral/ringcentral-js/blob/77484be7fc946e72f1b119fd31e8a49d72e31497/sdk/src/platform/Platform.ts#L787-L789

which invokes the platform.send(...) method: https://github.com/ringcentral/ringcentral-js/blob/77484be7fc946e72f1b119fd31e8a49d72e31497/sdk/src/platform/Platform.ts#L761

which invokes the platform.sendRequest(…) method: https://github.com/ringcentral/ringcentral-js/blob/77484be7fc946e72f1b119fd31e8a49d72e31497/sdk/src/platform/Platform.ts#L716

which invokes the platform.inflateRequest(…) method: https://github.com/ringcentral/ringcentral-js/blob/77484be7fc946e72f1b119fd31e8a49d72e31497/sdk/src/platform/Platform.ts#L698

which invokes the platform.ensureLoggedIn(…) method: https://github.com/ringcentral/ringcentral-js/blob/77484be7fc946e72f1b119fd31e8a49d72e31497/sdk/src/platform/Platform.ts#L807

which invokes the platform.refresh(…) method:https://github.com/ringcentral/ringcentral-js/blob/77484be7fc946e72f1b119fd31e8a49d72e31497/sdk/src/platform/Platform.ts#L810

That’s such a long method call chain! Let me summarize what it does: when you invoke an API, the SDK will check your access token expire time, if it expires, the SDK will automatically refresh the token for you.

This interesting fact is both a blessing and a curse. For people scratching quick and dirty simple applications, it saves their headache of refreshing the token themselves. But for complicated enterprise applications, this token auto refreshing feature could be really annoying.

The issue/problem

More often than not, developers want to manage token lifecycle themselves, especially for complicated enterprise applications. For example, some developer may store the token in a central database, and share the token among multiple applications (or multiple instances of the same application code base).

If multiple applications sharing the same token are all use the JavaScript SDK, by default, the SDK will automatically refresh the token, which will cause several issues:

token synchronization: one application refreshes the token will cause all other applications to have a revoked token. Thus, it is necessary to sync the token to all other applications.
racing condition: if two/multiple applications try to refresh the token at the same time, RingCentral server will make sure that only one of them will succeed. You may encounter token refresh failure due to this reason.
hard to take full control of the token lifecycle: let’s say you write a dedicated application to maintain the token’s lifecycle. This specially coded app will make sure that tokens are properly refreshed and maintained. If all the token consuming applications also refresh the token, it will again bring up the token synchronize and racing condition problem.

Can we just get rid of this problem?

The solution

First of all, I would like to emphasize that this solution is not necessary for simple applications. Let’s say you have an simple desktop application that you start once a day to send a fax. If it works, you don’t need to change it. You don’t need to care about how the token is refreshed.

If your application is distributed, tokens are shared among different servers/clients, and you want to centrally manage the token’s lifecycle. In the meantime, you don’t want anything magical happen to your token. You want full control over token’s lifecycle. If it sounds like your case, then the solution is for you.

The solution is very simple:

platform.ensureLoggedIn = async () => null;

Just rewrite the platform.ensureLoggedIn method and make sure it does nothing. This is because, we want to manage the token ourselves, we don’t need the ensureLoggedIn feature provided by the SDK. Please note that, if you are using the platform.ensureLoggedIn method directly in your code base, you need to change it to some other code. Since this method has been overridden to do nothing.

Then how do we refresh the token? easy:

await platform.refresh();

Or you may setup a timer to do it every 30 minutes:

setInterval(async () => {
  await platform.refresh();
}, 1800000);

Or you may create a dedicated application to refresh the token and let the app trigger by cron jobs.

You have the full flexibility to decide when and how you refresh your token.

Please note that, if multiple apps are using the token, you still need to sync the new token to all apps after token refreshment. This is inevitable. But at least, you token is bing refreshed and managed in a central place. There is no more magic happening to your tokens.

Source code

The source code for this article is available here: https://github.com/tylerlong/rc-js-sdk-no-auto-refresh-token-demo

Update

Nowadays I would recommend you to use https://github.com/ringcentral/ringcentral-extensible instead. This SDK is also officially supported. It doesn’t touch your token by default. And it has way better TypeScript support.

How to disable auto token refreshment for RingCentral JavaScript SDK was originally published in RingCentral Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Code a RingCentral WebSocket SDK from scratch

Tyler Liu — Tue, 18 Apr 2023 20:59:01 GMT

Technical details about RingCentral WebSocket API

What is RingCentral Subscription API?

A subscription refers to how events are delivered to an application. Events are synonymous with notifications, and refer to messages that are sent after they are triggered by an action, or state-change on the platform.

For example, you may subscribe to the following events:

SMS received
Presence/availability changed
Call started/ended

What is RingCentral WebSocket API?

It is mainly a new way to create subscription and receive events. Another popular way is to use WebHook(for more information about RingCentral WebHook, please read this article). WebHook requires you to have a public URL that RingCentral server can access. But if your app doesn’t have a public URL (most non-web applications don’t have an URL at all), you cannot use WebHook. In such case, you may use WebSocket to create subscription and receive events.

Please note that, RingCentral WebSocket API can do more than just subscriptions. For example, you may send “RESTful” API calls via WebSocket protocol. But in this article, we will focus on subscriptions.

Official RingCentral WebSocket SDKs

We have provided the following official WebSocket SDKs:

At the moment, we do not provide official SDKs for other programming languages. We may provide more SDKs in the future, but we are unlikely able to provide SDKs for every programming language existed (there are thousands of them). That’s why I am drafting this article. I will cover the details for how you can code your own RingCentral WebSocket SDK.

Prerequisites

We assume that you are already familiar with basic RingCentral API programming.

You should have a RingCentral developer account.
You should have create a RingCentral App.
Your RingCentral App must have permission “WebSocket Subscriptions”. At the moment the permission is internal. You may create a ticket to add it: https://developers.ringcentral.com/support/create-case
You should know where to find the credentials (clientId/clientSecret/JWT token…etc) for testing purpose.
You should know how to get access token and make API calls.

If you are not familiar with the things I mentioned above, please check the latest articles from my colleague Desika Srinivasan and A Lohith:

Please note that, the information shared in the 3 articles are very detailed-oriented and low-level. You probably want to use one of our REST SDKs to simplify the coding part. For example, to make API call using our Java SDK, refer to this example: https://github.com/ringcentral/ringcentral-java/blob/master/src/test/java/com/ringcentral/LowLevelAPITest.java

You are supposed to know at least one programming language. We will use Java as example, but the knowledge shared here should apply to other languages as well.

Connect to WebSocket Server

Make A REST API call to /restapi/oauth/wstoken

restClient.post("/restapi/oauth/wstoken")

The API response is a JSON string with the following data fields:

class WsToken {
    public String uri;
    public String ws_access_token;
    public int expires_in;
}

A sample response looks like this:

{
  "uri" : "wss://ws-api.devtest.ringcentral.com/ws",
  "ws_access_token" : "xxxxx",
  "expires_in" : 60
}

With the information above, we can connect to the WebSocket server using our favorite WebSocket client library:

String wsUri = wsToken.uri + "?access_token=" + wsToken.ws_access_token;
MyWebSocketClient myClient = new MyWebSocketClient(URI.create(wsUri));
myClient.connect();

Post messages to WebSocket server

In this section, we are going to create a subscription by posting messages to WebSocket server. You may post message to WebSocket server to invoke lots of different API endpoints. But here we take subscription creation for example, because in the next section we are going to demo how to receive notifications.

A message that you send to the WebSocket server contains two parts: the header and the body. But wait, does a WebSocket message support a header at all? Nope, it doesn’t. So by design, the WebSocket server requires us to send it an array contains both the header and the the body, like this: [header, body].

The header data structure is like this:

class RequestHeaders {
    public String type;
    public String messageId;
    public String method;
    public String path;
}

We can build a header object like this:

RequestHeaders requestHeaders = new RequestHeaders();
requestHeaders.method = "POST";
requestHeaders.path = "/restapi/v1.0/subscription";
requestHeaders.type = "ClientRequest";
requestHeaders.messageId = UUID.randomUUID().toString();

How about the body? It turns out that the body is the same as you make a REST API call. We can look it up in the API reference page. For HTTP POST /restapi/v1.0/subscription, check this page: https://developers.ringcentral.com/api-reference/Subscriptions/createSubscription We can build a body object like this:

SubscriptionRequestBody requestBody = new SubscriptionRequestBody();
requestBody.deliveryMode = new SubscriptionRequestBodyDeliveryMode();
requestBody.deliveryMode.transportType = "WebSocket";
requestBody.eventFilters = new String[]{"/restapi/v1.0/account/~/extension/~/message-store"};

Let’s put the header and body into an array and convert the array into a JSON string:

Object[] array = new Object[2];
array[0] = requestHeaders;
array[1] = requestBody;
String messageString = Utils.gson.toJson(array);

We may send the messageString to the WebSocket server:

myClient.send(messageString);

If everything goes well, the server will send you a reply message. The reply message is also an array containing two parts: the header and the body. Here a I provide a sample response for your reference:

[
  {
    "type": "ClientRequest",
    "messageId": "9fb4f43b-5b9d-4eb3-a8ac-9df81b5de783",
    "status": 200,
    "headers": {
      "Server": "nginx",
      "Date": "Tue, 18 Apr 2023 20:25:16 GMT",
      "Content-Type": "application/json",
      "WSG-SubscriptionId": "2db5fcc4-c515-423e-8c2f-fa9b78dd9a55",
      "WSG-SubscriptionTTL": "86399",
      "X-Rate-Limit-Group": "medium",
      "X-Rate-Limit-Limit": "999",
      "X-Rate-Limit-Remaining": "998",
      "X-Rate-Limit-Window": "60",
      "RoutingKey": "SJC12P01",
      "RCRequestId": "2119cb78-de27-11ed-8151-005056a61ee6-18"
    }
  },
  {
    "uri": "/restapi/v1.0/subscription/2db5fcc4-c515-423e-8c2f-fa9b78dd9a55",
    "id": "2db5fcc4-c515-423e-8c2f-fa9b78dd9a55",
    "creationTime": "2023-04-18T20:25:16.139Z",
    "status": "Active",
    "eventFilters": [
      "/restapi/v1.0/account/233676004/extension/233676004/message-store"
    ],
    "expirationTime": "2023-04-19T20:25:16.139Z",
    "expiresIn": 86399,
    "deliveryMode": {
      "transportType": "WebSocket",
      "encryption": false
    }
  }
]

There is a text field “expiresIn”: 86399 , but don’t worry about its expiration. Because by design the WebSocket server will refresh it automatically. You don’t need to refresh it yourself.

Receive notifications

This part is relatively simple. With the subscription created, what we need to do is to listen to messages from server side and pick the ones that we are interested in. A typical notification message looks like this:

[
  {
    "type": "ServerNotification",
    "messageId": "2661273919712564939",
    "status": 200,
    "headers": {
      "RCRequestId": "265348d0-de27-11ed-944a-005056a62c0c"
    }
  },
  {
    "uuid": "2661273919712564939",
    "event": "/restapi/v1.0/account/233676004/extension/233676004/message-store",
    "timestamp": "2023-04-18T20:25:24.611Z",
    "subscriptionId": "2db5fcc4-c515-423e-8c2f-fa9b78dd9a55",
    "ownerId": "233676004",
    "body": {
      "accountId": 233676004,
      "extensionId": 233676004,
      "lastUpdated": "2023-04-18T20:25:15.775Z",
      "changes": [
        {
          "type": "Pager",
          "newCount": 2,
          "updatedCount": 0,
          "newMessageIds": [
            12756735005,
            12756737005
          ]
        }
      ]
    }
  }
]

Again this message is an array containing two parts: the header and the body. And the header has “type”: “ServerNotification” . The body is identical to a WebHook notification’s body. You may check the specification of all the notification types here: https://developers.ringcentral.com/api-reference/Account-Presence-Event.

Known limitations

It is known that each WebSocket connection can only have one active subscription. If you try to create more, previous ones will be overwritten. If you need to create multiple subscriptions, you need to create multiple WebSocket connections.

Sample code for your reference

Please refer to the implementation of the official RingCentral WebSocket Java SDK.

Create WebSocket subscriptions using RingCentral JavaScript SDKs

Tyler Liu — Wed, 18 Jan 2023 22:14:39 GMT

A quick start guide for RingCentral WebSocket Subscriptions

What are subscriptions for?

First things first, why do you need to create subscriptions? If your application needs to get notified when something happens (like new sms received, new incoming call…etc), you need to create subscriptions to those events. Creating a subscription is like telling RingCentral server that your application is interested in some events. Then your application will get notified when such such events occur.

Different ways to create subscriptions

At the moment, there are 2 official ways to create subscriptions: WebHook and WebSocket. (There was a legacy way to use PubNub to create subscriptions that we do not recommend any more).

In this article, we will focus on creating subscriptions using WebSocket. If you are interesting in WebHooks, please read this article instead.

Prerequisites

Your RingCentral application needs to have the “WebSocket Subscriptions” permission.

If for some reason you cannot enable this permission for your application, please create a support case here.

Recommended way

You are recommended to use @rc-ex/core and @rc-ex/ws. They have excellent TypeScript support and they are actively maintained.

import RingCentral from '@rc-ex/core';
import WebSocketExtension from '@rc-ex/ws';

const rc = new RingCentral({
  server: process.env.RINGCENTRAL_SERVER_URL,
  clientId: process.env.RINGCENTRAL_CLIENT_ID,
  clientSecret: process.env.RINGCENTRAL_CLIENT_SECRET,
});
const wsExtension = new WebSocketExtension();

const main = async () => {
  await rc.authorize({
    jwt: process.env.RINGCENTRAL_JWT_TOKEN!,
  });
  // install the WebSocket extension
  await rc.installExtension(wsExtension);

  // subscribe
  await wsExtension.subscribe(
    ['/restapi/v1.0/account/~/extension/~/message-store'],
    evt => {
      console.log(JSON.stringify(evt, null, 2));
    }
  );

  // trigger an event, optional
  const ext = await rc.restapi().account().extension().get();
  await rc
    .restapi()
    .account()
    .extension()
    .companyPager()
    .post({
      from: {extensionId: ext.id?.toString()},
      to: [{extensionId: ext.id?.toString()}],
      text: 'Hello world!',
    });
};

main();

In the sample code above, we are using the RingCentral Extensible SDK. RingCentral Extensible is a SDK with a tiny core (@rc-ex/core) and lots of extensions. It is an endeavor to get rid of bloated SDK. You install extensions on demand. In order to support WebSocket, we also installed the @rc-ex/ws extension.

The code is pretty straightforward and self-explanatory, just remember to read the inline comments in the code snippet. There is a section to trigger an event, which is optional, you probably don’t need it in your own code.

For @ringcentral/sdk users

If you are existing user of the official JavaScript SDK @ringcentral/sdk and you’d like to stick to it (instead of switching to the RingCentral Extensible SDK), there is a solution for you:

import {SDK} from '@ringcentral/sdk';
import RingCentral from '@rc-ex/core';
import WebSocketExtension from '@rc-ex/ws';
import RcSdkExtension from '@rc-ex/rcsdk';

const sdk = new SDK({
  server: process.env.RINGCENTRAL_SERVER_URL,
  clientId: process.env.RINGCENTRAL_CLIENT_ID,
  clientSecret: process.env.RINGCENTRAL_CLIENT_SECRET,
});
const platform = sdk.platform();
const rc = new RingCentral();
const rcsdkExtension = new RcSdkExtension({rcSdk: sdk});
const wsExtension = new WebSocketExtension();

const main = async () => {
  await platform.login({
    username: process.env.RINGCENTRAL_USERNAME,
    extension: process.env.RINGCENTRAL_EXTENSION,
    password: process.env.RINGCENTRAL_PASSWORD,
  });

  // install the extensions
  await rc.installExtension(rcsdkExtension);
  await rc.installExtension(wsExtension);

  // subscribe
  await wsExtension.subscribe(
    ['/restapi/v1.0/account/~/extension/~/message-store'],
    evt => {
      console.log(JSON.stringify(evt, null, 2));
    }
  );

  // trigger an event, optional
  const r = await platform.get('/restapi/v1.0/account/~/extension/~');
  const ext = await r.json();
  platform.post('/restapi/v1.0/account/~/extension/~/company-pager', {
    from: {extensionId: ext.id},
    to: [{extensionId: ext.id}],
    text: 'Hello world!',
  });
};

main();

The code is very similar to the code we provided to new developers above. Please read the code explanation of previous section if you haven’t done so.

The different part is we are using @rc-ex/rcsdk to make @ringcentral/sdk an extension of the RingCentral Extensible SDK. You may continue to use @ringcentral/sdk in your projects. And the WebSocket Subscriptions is supported by @rc-ex/ws. @ringcentral/sdk and @rc-ex/ws could work toghether without issue.

For existing developers who don’t want to change their code

Let’s say you are already using both @ringcentral/sdk and @ringcentral/subscriptions and you really do not want to change your code. We have you covered!

@ringcentral/subscriptions is powered by WebSocket instead of PubNub since 5.0.0. And you just upgrade @ringcentral/subscriptions to latest version and no more coding change is required.

Please note that, @ringcentral/subscriptions is just a proxy library to @rc-ex/ws. Real work is done by @rc-ex/ws. You are recommended to use @rc-ex/ws instead.

Since you do not need to change your code, you probably do not need any sample code snippets. But here I provide one anyway:

import {SDK} from '@ringcentral/sdk';
import {Subscriptions} from '@ringcentral/subscriptions';

// init
const sdk = new SDK({
  server: process.env.RINGCENTRAL_SERVER_URL,
  clientId: process.env.RINGCENTRAL_CLIENT_ID,
  clientSecret: process.env.RINGCENTRAL_CLIENT_SECRET,
});
const platform = sdk.platform();
const subscriptions = new Subscriptions({
  sdk: sdk,
});

const main = async () => {
  // login
  await platform.login({
    username: process.env.RINGCENTRAL_USERNAME,
    extension: process.env.RINGCENTRAL_EXTENSION,
    password: process.env.RINGCENTRAL_PASSWORD,
  });

  // subscribe
  const subscription = subscriptions.createSubscription();
  subscription.on(subscription.events.notification, evt => {
    console.log(JSON.stringify(evt, null, 2));
  });
  await subscription
    .setEventFilters(['/restapi/v1.0/account/~/extension/~/message-store'])
    .register();

  // trigger an event, optional
  const r = await platform.get('/restapi/v1.0/account/~/extension/~');
  const ext = await r.json();
  platform.post('/restapi/v1.0/account/~/extension/~/company-pager', {
    from: {extensionId: ext.id},
    to: [{extensionId: ext.id}],
    text: 'Hello world!',
  });
};

main();

Sample output

We have provided 3 different solutions for different developers and use cases. No matter which solution you choose, the final result should be similar. If everything goes well, a notification message will be printed to console. Below is just a sample, what you get may be different:

{
  "uuid": "8790364716118035345",
  "event": "/restapi/v1.0/account/809646016/extension/62264425016/message-store",
  "timestamp": "2023-01-18T22:07:17.532Z",
  "subscriptionId": "2a4aafef-c9e0-4d9f-a34f-120ae5de8684",
  "ownerId": "62264425016",
  "body": {
    "accountId": 809646016,
    "extensionId": 62264425016,
    "lastUpdated": "2023-01-18T22:07:11.635Z",
    "changes": [
      {
        "type": "Pager",
        "newCount": 2,
        "updatedCount": 0,
        "newMessageIds": [
          1890265271016,
          1890265273016
        ]
      }
    ]
  }
}

RingCentral Chatbot Adaptive Cards

Tyler Liu — Fri, 16 Dec 2022 17:24:18 GMT

RingCentral Chatbot Adaptive Cards was released quite a while ago, but I just got some time to try it out recently. Today I am going to share my experience about RingCentral Adaptive Cards. The following topics will be covered: firstly, how to bootstrap a RingCentral Chatbot project; secondly, how to post an adaptive card; lastly, how to show a dialog.

How to bootstrap a RingCentral Chatbot project

Please follow this guide. If you want to deploy to AWS Lambda, follow this guide instead.

I don’t want to post the details here because those two guides mentioned above are very comprehensive and they should be sufficient for you to get started.

Basically you need to create a Node.js project, create a RingCentral app, do some configuration, setup the database and test the sample code provided. And by the end of the day you should have a working chatbot which responds with a “pong” whenever it received a “ping”:

And the business logic code is short and concise:

if (type === 'Message4Bot' && text === 'ping') {
    await bot.sendMessage(group.id, { text: 'pong' })
}

How to post an adaptive card

First of all, what is an adaptive card?

Adaptive Cards allow users to interact directly with messages to get more work done without leaving RingCentral team messaging.

RingCentral implements the Adaptive Card framework version 1.3. Originally developed by Microsoft, this open source framework aids developers with the design and development of richly formatted and interactive messages common to team chat and messaging services.

Posting an adaptive card is very similar to posting a plain text message:

await bot.sendAdaptiveCard(group.id, {
        type: 'AdaptiveCard',
        $schema: 'http://adaptivecards.io/schemas/adaptive-card.json',
        version: '1.3',
        body: [
          {
            type: 'ActionSet',
            actions: [
              {
                type: 'Action.Submit',
                title: 'Open dialog',
                data: {
                  path: 'open-dialog',
                },
              },
            ],
          },
        ],
      });

Our adaptive card is a simple one. It simply displays a button with text “Open Dialog”. Let’s move on to the next section.

How to show a dialog

Modal dialogs are windows that developers can cause to be opened and that float above a conversation. While a modal dialog is open, users cannot interact with any part of the team messaging interface. Dialogs can be forcibly closed by the end user, or be closed naturally following a successful interaction with a dialog’s contents.

Please note that, by design you cannot show a dialog by invoking REST API. Instead, you can respond to user’s submit action. A submit action is when user clicks a button on an adaptive card.

if (type === 'UserSubmit') {
    return {
      type: 'dialog',
      dialog: {
        title: 'Dialog',
        size: 'large',
        iconUrl:
          'https://www.kindpng.com/picc/m/255-2554719_a-generic-square-placeholder-image-with-rounded-corners.png',
        // iframeUrl: 'https://www.ringcentral.com',
        card: {
          type: 'AdaptiveCard',
          version: '1.3',
          $schema: 'http://adaptivecards.io/schemas/adaptive-card.json',
          body: [
            {
              type: 'TextBlock',
              text: 'Hello.',
              wrap: true,
              size: 'ExtraLarge',
              weight: 'Bolder',
            },
          ],
        },
      },
    };
  }

Source code

For a working demo, please refer to the full source code here.

Summary

In this article we covered some details about RingCentral Chatbot Adaptive Cards. By following the steps mentioned in this article, you should be able to create a RingCentral Chatbot and display adaptive cards and dialogs.

Host a RingCentral function on Microsoft Azure

Tyler Liu — Fri, 16 Dec 2022 17:22:15 GMT

Today we are going to do an interesting experiment: host a RingCentral function on Microsoft Azure. I use macOS as my development computer. For those who use Windows, the steps should be similar, but you’d have to reference some official documents of Azure.

Install the Azure CLI

brew update
brew install azure-cli

Install the Azure Functions Core Tools

brew tap azure/functions
brew install azure-functions-core-tools@3

Install .Net Core 3.1

Please download and install version 3.1. At the time that I am writing this article, 3.1 is the active LTS version.

Create a new Project

func init MyAwesomeProject --dotnet

Create a new function

func new --name RingCentralExample --template "HTTP trigger" --authlevel "anonymous"

Restore dependencies

dotnet restore

Run the function locally

fun start

Then visit http://localhost:7071/api/RingCentralExample?name=Tyler to test it. You should see something like this:

Install RingCentral.Net SDK

dotnet add package RingCentral.Net

Invoke RingCentral API

Update our function and make it look like below:

[FunctionName("RingCentralExample")]
public static async Task Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequest req,
    ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    var clientId = req.Query["clientId"];
    var clientSecret = req.Query["clientSecret"];
    var username = req.Query["username"];
    var extension = req.Query["extension"];
    var password = req.Query["password"];
    
    var rc = new RestClient(clientId, clientSecret, true);
    try {
        await rc.Authorize(username, extension, password);
        var extInfo = await rc.Restapi().Account().Extension().Get();
        return new OkObjectResult($"{DateTime.Now.ToString("yyyyMMdd HH:mm:ss ffff")}\n\nHello, {extInfo.contact.firstName} {extInfo.contact.lastName}.");
    } catch(RestException re) {
        return new OkObjectResult($"{DateTime.Now.ToString("yyyyMMdd HH:mm:ss ffff")}\n\n{Utils.FormatHttpMessage(re.httpResponseMessage, re.httpRequestMessage)}");
    }
}

We get 5 credential parameters from query string:

clientId
clientSecret
username
extension
password

And we use the credentials to do authorization and invoke RingCentral API:

var rc = new RestClient(clientId, clientSecret, true);
await rc.Authorize(username, extension, password);
var extInfo = await rc.Restapi().Account().Extension().Get();

RingCentral.Net SDK makes it very easy to use RingCentral API.

Then we return a greeting message to the current user:

return new OkObjectResult($"{DateTime.Now.ToString("yyyyMMdd HH:mm:ss ffff")}\n\nHello, {extInfo.contact.firstName} {extInfo.contact.lastName}.");

What if credentials are wrong? We handled the exception:

} catch(RestException re) {
    return new OkObjectResult($"{DateTime.Now.ToString("yyyyMMdd HH:mm:ss ffff")}\n\n{Utils.FormatHttpMessage(re.httpResponseMessage, re.httpRequestMessage)}");
}

Create remote resources

Create resource group:

az group create --name MyAwesomeProject-rg --location westus

Create storage acccount:

az storage account create --name myawesomeprojectsa --location westus --resource-group MyAwesomeProject-rg --sku Standard_LRS

Create function

az functionapp create --resource-group MyAwesomeProject-rg --consumption-plan-location westus --runtime dotnet --functions-version 3 --name my-awesome-project-rc-tyler-liu --storage-account myawesomeprojectsa

Publish the app

func azure functionapp publish my-awesome-project-rc-tyler-liu

Then you will be able to test your deployment by visiting https://my-awesome-project-rc-tyler-liu.azurewebsites.net/api/ringcentralexample?clientId=clientID&clientSecret=clientSecret&username=username&extension=extension&password=password

Of course you need to replace the query parameters with real credentials in order to get a greeting:

Clean up resources

Because we are just doing an experiment for learning purpose, it doesn’t make sense to keep the resources we created after the experiment is successful. Let’s do the clean up work.

It could be done by one command since all the resources are under the same resource group:

az group delete --name MyAwesomeProject-rg

Summary

That’s it for today’s tutorial. It’s basically a step by step tutorial teaching readers how to create and host a RingCentral application on Microsoft Azure. It’s pretty straightforward. I have the feeling that Azure is easier to get started with than AWS. In the future I may use more Azure.

Publish a Java library to mavenCentral using Gradle 7

Tyler Liu — Fri, 16 Dec 2022 17:21:07 GMT

This article is a sequel of Publish an Open Source Library to mavenCentral. In that article, we talked about how to publish an open source library to mavenCentral. As time goes, some of the content there becomes out-dated. Especially the way I shared in that article doesn’t work any more with latest Gradle 7.

What remain the same?

First of all, the same as last article, you need to have a Java library to publish, obviously. I have to say that most people have no library to publish. Because what they build are applications instead of libraries. But if you do have one, continue reading.

Secondly, you still need a public/secret key pair to publish a Java library. You need to create one if you don’t have one. The details are covered in article Publish an Open Source Library to mavenCentral.

Gradle 7 & maven-publish plugin

We will use Grade 7, the latest version of Gradle. Last time we were using Gradle 6. Please refer to Upgrading your build from Gradle 6.x to the latest. One notable breaking change is the maven plugin has been removed. You should use the maven-publish plugin instead.

So please change

plugins {
    ...
    id 'maven'
    ...
}

plugins {
    ...
    id 'maven-publish'
    ...
}

You also need to replace

uploadArchives {
  repositories {
    mavenDeployer {
      beforeDeployment { MavenDeployment deployment -> signing.signPom(deployment) }

repository(url: "https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/") {
        if (project.hasProperty('ossrhUsername')) {
            authentication(userName: ossrhUsername, password: ossrhPassword)
        }
      }

snapshotRepository(url: "https://s01.oss.sonatype.org/content/repositories/snapshots/") {
        if (project.hasProperty('ossrhUsername')) {
            authentication(userName: ossrhUsername, password: ossrhPassword)
        }
      }

pom.project {
        name 'RingCentral SDK'
        packaging 'jar'
        artifactId 'ringcentral'
        description 'RingCentral Java SDK'
        url 'https://github.com/ringcentral/ringcentral-java'
        licenses {
            license {
                name "MIT"
                url "https://opensource.org/licenses/MIT"
            }
        }
        developers {
            developer {
                id 'tylerliu'
                name 'Tyler Liu'
                email 'tyler.liu@ringcentral.com'
            }
        }
        scm {
            connection 'scm:git:git://git@github.com:ringcentral/ringcentral-java.git'
            developerConnection 'scm:git:ssh://git@github.com:ringcentral/ringcentral-java.git'
            url 'https://github.com/ringcentral/ringcentral-java'
        }
      }
    }
  }
}

with

publishing {
    publications {
        mavenJava(MavenPublication) {
            artifactId = 'ringcentral'
            from components.java
            versionMapping {
                usage('java-api') {
                    fromResolutionOf('runtimeClasspath')
                }
                usage('java-runtime') {
                    fromResolutionResult()
                }
            }
            pom {
                name = 'RingCentral SDK'
                description = 'RingCentral Java SDK'
                url = 'https://github.com/ringcentral/ringcentral-java'
                licenses {
                    license {
                        name = 'MIT'
                        url = 'https://opensource.org/licenses/MIT'
                    }
                }
                developers {
                    developer {
                        id = 'tylerliu'
                        name = 'Tyler Liu'
                        email = 'tyler.liu@ringcentral.com'
                    }
                }
                scm {
                    connection = 'scm:git:git://git@github.com:ringcentral/ringcentral-java.git'
                    developerConnection = 'scm:git:ssh://git@github.com:ringcentral/ringcentral-java.git'
                    url = 'https://github.com/ringcentral/ringcentral-java'
                }
            }
        }
    }
    repositories {
        maven {
            url = "https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/"
            credentials {
                username = ossrhUsername
                password = ossrhPassword
            }
        }
    }
}

Please note that, I am using the RingCentral Java SDK library as example. Please adjust the configuration based on your library’s details.

Code Signing

Code sign part is also quite different from before. Previously, we have the following configuration for code signing:

task javadocJar(type: Jar) {
    classifier = 'javadoc'
    from javadoc
}
task sourcesJar(type: Jar) {
    classifier = 'sources'
    from sourceSets.main.allSource
}
artifacts {
    archives javadocJar, sourcesJar
}
signing {
    sign configurations.archives
}

Now it needs to be updated to:

signing {
    sign publishing.publications.mavenJava
}

It is way simpler, I have to say. So Gradle 7 does have some improvements compared to Gradle 6.

Command to publish

Previously, we use a customized command named ./gradlew uploadArchives , now we use the built-in command ./gradlew publish .

Summary

OK, that concludes this article. It’s not a brand new article. It’s a sequel of Publish an Open Source Library to mavenCentral. It is for those who wants to stay update-to-date with the latest Gradle tool.