Integrating Plivo SMS API with ASP.NET Core: A Comprehensive Guide

Date- Apr 29,2026 91

plivo sms

Overview

The Plivo SMS API is a powerful tool that allows applications to send and receive SMS messages programmatically. It exists to solve the need for effective communication in various sectors, including customer support, marketing, and transactional notifications. With the proliferation of mobile devices, SMS has become a vital channel for reaching users directly and instantly.

Real-world use cases for the Plivo SMS API are abundant. Businesses utilize SMS for sending promotional offers, reminders for appointments, two-factor authentication codes, and alerts for system statuses. By integrating SMS functionality into applications, organizations can enhance user engagement and improve operational efficiency.

Prerequisites

ASP.NET Core SDK: Ensure that the latest version is installed to create and run the application.
Plivo Account: Create a Plivo account to obtain the necessary API credentials (Auth ID and Auth Token).
NuGet Package Manager: Familiarity with installing packages in ASP.NET Core.
Basic Knowledge of REST APIs: Understanding how to make HTTP requests and handle responses.

Setting Up the ASP.NET Core Project

Before integrating the Plivo SMS API, we need to set up an ASP.NET Core project. This serves as the foundation for our integration efforts. We will create a new web application that can handle SMS requests and responses.

dotnet new webapp -n PlivoSmsIntegration

This command creates a new ASP.NET Core web application in a folder named PlivoSmsIntegration. Next, navigate to the project directory:

cd PlivoSmsIntegration

Now, we need to add the RestSharp library, which simplifies making HTTP requests to the Plivo API. Install it via NuGet:

dotnet add package RestSharp

The RestSharp library is a popular HTTP client for .NET, facilitating the process of sending requests and handling responses.

Creating the SMS Service

Next, we will create a service that encapsulates the logic for sending SMS messages through the Plivo API. This promotes separation of concerns and makes the code easier to maintain.

using RestSharp;
using System.Threading.Tasks;

public class SmsService
{
    private readonly string _authId;
    private readonly string _authToken;
    private readonly string _apiUrl = "https://api.plivo.com/v1/Account/{auth_id}/Message/";

    public SmsService(string authId, string authToken)
    {
        _authId = authId;
        _authToken = authToken;
    }

    public async Task SendSmsAsync(string to, string from, string text)
    {
        var client = new RestClient(_apiUrl.Replace("{auth_id}", _authId));
        var request = new RestRequest(Method.POST);
        request.AddHeader("Authorization", "Basic " + Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(_authId + ":" + _authToken)));
        request.AddJsonBody(new { src = from, dst = to, text = text });

        var response = await client.ExecuteAsync(request);
        return response.Content;
    }
}

This SmsService class is designed to handle SMS sending operations. It requires the Auth ID and Auth Token for authentication with the Plivo API. The SendSmsAsync method constructs the API request and sends it asynchronously.

Line-by-line explanation:

using RestSharp; - Imports the RestSharp library.
private readonly string _authId; - Stores the Auth ID for API authentication.
private readonly string _authToken; - Stores the Auth Token for API authentication.
private readonly string _apiUrl; - Defines the API endpoint, with a placeholder for the Auth ID.
public SmsService(string authId, string authToken) - Constructor that initializes the service with credentials.
public async Task SendSmsAsync(string to, string from, string text) - Asynchronous method to send an SMS.
var client = new RestClient(_apiUrl.Replace("{auth_id}", _authId)); - Initializes the RestClient with the API URL.
var request = new RestRequest(Method.POST); - Creates a POST request.
request.AddHeader("Authorization", ...); - Adds the necessary authorization header.
request.AddJsonBody(new { src = from, dst = to, text = text }); - Adds the SMS details to the request body.
var response = await client.ExecuteAsync(request); - Executes the request and waits for the response.
return response.Content; - Returns the response content, which contains the SMS sending result.

Integrating the SMS Service into the Application

With the SmsService established, the next step is to integrate it into the ASP.NET Core application. This involves configuring the service in the dependency injection container and creating a controller to handle incoming requests.

Adding to Startup.cs

Open the Startup.cs file and register the SmsService in the ConfigureServices method:

services.AddSingleton(new SmsService("YOUR_AUTH_ID", "YOUR_AUTH_TOKEN"));

Replace YOUR_AUTH_ID and YOUR_AUTH_TOKEN with your actual Plivo credentials. This registration allows the service to be injected into controllers.

Creating the SMS Controller

Next, we will create a controller to expose an endpoint for sending SMS messages. This controller will accept parameters for the recipient's number, sender's number, and the message text.

using Microsoft.AspNetCore.Mvc;

[Route("api/[controller]")]
[ApiController]
public class SmsController : ControllerBase
{
    private readonly SmsService _smsService;

    public SmsController(SmsService smsService)
    {
        _smsService = smsService;
    }

