You can use this C# client library to integrate Vonage's APIs to your application. To use this, you'll need a Vonage API account. Sign up for free at vonage.com.

• Installation
  • Migration guides
    • Upgrading 5.x => 6.x
  • Targeted frameworks
  • Tested frameworks
• Configuration
  • Setup
    • Provide credentials
    • Set credentials in settings file
    • Override values on Configuration singleton
  • Configuration reference
  • Test configuration
  • Logging
    • v5.0.0+
    • 3.1.x, 5.0.0
    • 2.2.0, 3.0.x
• Examples
• Supported APIs
• FAQ
• Contributing
• Thanks
• Licence

To use the client library you'll need to have created a Vonage account.

To install the C# client library using NuGet:

• Run the following command from your terminal in your projects directory:

dotnet add package Vonage

OR

• Run the following command in the Package Manager Console:

Install-Package Vonage

If you would prefer to run directly from source:

• Clone this repository git clone https://github.com/vonage/vonage-dotnet-sdk
• Add the Vonage/Vonage.csproj file to your .sln file
• Add the Vonage/Vonage.csproj file as a project dependency of you project e.g.

<ItemGroup>
    <ProjectReference Include="..\Vonage\Vonage.csproj" />
</ItemGroup>

Changes in version 6.x

• Enum values are now caplitalised in alignment with accepted coding practices and are Pascal Case
• All classes that were marked as deprecated in 5.x are now removed
• Ncco now inherits from List, it no longer has the Actions property, to add an action use ncco.Add(action);
• Strings with values "true" or "false" are now represented as bool in code

The SDK targets towards netstandard2.0. It is compatible with every supported version.

We test the SDK against every supported version of the framework. Therefore, we ensure complete compatibility no matter the version you are using.

• .NET Framework 4.6.2
• .NET Framework 4.7.0
• .NET Framework 4.7.1
• .NET Framework 4.7.2
• .NET Framework 4.8.0
• .NET 6.0
• .NET 6.0-Windows

To setup the configuration of the Vonage Client you can do one of the following.

Create a Vonage Client instance and pass in credentials in the constructor - this will only affect the security credentials (Api Key, Api Secret, Signing Secret, Signing Method Private Key, App Id)

var credentials = Credentials.FromApiKeyAndSecret(
    VONAGE_API_KEY,
    VONAGE_API_SECRET
    );

var vonageClient = new VonageClient(credentials);

Provide the vonage URLs, API key, secret, and application credentials (for JWT) in appsettings.json:

{
  "appSettings": {
    "Vonage.UserAgent": "myApp/1.0",
    "Vonage.Url.Rest": "https://rest.nexmo.com",
    "Vonage.Url.Api": "https://api.nexmo.com",
    "Vonage.Meetings.Url.Api": "https://api-eu.vonage.com",
    "Vonage.Video.Url.Api": "https://video.api.vonage.com",
    "Vonage_key": "VONAGE-API-KEY",
    "Vonage_secret": "VONAGE-API-SECRET",    
    "Vonage.Application.Id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "Vonage.Application.Key": "VONAGE_APPLICATION_PRIVATE_KEY"
  }
}

Note: In the event multiple configuration files are found, the order of precedence is as follows: appsettings.json which overrides settings.json

Access the Configuration instance and set the appropriate key in your code for example:

Configuration.Instance.Settings["appSettings:Vonage.Url.Api"] = "https://www.example.com/api";
Configuration.Instance.Settings["appSettings:Vonage.Url.Rest"] = "https://www.example.com/rest";
Configuration.Instance.Settings["appSettings:Vonage.Meetings.Url.Api"] = "https://www.meetings.example.com/api";
Configuration.Instance.Settings["appSettings:Vonage.Video.Url.Rest"] = "https://www.video.example.com/rest";

NOTE: Private Key is the literal key - not a path to the file containing the key

Make sure to set Vonage.Test.RsaPrivateKey (with a RSA Private Key) in your environment variables. Some tests rely on that to verify a token can be created.

For security reasons, not RSA Private Key is hardcoded in the repository.

The Library uses Microsoft.Extensions.Logging to preform all of it's logging tasks. To configure logging for you app simply create a new ILoggerFactory and call the LogProvider.SetLogFactory() method to tell the Vonage library how to log. For example, to log to the console with serilog you can do the following:

