lincuss / nexmo-dotnet

Nexmo REST API client for .NET, ASP.NET, ASP.NET MVC written in C#. API support for SMS, Voice, Text-to-Speech, Numbers, Verify (2FA) and more.

Nexmo Client Library for C#/.NET

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

• Installation
• Configuration
• Examples
• Coverage
• Contributing

Installation:

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

To install the C# client library using NuGet:

• Run the following command in the Package Manager Console:

    Install-Package Nexmo.Csharp.Client

Alternatively:

• Download or build (see developer instructions) the Nexmo.Api.dll.
• If you have downloaded a release, ensure you are referencing the required dependencies by either including them with your project's NuGet dependencies or manually referencing them.
• Reference the assembly in your code.

Targeted frameworks:

• 4.5.2
• 4.6, 4.6.1, 4.6.2
• .NET Standard 1.6, 2.0
• ASP.NET Core 2.0

Configuration:

• Create a Nexmo Client instance and pass in credentials in the constructor

var client = new Client(creds: new Nexmo.Api.Request.Credentials
                {
                    ApiKey = "NEXMO-API-KEY",
                    ApiSecret = "NEXMO-API-SECRET"
                });

var results = client.SMS.Send(request: new SMS.SMSRequest
                {
 
                    from = NEXMO_NUMBER,
                    to = TO_NUMBER,
                    text = "Hello, I'm an SMS sent to you using Nexmo"
                });

Alternatively:

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

{
  "appSettings": {
    "Nexmo.UserAgent": "myApp/1.0",
    "Nexmo.Url.Rest": "https://rest.nexmo.com",
    "Nexmo.Url.Api": "https://api.nexmo.com",
    "Nexmo.api_key": "NEXMO-API-KEY",
    "Nexmo.api_secret": "NEXMO-API-SECRET",
    
    "Nexmo.Application.Id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "Nexmo.Application.Key": "c:\\path\\to\\your\\application\\private.key"
  }
}

• In the event multiple configuration files are found, the order of precedence is as follows:

  • appsettings.json which overrides
  • settings.json

Configuration Reference

Key	Description
Nexmo.api_key	Your API key from the dashboard
Nexmo.api_secret	Your API secret from the dashboard
Nexmo.Application.Id	Your application ID
Nexmo.Application.Key	Path to your application key
Nexmo.Url.Rest	Optional. Nexmo REST API base URL. Defaults to https://rest.nexmo.com
Nexmo.Url.Api	Optional. Nexmo API base URL. Defaults to https://api.nexmo.com
Nexmo.Api.RequestsPerSecond	Optional. Throttle to specified requests per second.
Nexmo.Api.EnsureSuccessStatusCode	Optional. Defaults to false. If true, EnsureSuccessStatusCode will be called against each response. If the response has a failure HTTP status code, a HttpRequestException will be thrown.
Nexmo.UserAgent	Optional. Your app-specific usage identifier in the format of name/version. Example: "myApp/1.0"

Logging

3.1.x+

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 Nexmo.Api.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 Nexmo.Api.Client(new Credentials("example", "password"));
client.Account.GetBalance();
Log.Logger.Debug("end");

2.2.0 - 3.0.x

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

Note that logging Nexmo.Api 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",
    "Nexmo.Api": "Debug",
    "Nexmo.Api.Authentication": "Error",
    "Nexmo.Api.Configuration": "Error"
  }
}

You may specify other types of logging (file, etc.). The Nexmo.Samples.Coverage project contains an example that logs to a file with the assistance of Serilog.Extensions.Logging.File.

Examples

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

Sending a Message

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

var client = new Client(creds: new Nexmo.Api.Request.Credentials
            {
                  ApiKey = "NEXMO_API_KEY",
                  ApiSecret = "NEXMO_API_SECRET"
            });

var results = client.SMS.Send(new SMS.SMSRequest
{
    from = NEXMO_NUMBER,
    to = TO_NUMBER,
    text = "this is a test"
});

Receiving a Message

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

public ActionResult Get([FromUri]SMS.SMSInbound response)
{
    return new HttpStatusCodeResult(HttpStatusCode.OK);
}

Receiving a Message Delivery Receipt

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

public ActionResult DLR([FromUri]SMS.SMSDeliveryReceipt response)
{
    Debug.WriteLine("-------------------------------------------------------------------------");
    Debug.WriteLine("DELIVERY RECEIPT");
    Debug.WriteLine("Message ID: " + response.messageId);
    Debug.WriteLine("From: " + response.msisdn);
    Debug.WriteLine("To: " + response.to);
    Debug.WriteLine("Status: " + response.status);
    Debug.WriteLine("-------------------------------------------------------------------------");

    return new HttpStatusCodeResult(HttpStatusCode.OK);
}

