ringcentral-csharp-client
RingCentral.Net
RingCentral.Net is the successor of this project. All users are recommended to use RingCentral.Net instead.
Reference
- RingCentral.Net on NuGet
- Article: Announcing the New RingCentral SDK for .NET
- Article: RingCentral SDK for .NET Upgrade Guide
RingCentral Developers is a cloud communications platform which can be accessed via more than 70 APIs. The platform's main capabilities include technologies that enable: Voice, SMS/MMS, Fax, Glip Team Messaging, Data and Configurations.
API Reference and APIs Explorer.
RingCentral C# client.
Notice: any issues or questions, please do let me know by creating an issue.
Feel free to
Video tutorial
Setup project, authorization and sending fax
Deprecated: Work with .NET 4.5 & WebForm You should not use legacy .NET versions. But if you have to, please watch the video.
Installation
Install-Package RingCentral.Client
API Reference
RingCentral API Reference is where you can find all the endpoints, requests, parameters and all kinds of necessary details.
Please note: as a guest reader, you can only read the basic version of API Reference. Please do login if you want to get information about Advanced API endpoints.
Initialization
using RingCentral;
rc = new RestClient("clientId", "clientSecret");
By default the clients talk to sandbox server. If you want production server:
rc = new RestClient("clientId", "clientSecret", true);
Or you can specify the server url explicitly:
rc = new RestClient("clientId", "clientSecret", "https://platform.devtest.ringcentral.com");
Authorization
await rc.Authorize("username", "extension", "password");
If you use direct number as username, leave extension empty.
Auto refresh
By default, there is a background timer calling rc.Refresh()
periodically, so the authorization never expires.
But if you would like to call Refresh
manually:
rc.AutoRefreshToken = false;
Token Revoke
When you no longer need a token, don't forget to revoke it: rc.Revoke()
.
Map URI to code
This client library is built around URIs. Please read this part carefully and make sure you get it before continuing.
Let's go to the RingCentral API Reference to find an example.
We can see that the URI pattern is:
/restapi/v1.0/account/{accountId}/extension/{extensionId}/call-log/{callRecordId}
An real example of the URI could be:
/restapi/v1.0/account/~/extension/130829004/call-log/ASsQ3xLOZfrLBwM
Let's map the URI above to code:
rc.Restapi("v1.0").Account("~").Extension("130829004").CallLog("ASsQ3xLOZfrLBwM");
It's just a one-to-one mapping:
Default ID
The default ID for Restapi
is v1.0
, the default ID for Account
and Extension
is ~
.
We can omit arguments to use default value:
rc.Restapi().Account().Extension("130829004").CallLog("ASsQ3xLOZfrLBwM");
You can also break it into multiple lines if you don't like long-chained method calls:
var account = rc.Restapi().Account();
var extension = account.Extension("130829004");
var callLog = extension.CallLog("ASsQ3xLOZfrLBwM");
Anonymous types vs Pre-defined types
For example, the following line is for sending fax:
var response = await extension.Fax().Post(requestBody, attachments);
To create the requestBody
object, you can define it as following:
var requestBody = new FaxPath.PostParameters
{
to = new CallerInfo[] { new CallerInfo { phoneNumber = "123456789" } }
}
Or, you can define it using anonymous types:
var requestBody = new
{
to = new object[] { new { phoneNumber = "123456789" } }
}
Both are OK. The anonymous types approach is shorter while you can take advantages of IDE intellisense with pre-defined types approach. You can choose based on your preferences.
Talk to API Server
var extension = rc.Restapi().Account().Extension();
GET
List all of the inbound call Logs
var callLogs = await extension.CallLog().List(new { direction = "Inbound" });
Or if you prefer the query parameters as a typed model:
var callLogs = await extension.CallLog().List(new CallLog.ListParameters { direction = "Inbound" });
All the HTTP calls are by default async, so you should use the await
keyword of C#.
Get a call log by ID
var callLog = await extension.CallLog("ASsQ3xLOZfrLBwM").Get();
You can inspect the attributes of the returned callLog
object because it is a model instead of a string:
Console.WriteLine(callLog.id);
Console.WriteLine(callLog.direction);
Console.WriteLine(callLog.startTime);
POST
Send an SMS
var requestBody = new {
text = "hello world",
from = new { phoneNumber = phoneNumber },
to = new object[] { new { phoneNumber = phoneNumber } }
};
var response = await extension.Sms().Post(requestBody);
PUT
Update message status
var requestBody = new { readStatus = "Read" };
var response = await extension.MessageStore(messageId).Put(requestBody);
DELETE
Delete message by ID
var response = await extension.MessageStore(messageId).Delete();
What if I want plain HTTP without those fancy models?
var endpoint = rc.Restapi().Dictionary().Timezone("6").Endpoint(); // "/restapi/v1.0/dictionary/timezone/6"
var response = await rc.Get(endpoint); // make http request
var statusCode = response.StatusCode; // check status code
var str = await response.Content.ReadAsStringAsync(); // get response string
Subscription
The subscription will renew itself automatically before it expires. In rare cases you might need to renew it manually:
await subscription.Renew();
Send Fax
Send MMS
MMS and SMS share the same API endpoint. You can deem MMS as SMS with attachments
Binary data
Create/Update profile image
Get message content
Download call recording
Exception handling
try
{
await ...
}
catch (FlurlHttpException fhe)
{
string errorMessage = fhe.GetResponseString();
Console.WriteLine(errorMessage);
if (fhe.Call.Response.StatusCode == System.Net.HttpStatusCode.NotFound)
{
Console.WriteLine("The resource doesn't exist");
}
}
Events
RestClient
class has EventHandlerTokenRefreshed
, so that every time token refreshed you can get a notificationRestClient
class has EventHandlerAfterHttpCall
, so that after every HTTP call you can a notification
Sample code
The unit test project contains lots of useful code snippets. Such as this test class.
License
MIT
Common issues
You must add a reference to assembly netstandard
Ref: dotnet/standard#542