using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Configuration;
using Vonage.Logger;
using Serilog;

var log = new LoggerConfiguration()
    .MinimumLevel.Debug()
    .WriteTo.Console(outputTemplate: "{Timestamp:HH:mm} [{Level}]: {Message}\n")
    .CreateLogger();
var factory = new LoggerFactory();
factory.AddSerilog(log);
LogProvider.SetLogFactory(factory);

The library makes use of LibLog to facilitate logging.

Your application controls if and how logging occurs. Example using Serilog and Serilog.Sinks.Console v3.x:

using Vonage.Request;
using Serilog;

// set up logging at startup
var log = new LoggerConfiguration()
  .MinimumLevel.Debug()
  .WriteTo.Console(outputTemplate: "{Timestamp:HH:mm} [{Level}] ({Name:l}) {Message}")
  .CreateLogger();
Log.Logger = log;

Log.Logger.Debug("start");
var client = new Vonage.VonageClient(new Credentials("example", "password"));
client.Account.GetBalance();
Log.Logger.Debug("end");

You can request console logging by placing a logging.json file alongside your appsettings.json configuration.

Note that logging Vonage messages will very likely expose your key and secret to the console as they can be part of the query string.

Example logging.json contents that would log all requests as well as major configuration and authentication errors:

{
  "IncludeScopes": "true",
  "LogLevel": {
    "Default": "Debug",
    "Vonage": "Debug",
    "Vonage.Authentication": "Error",
    "Vonage.Configuration": "Error"
  }
}

You may specify other types of logging (file, etc.).

We are working on a separate repository for .NET examples. Check it out here!

The following examples show how to:

• Send a message
• Receive a message
• Receive a message delivery receipt
• Redact a message
• Initiate a call
• Receive a call
• Send 2FA code
• Check 2FA code

Use Vonage's SMS API to send an SMS message.

var credentials = Credentials.FromApiKeyAndSecret(
    VONAGE_API_KEY,
    VONAGE_API_SECRET
    );

var vonageClient = new VonageClient(credentials);

var response = await vonageClient.SmsClient.SendAnSmsAsync(new Vonage.Messaging.SendSmsRequest()
{
    To = TO_NUMBER,
    From = VONAGE_BRAND_NAME,
    Text = "A text message sent using the Vonage SMS API"
});

Use Vonage's SMS API to receive an SMS message. Assumes your Vonage webhook endpoint is configured.

The best method for receiving an SMS will vary depending on whether you configure your webhooks to be GET or POST. Will Also Vary between ASP.NET MVC and ASP.NET MVC Core.

[HttpGet("webhooks/inbound-sms")]
public async Task<IActionResult> InboundSmsGet()
{
    var inbound = Vonage.Utility.WebhookParser.ParseQuery<InboundSms>(Request.Query);
    return NoContent();
}

[HttpPost("webhooks/inbound-sms")]
public async Task<IActionResult> InboundSms()
{
    var inbound = await Vonage.Utility.WebhookParser.ParseWebhookAsync<InboundSms>(Request.Body, Request.ContentType);
    return NoContent();
}

[HttpGet]
[Route("webhooks/inbound-sms")]
public async Task<HttpResponseMessage> GetInbound()
{
    var inboundSms = WebhookParser.ParseQueryNameValuePairs<InboundSms>(Request.GetQueryNameValuePairs());
    return new HttpResponseMessage(HttpStatusCode.NoContent);
}

[HttpPost]
[Route("webhooks/inbound-sms")]
public async Task<HttpResponseMessage> PostInbound()
{
    var inboundSms = WebhookParser.ParseWebhook<InboundSms>(Request);
    return new HttpResponseMessage(HttpStatusCode.NoContent);
}

Use Vonage's SMS API to receive an SMS delivery receipt. Assumes your Vonage webhook endpoint is configured.

The best method for receiving an SMS will vary depending on whether you configure your webhooks to be GET or POST. Will Also Vary between ASP.NET MVC and ASP.NET MVC Core.

[HttpGet("webhooks/dlr")]
public async Task<IActionResult> InboundSmsGet()
{
    var dlr = Vonage.Utility.WebhookParser.ParseQuery<DeliveryReceipt>(Request.Query);
    return NoContent();
}