NOTE: [FromUri] is deprecated in .NET Core; [FromQuery] works in this case.

Redacting a message

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

var client = new Client(creds: new Nexmo.Api.Request.Credentials
            {
                  ApiKey = "NEXMO_API_KEY",
                  ApiSecret = "NEXMO_API_SECRET"
            });

client.Redact.RedactTransaction(new Redact.RedactRequest(MESSAGE_ID, "sms", "outbound"));

Initiating a Call

Use Nexmo'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 Nexmo.Api.Application or Nexmo's Node.js-based CLI tool to register. See the Application API documentation for details.

var client = new Client(creds: new Nexmo.Api.Request.Credentials
            {
                ApiKey = "NEXMO_API_KEY",
                ApiSecret = "NEXMO_API_SECRET",
                ApplicationId = "NEXMO_APPLICATION_ID",
                ApplicationKey = "NEXMO_APPLICATION_PRIVATE_KEY"
            }

using Nexmo.Api.Voice;

client.Call.Do(new Call.CallCommand
{
    to = new[]
    {
        new Call.Endpoint {
            type = "phone",
            number = TO_NUMBER
        }
    },
    from = new Call.Endpoint
    {
        type = "phone",
        number = NEXMO_NUMBER
    },
    answer_url = new[]
    {
        "https://nexmo-community.github.io/ncco-examples/first_call_talk.json"
    }
});

Receiving a Call

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

var client = new Client(creds: new Nexmo.Api.Request.Credentials
            {
                ApiKey = "NEXMO_API_KEY",
                ApiSecret = "NEXMO_API_SECRET",
                ApplicationId = "NEXMO_APPLICATION_ID",
                ApplicationKey = "NEXMO_APPLICATION_PRIVATE_KEY"
            }

using Nexmo.Api.Voice;

public ActionResult GetCall(string id)
{
    var call = client.Call.Get(id);
    // Do something with call.
}

Sending 2FA Code

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

var client = new Client(creds: new Nexmo.Api.Request.Credentials
            {
                ApiKey = "NEXMO_API_KEY",
                ApiSecret = "NEXMO_API_SECRET"
            }

public ActionResult Start(string to)
{
    var start = client.NumberVerify.Verify(new NumberVerify.VerifyRequest
    {
        number = to,
        brand = "NexmoQS"
    });
    Session["requestID"] = start.request_id;

    return View();
}

Checking 2FA Code

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

var client = new Client(creds: new Nexmo.Api.Request.Credentials
            {
                ApiKey = "NEXMO_API_KEY",
                ApiSecret = "NEXMO_API_SECRET"
            }

public ActionResult Check(string code)
{
    var result = client.NumberVerify.Check(new NumberVerify.CheckRequest
    {
        request_id = Session["requestID"].ToString(),
        code = code
    });
   
    if (result.status == "0")
    {
        ViewBag.Message = "Verification Sucessful";
    }
    else
    {
        ViewBag.Message = result.error_text;
    }
    return View();
}

Additional Examples

• 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.

API Coverage

• Account
  • Balance
  • Pricing
  • Settings
  • Top Up
  • Numbers
    • Search
    • Buy
    • Cancel
    • Update
• Number Insight
  • Basic
  • Standard
  • Advanced
  • Webhook Notification
• Verify
  • Verify
  • Check
  • Search
  • Control
• Search
  • Message
  • Messages
  • Rejections
• Messaging
  • Send
  • Delivery Receipt
  • Inbound Messages
  • Search
    • Message
    • Messages
    • Rejections
  • US Short Codes
    • Two-Factor Authentication
    • Event Based Alerts
      • Sending Alerts
      • Campaign Subscription Management
• Application
  • Create
  • List
  • Update
  • Delete
• Call
  • Outbound
  • Get
  • List
  • Edit
  • TTS
  • Stream
  • DTMF

Contributing

Visual Studio 2017 is required (Community is fine). v15.5+ is recommended.

1. Get the latest code either by cloning the repository or downloading a snapshot of the source.
2. Open "Nexmo.Api.sln"
3. Build! NuGet dependencies should be brought down automatically; check your settings if they are not.

Pull requests are welcome!

Thanks

Special thanks to our contributors:

• jdpearce
• jonferreira

License

This library is released under the MIT License.