# Integration of Nexmo SMS and Verify API using C# for AuctionWorx
**by:** Shruti Sawant     **in:**  [Programming](https://www.systenics.com/blogs/category/programming)     **tags:**  [*AuctionWorx*](https://www.systenics.com/blogs/tag/auctionworx) ,  [*C#*](https://www.systenics.com/blogs/tag/c-sharp) ,  [*ASP.NET MVC*](https://www.systenics.com/blogs/tag/aspnet-mvc)
## Introduction

This tutorial explains how to use Nexmo SMS and Verify API to add
additional functionality into AuctionWorx MVC application. Nexmo SMS API
is used to send and receive a high volume of SMS anywhere in the world.
There are many APIs Nexmo provides and in this article I am going to
explain two APIs - SMS and Verify.

For teams planning SMS notifications, buyer verification, or other
custom AuctionWorx workflows, our
[AuctionWorx development and customization services](https://www.systenics.com/auctionworx-development-and-customization/) cover implementation, testing, and platform-specific integration work.

Nexmo even provides an official [Nexmo Client Library for C#/.NET](https://github.com/Nexmo/nexmo-dotnet) for .Net Framework 4.5.2 and above which will allow you to integrate their
API calls with your C# application. But in our case, we had an older version
of AuctionWorx MVC application which was running on .Net Framework 4.5.1 and
hence we decided to write our own code to call their APIs. Refer [this link](https://github.com/Nexmo/nexmo-dotnet/issues/3) to know more about .Net Framework issue on Nexmo GitHub.

## Pre-requisites

1. Mobile or landline phone number (mobile preferred to receive SMS).

2. [Nexmo Test Account](https://dashboard.nexmo.com/sign-up) - you can create a test account using your mobile or landline phone number
and Nexmo provides free credit which is enough to get started to learn how
to use their APIs in your application.

3. Visual Studio (C#)

## Nexmo SMS API

1. It is used to send SMS to given number. Using this API, you can send
any customize text message. It follows below scenario.

2. Create Request: Send a request to Nexmo to send SMS to user.

3. Get Response: Gives response to ensure that SMS request you sent is
successful.

### SMS API Request

This is rest API. For e.g.
https://rest.nexmo.com/sms/json?api_key=xxxxxxxx&api_secret=xxxxxxxx&to=ToNumber&from=FromNumber&text=hello+test+message

Where,

a. https://rest.nexmo.com/sms is Base URL. All the request to the SMS API
must use this URL. Your base URL becomes either: json / XML (https://rest.nexmo.com/sms/json
or https://rest.nexmo.com/sms/xml)

b. **api_key** and **api_secret**: Nexmo
provides this "api_key" and "api_secret" from [Nexmo Dashboard](https://dashboard.nexmo.com/sign-in)

c. **to**: A single phone number in international format.
You can set one recipient only for each request.

d. **from**: A single phone/mobile number with country code
from which SMS is going to be sent.

e. **text**: The SMS body. Messages where "type" is "text"
(the default) are in UTF-8 with URL encoding.

Let's start with the coding :)

1. Create 2 model classes - SmsResponse and Message.

```
public class SmsResponse
{
public string MessageCount { get; set; }
public List Messages { get; set; }
}

public class Message
{
public string To { get; set; }
public string MessageId { get; set; }
public string Status { get; set; }
public string RemainingBalance { get; set; }
public string MessagePrice { get; set; }
public string Network { get; set; }
public string From { get; set; }
}

```

2. Create class "SMS" and create a method "SendSms" of return type
"SmsResponse" and pass "to" number and "type=text" string as a
parameter.

3. Now to send request to Nexmo SMS API, use following code:

```
string uri = string.Format("{0}/sms/json?from={1}&to={2}&text={3}&api_key={4}&api_secret={5}&type={6}",
ConfigurationManager.AppSettings["Nexmo.Url.Rest"],
HttpUtility.UrlEncode(ConfigurationManager.AppSettings["Nexmo.from_number"]),
HttpUtility.UrlEncode(toNumber),
HttpUtility.UrlEncode(text),
HttpUtility.UrlEncode(ConfigurationManager.AppSettings["Nexmo.api_key"]),
HttpUtility.UrlEncode(ConfigurationManager.AppSettings["Nexmo.api_secret"]),
type);
var json = new WebClient().DownloadString(uri);

```

Here you have to add "api_key" and "api_secret" as I mentioned above. I
have added this key-value pair in web.config file as shown below.

```
<appSettings>
<!-- START - Nexmo SMS API settings -->
<add key="Nexmo.Url.Rest" value="https://rest.nexmo.com" />
<add key="Nexmo.Url.Api" value="https://api.nexmo.com" />
<add key="Nexmo.api_key" value="your api key goes here" />
<add key="Nexmo.api_secret" value="your api_secret key goes here" />
<add key="Nexmo.from_number" value="country_code+ from_number goes here" />
<!-- END - Nexmo SMS API settings -->
</appSettings>

```

4. To get the SMS API response:

```
SmsResponse result = JsonConvert.DeserializeObject(json);

```

### SMS API Response

Each request you make using the SMS API returns a response - the
"status" and "price" of your request to Nexmo in JSON or XML format.
Each response comes in specific format with key and value pair.

```
{
"message-count": "1",
"messages": [
{
"status": "returnCode",
"message-id": "messageId",
"to": "to",
"client-ref": "client-ref",
"remaining-balance": "remaining-balance",
"message-price": "message-price",
"network": "network",
"error-text": "error-message"
}
]
}

```

[Refer this link](https://docs.nexmo.com/messaging/sms-api/api-reference#keys) for detail information. I have attached the output of the SMS API below.

Figure 1: Output for SMS API Sample

## Nexmo Verify API

Nexmo Verify API is used to send a PIN by SMS or Text-To-Speech in order
to prove that a user can be contacted on a specific phone number.

By default, the Nexmo Verify API sends PIN (OTP) by an SMS. Due to some
reason if there is no reply, it sends PIN by TTS. The reason can be the
receiver number user is providing might be a landline number.

This can be used to verify that a phone number is valid, reachable and
accessible by that user.

### Verify API Request

A Verify API request looks like:
https://api.nexmo.com/verify/json?api_key=xxxxxxxx&api_secret=xxxxxxxx&number=xxxxxxxxxxxx&brand=MyApp

Where,

a. https://api.nexmo.com/verify is Base URL. All the request to the SMS API
must use this URL. Your base URL becomes either: json / XML (https://api.nexmo.com/verify/json
or https://api.nexmo.com/verify/xml)

b. **api_key** and **api_secret**: Nexmo
provides this "api_key" and "api_secret" from [Nexmo Dashboard](https://dashboard.nexmo.com/sign-in)

c. **to**: A single phone number in international format.
You can set one recipient only for each request.

d. **number**: A single phone/mobile number with country
code to which PIN is going to be sent.

e. **brand**: The name of the company or application for
which you are using Verify API. For example: "Your brand PIN is ...".
For more details, [click here](https://docs.nexmo.com/verify/api-reference/api-reference#vrequest).

1. Create 2 model classes - JsonResponse and JsonVerifyCheckResponse.

```
public class JsonResponse
{
public string RequestId { get; set; }
public int Status { get; set; }
}

public class JsonVerifyCheckResponse
{
public string EventId { get; set; }
public int Status { get; set; }
public decimal Price { get; set; }
public string Currency { get; set; }
public string Error { get; set; }
public string RequestId { get; set; }
}

```

2. Create another class "CallTTS" and add method into it named
"SendSMSOrCall" with return type "JsonResponse"

3. Now to send request to Verify API, add following line:

```
string uri = string.Format("{0}/verify/json?api_key={1}&api_secret={2}&number={3}&brand={4}",
ConfigurationManager.AppSettings["Nexmo.Url.Api"],
HttpUtility.UrlEncode(ConfigurationManager.AppSettings["Nexmo.api_key"]),
HttpUtility.UrlEncode(ConfigurationManager.AppSettings["Nexmo.api_secret"]),
HttpUtility.UrlEncode(toNumber),
"--your app name goes here--");

var json = new WebClient().DownloadString(uri);

```

You can use more parameters as you want. For more details, [click here](https://docs.nexmo.com/verify/api-reference/api-reference#rparameters)

4. To get Verify API response, add following line:

```
JsonResponse result = JsonConvert.DeserializeObject(json);

```

5. Each request you make to the Verify API returns:

```
{
"request_id": "requestId",
"status": "status",
"error_text": "error"
}

```

6. Now to check whether the PIN number user entered is correct or not, I
have created another method named "VerifyOTPCode" with parameter
"requestId", "code" and "toNumber" of type string with return type
"JsonVerifyCheckResponse"

Where, requestId = Id which is generated by Nexmo per request code = PIN
number which user will enter toNumber = phone/mobile number to whom SMS
is to be sent. For more details, [click here](https://docs.nexmo.com/verify/api-reference/api-reference#vrequest).

7. To send request, add following code in this method:

```
string uri = string.Format("{0}/verify/check/json?api_key={1}&api_secret={2}&request_id={3}&code={4}",
ConfigurationManager.AppSettings["Nexmo.Url.Api"],
HttpUtility.UrlEncode(ConfigurationManager.AppSettings["Nexmo.api_key"]),
HttpUtility.UrlEncode(ConfigurationManager.AppSettings["Nexmo.api_secret"]),
requestId, code);

var json = new WebClient().DownloadString(uri);

```

8. Now add below line to deserialize the given object and get the
response.

```
JsonVerifyCheckResponse result = JsonConvert.DeserializeObject(json);

```

Response will look like following format:

```
{
"event_id": "eventId",
"status": "status",
"price": "price",
"currency": "currency",
"error_text": "error"
}

```

9. The response contains key-value format. For more details about
responses, [click here](https://docs.nexmo.com/verify/api-reference/api-reference#ckeys). I have attached the output of Verify API below.

Figure 2: Output for Verify API Sample

## Some Helpful Links

[Getting started sending SMS guide](https://help.nexmo.com/hc/en-us/articles/204014803-Getting-started-sending-SMS-guide)

[Nexmo Developer](https://developers.nexmo.com/Quickstarts/verify/search/)

Happy Coding :)