[HttpPost("webhooks/dlr")]
public async Task<IActionResult> InboundSms()
{
    var dlr = await Vonage.Utility.WebhookParser.ParseWebhookAsync<DeliveryReceipt>(Request.Body, Request.ContentType);
    return NoContent();
}

[HttpGet]
[Route("webhooks/dlr")]
public async Task<HttpResponseMessage> GetInbound()
{
    var dlr = WebhookParser.ParseQueryNameValuePairs<DeliveryReceipt>(Request.GetQueryNameValuePairs());
    return new HttpResponseMessage(HttpStatusCode.NoContent);
}

[HttpPost]
[Route("webhooks/dlr")]
public async Task<HttpResponseMessage> PostInbound()
{
    var dlr = WebhookParser.ParseWebhook<DeliveryReceipt>(Request);
    return new HttpResponseMessage(HttpStatusCode.NoContent);
}

Use Vonage's Redact API to redact a SMS message.

var credentials = Credentials.FromApiKeyAndSecret(VONAGE_API_KEY, VONAGE_API_SECRET);
var client = new VonageClient(credentials);
var request = new RedactRequest() { Id = VONAGE_REDACT_ID, Type = VONAGE_REDACT_TYPE, Product = VONAGE_REDACT_PRODUCT };
var response = await client.RedactClient.RedactAsync(request);

Use Vonage's Voice API to initiate a voice call.

NOTE: You must have a valid Application ID and private key in order to make voice calls. Use either Vonage.Application or Vonage's Node.js-based CLI tool to register. See the Application API documentation for details.

var creds = Credentials.FromAppIdAndPrivateKeyPath(VONAGE_APPLICATION_ID, VONAGE_PRIVATE_KEY_PATH);
var client = new VonageClient(creds);

var command = new CallCommand() { To = new Endpoint[] { toEndpoint }, From = fromEndpoint, AnswerUrl=new[] { ANSWER_URL}};
var response = await client.VoiceClient.CreateCallAsync(command);

Use Vonage's Voice API to receive a voice call.

[HttpGet("webhooks/answer")]
public string Answer()
{
    var talkAction = new TalkAction()
    {
        Text = $"Thank you for calling from " +
        $"{string.Join(" ", Request.Query["from"].ToString().ToCharArray())}"
    };
    var ncco = new Ncco(talkAction);
    return ncco.ToString();
}

var credentials = Credentials.FromAppIdAndPrivateKeyPath(VONAGE_APPLICATION_ID, VONAGE_PRIVATE_KEY_PATH);
var client = new VonageClient(credentials);

var response = await client.VoiceClient.GetCallAsync(UUID);

Use Vonage's Verify API to send 2FA pin code.

var credentials = Credentials.FromApiKeyAndSecret(VONAGE_API_KEY, VONAGE_API_SECRET);
var client = new VonageClient(credentials);

var request = new VerifyRequest() { Brand = BRAND_NAME, Number = RECIPIENT_NUMBER };
var response = await client.VerifyClient.VerifyRequestAsync(request);

Use Vonage's Verify API to check 2FA pin code.

var credentials = Credentials.FromApiKeyAndSecret(VONAGE_API_KEY, VONAGE_API_SECRET);
var client = new VonageClient(credentials);

var request = new VerifyCheckRequest() { Code = CODE, RequestId = REQUEST_ID };
var response = await client.VerifyClient.VerifyCheckAsync(request);

• Check out the sample MVC application and tests for more examples. Make sure to copy appsettings.json.example to appsettings.json and enter your key/secret.

The following is a list of Vonage APIs and whether the Vonage .NET SDK provides support for them:

Q: Does the .NET SDK Support the async pattern? A: Yes. All methods either support asynchronous behaviours by default or provide specific behaviours for each sync/async option.

Pick your preferred IDE:

• Visual Studio (Community is fine)
• Visual Studio Code
• Jetbrains Rider

Keep in mind the SDK is built on netstandard2.0 and tested against several framework versions (v4.6.2 & upper, and .Net6.0). Therefore, they should be installed on your machine to guarantee compatibility with all supported framework versions.

1. Get the latest code either by cloning the repository or downloading a snapshot of the source.
2. Open "Vonage.sln"
3. Build! NuGet dependencies should be brought down automatically; check your settings if they are not.
4. Tests! Run all the tests to verify everything's fine.

Pull requests are welcome!

This library is released under the MIT License.