    [HttpPost]
    public async Task SendSms([FromBody] SmsRequest request)
    {
        var result = await _smsService.SendSmsAsync(request.To, request.From, request.Text);
        return Ok(result);
    }
}

public class SmsRequest
{
    public string To { get; set; }
    public string From { get; set; }
    public string Text { get; set; }
}

This SmsController class defines an API endpoint for sending SMS messages. The SendSms method processes incoming requests and calls the SendSmsAsync method of the SmsService.

Line-by-line explanation:

[Route("api/[controller]")] - Sets the route for the controller.
[ApiController] - Indicates that this class is an API controller.
private readonly SmsService _smsService; - Holds the SMS service instance.
public SmsController(SmsService smsService) - Constructor that accepts the SMS service through dependency injection.
[HttpPost] - Indicates that this method responds to POST requests.
public async Task SendSms([FromBody] SmsRequest request) - The action method to send an SMS.
var result = await _smsService.SendSmsAsync(request.To, request.From, request.Text); - Calls the SMS service to send the message.
return Ok(result); - Returns the result as an HTTP response.

Testing the SMS Integration

Once the integration is complete, it’s essential to test the SMS functionality to ensure that messages are sent as expected. This can be done using tools like Postman or cURL to send HTTP POST requests to the API endpoint.

Using Postman

Open Postman and set up a new request to http://localhost:5000/api/sms with the following JSON body:

{
    "To": "+1234567890",
    "From": "+0987654321",
    "Text": "Hello from Plivo SMS API"
}

Replace the phone numbers with valid numbers. After sending the request, you should receive a response indicating the result of the SMS sending operation. If successful, the response will contain details about the message sent.

Edge Cases & Gotchas

When integrating with the Plivo SMS API, several edge cases and potential pitfalls can arise. Understanding these will help in creating a robust application.

Invalid Phone Numbers

One common issue is sending messages to invalid phone numbers. Plivo will return an error response if the number is not formatted correctly or does not exist.

if (!IsValidPhoneNumber(request.To))
{
    return BadRequest("Invalid phone number format.");
}

This code checks the validity of the phone number before attempting to send an SMS. Implementing such validation can prevent unnecessary API calls and reduce costs.

Rate Limiting

Plivo enforces rate limits on API calls. Exceeding these limits can result in temporary blocking. To manage this, implement retries with exponential backoff.

public async Task SendSmsWithRetryAsync(string to, string from, string text, int retries = 3)
{
    for (int i = 0; i < retries; i++)
    {
        var result = await SendSmsAsync(to, from, text);
        if (IsSuccess(result)) return result;
        await Task.Delay(1000 * (int)Math.Pow(2, i)); // Exponential backoff
    }
    return "Failed to send SMS after retries.";
}

This method attempts to send an SMS multiple times with increasing wait times between attempts. This approach helps mitigate the impact of transient failures or rate limiting.

Performance & Best Practices

To ensure optimal performance when integrating the Plivo SMS API, consider the following best practices:

Asynchronous Operations

Always use asynchronous methods when interacting with external APIs. This prevents blocking the main thread and improves the responsiveness of your application.

Batch Sending

If you need to send messages to multiple recipients, consider using batch sending capabilities. Plivo supports sending bulk messages, which can be more efficient and cost-effective.

public async Task SendBulkSmsAsync(List requests)
{
    foreach (var request in requests)
    {
        await SendSmsAsync(request.To, request.From, request.Text);
    }
    return "Bulk SMS sent.";
}

This method iterates over a list of SMS requests and sends them one by one. For even better performance, consider using Plivo's bulk messaging features if available.

Real-World Scenario: User Verification System

As a practical application of the Plivo SMS API, we will create a simple user verification system that sends an SMS verification code to users upon registration.

Building the Registration Endpoint

Extend the existing application to include a user registration endpoint. When a user registers, generate a verification code and send it via SMS.

[HttpPost]
[Route("api/register")]
public async Task Register([FromBody] UserRegistrationRequest request)
{
    var verificationCode = GenerateVerificationCode();
    await _smsService.SendSmsAsync(request.PhoneNumber, "YOUR_FROM_NUMBER", "Your verification code is: " + verificationCode);
    return Ok("Registration successful, verification code sent.");
}

public class UserRegistrationRequest
{
    public string PhoneNumber { get; set; }
}

This registration endpoint generates a verification code and sends it via SMS. The GenerateVerificationCode method can be a simple random number generator.

Conclusion

Integration of Plivo SMS API: Understanding how to integrate the Plivo SMS API into an ASP.NET Core application enhances communication capabilities.
Service Layer: Implementing a service layer for SMS operations promotes code organization and maintainability.
Error Handling: Addressing edge cases like invalid phone numbers and implementing rate limiting strategies is crucial for robust applications.
Asynchronous Programming: Utilizing async methods improves application performance and user experience.
Real-World Application: The user verification scenario demonstrates practical usage of the SMS API in a typical application flow.