A blog on software development, gadgets, security and some more Volkan Paksoy's Blog 2026-08-06T18:33:19+00:00 https://volkanpaksoy.com/ Octopress <![CDATA[Implementing a Custom MCP Server with .NET]]> 2026-08-05T13:20:00+00:00 https://volkanpaksoy.com/archive/2026/08/05/Implementing-a-Custom-MCP-Server-with-dotNET In the previous post, you learned how to use AWS Knowledge MCP Server in Claude Code. That server was hosted remotely by AWS, making it simple to add with just a URL. But what if you need custom functionality specific to your domain or workflow? That’s where building your own MCP server comes in.

In this tutorial, you’ll build a custom Weather MCP Server using .NET 9. More importantly, you’ll implement it with two different transports: stdio (for local processes) and HTTP (for remote services). This demonstrates a key MCP principle: your business logic stays the same regardless of how clients connect to it.

What You’ll Build

A Weather MCP Server that provides:

  • Current weather information for any location
  • Random temperature generation (mock data for demonstration)
  • Two deployment options: local stdio and HTTP endpoint

By the end of this tutorial, you’ll understand:

  • How MCP servers are architected
  • The difference between business logic and transport layers
  • When to use stdio vs HTTP transports
  • How to integrate both types into Claude Code

Pre-requisites

Before starting, ensure you have:

Required Software

  1. .NET 9 SDK
  2. IDE or Code Editor
    • Visual Studio 2022 (Windows/Mac)
    • Visual Studio Code with C# extension
    • JetBrains Rider
    • Any text editor (vim, nano, etc.)
  3. Claude Code
    • Already installed from previous tutorials
    • Verify with: claude --version

Understanding MCP Server Architecture

Before diving into code, let’s understand how MCP servers are structured. This architectural understanding will make the implementation much clearer.

The Two-Layer Design

MCP servers follow a clean separation of concerns:

graph TB
    subgraph "MCP Server Architecture"
        A[Business Logic Layer] -->|Uses| B[MCP Protocol Layer]
        B -->|Exposes via| C1[Stdio Transport]
        B -->|Exposes via| C2[HTTP Transport]
        B -->|Exposes via| C3[SSE Transport]
    end

    C1 --> D1[Local Process<br/>Claude Code]
    C2 --> D2[Remote HTTP<br/>Any Client]
    C3 --> D2

    style A fill:#2ECC40
    style B fill:#FF851B
    style C1 fill:#0074D9
    style C2 fill:#0074D9
    style C3 fill:#0074D9

Layer 1: Business Logic

  • Your domain-specific code (weather data, database queries, API calls, etc.)
  • Independent of how clients connect
  • Reusable across different transports

Layer 2: Transport

  • Handles communication protocol (stdio, HTTP, SSE)
  • Wraps business logic in MCP protocol format
  • Manages serialization, requests, and responses

Why This Matters

With this design, you write your weather logic once and expose it through multiple transports. Need to add WebSocket support later? Just add another transport wrapper—no changes to business logic.

This is exactly what you’ll implement: one weather service, two transports.

Project Setup

Now you’re ready to start building!

Create a directory for your project:

mkdir weather-mcp-server
cd weather-mcp-server

Step 1: Create the Solution Structure

Let’s create a .NET solution with three projects:

# Create solution
dotnet new sln -n WeatherMcpServer

# Create shared library for business logic
dotnet new classlib -n WeatherMcp.Core

# Create stdio transport project
dotnet new console -n WeatherMcp.Stdio

# Create HTTP transport project
dotnet new web -n WeatherMcp.Http

# Add projects to solution
dotnet sln add WeatherMcp.Core/WeatherMcp.Core.csproj
dotnet sln add WeatherMcp.Stdio/WeatherMcp.Stdio.csproj
dotnet sln add WeatherMcp.Http/WeatherMcp.Http.csproj

# Add project references
dotnet add WeatherMcp.Stdio reference WeatherMcp.Core
dotnet add WeatherMcp.Http reference WeatherMcp.Core

Your folder structure should now look like this:

weather-mcp-server/
├── WeatherMcpServer.sln
├── WeatherMcp.Core/
│   ├── WeatherMcp.Core.csproj
│   └── Class1.cs
├── WeatherMcp.Stdio/
│   ├── WeatherMcp.Stdio.csproj
│   └── Program.cs
└── WeatherMcp.Http/
    ├── WeatherMcp.Http.csproj
    └── Program.cs

Step 2: Install Required NuGet Packages

You’ll implement the MCP protocol manually using JSON-RPC, giving you full control and understanding. No external MCP packages needed—just .NET built-in JSON serialization.

Step 3: Implement the Core Weather Service

Delete Class1.cs in WeatherMcp.Core and create these files:

WeatherMcp.Core/Models/WeatherData.cs

namespace WeatherMcp.Core.Models;

public record WeatherData(
    string Location,
    double TemperatureCelsius,
    string Condition,
    int Humidity,
    double WindSpeed,
    DateTime Timestamp
)
{
    public double TemperatureFahrenheit => (TemperatureCelsius * 9 / 5) + 32;
}

WeatherMcp.Core/Services/IWeatherService.cs

using WeatherMcp.Core.Models;

namespace WeatherMcp.Core.Services;

public interface IWeatherService
{
    Task<WeatherData> GetCurrentWeatherAsync(string location);
}

WeatherMcp.Core/Services/MockWeatherService.cs

using WeatherMcp.Core.Models;

namespace WeatherMcp.Core.Services;

public class MockWeatherService : IWeatherService
{
    private static readonly string[] Conditions =
    {
        "Sunny", "Partly Cloudy", "Cloudy", "Rainy", "Stormy", "Snowy", "Foggy", "Windy"
    };

    private readonly Random _random = new();

    public Task<WeatherData> GetCurrentWeatherAsync(string location)
    {
        // Generate random but realistic weather data
        var temperature = _random.Next(-10, 40); // -10°C to 40°C
        var condition = Conditions[_random.Next(Conditions.Length)];
        var humidity = _random.Next(30, 100);
        var windSpeed = _random.NextDouble() * 30; // 0-30 km/h

        var weather = new WeatherData(
            Location: location,
            TemperatureCelsius: temperature,
            Condition: condition,
            Humidity: humidity,
            WindSpeed: Math.Round(windSpeed, 1),
            Timestamp: DateTime.UtcNow
        );

        return Task.FromResult(weather);
    }
}

WeatherMcp.Core/Mcp/McpServer.cs

This is the core MCP protocol implementation:

using System.Text.Json;
using System.Text.Json.Serialization;
using WeatherMcp.Core.Services;

namespace WeatherMcp.Core.Mcp;

public class McpServer
{
    private readonly IWeatherService _weatherService;

    public McpServer(IWeatherService weatherService)
    {
        _weatherService = weatherService;
    }

    public async Task<string> HandleRequestAsync(string jsonRequest)
    {
        try
        {
            var request = JsonSerializer.Deserialize<McpRequest>(jsonRequest);

            if (request == null)
                return CreateErrorResponse("Invalid request format");

            return request.Method switch
            {
                "initialize" => await HandleInitializeAsync(request),
                "tools/list" => HandleToolsList(request),
                "tools/call" => await HandleToolCallAsync(request),
                _ => CreateErrorResponse($"Unknown method: {request.Method}")
            };
        }
        catch (Exception ex)
        {
            return CreateErrorResponse($"Error processing request: {ex.Message}");
        }
    }

    private Task<string> HandleInitializeAsync(McpRequest request)
    {
        var response = new
        {
            jsonrpc = "2.0",
            id = request.Id,
            result = new
            {
                protocolVersion = "2024-11-05",
                capabilities = new
                {
                    tools = new { }
                },
                serverInfo = new
                {
                    name = "weather-mcp-server",
                    version = "1.0.0"
                }
            }
        };

        return Task.FromResult(JsonSerializer.Serialize(response));
    }

    private string HandleToolsList(McpRequest request)
    {
        var response = new
        {
            jsonrpc = "2.0",
            id = request.Id,
            result = new
            {
                tools = new[]
                {
                    new
                    {
                        name = "get_current_weather",
                        description = "Get current weather information for a specific location",
                        inputSchema = new
                        {
                            type = "object",
                            properties = new
                            {
                                location = new
                                {
                                    type = "string",
                                    description = "City name or location (e.g., 'London', 'New York', 'Tokyo')"
                                }
                            },
                            required = new[] { "location" }
                        }
                    }
                }
            }
        };

        return JsonSerializer.Serialize(response);
    }

    private async Task<string> HandleToolCallAsync(McpRequest request)
    {
        if (request.Params?.Name != "get_current_weather")
            return CreateErrorResponse("Unknown tool");

        var location = request.Params.Arguments?.GetProperty("location").GetString();

        if (string.IsNullOrEmpty(location))
            return CreateErrorResponse("Location is required");

        var weather = await _weatherService.GetCurrentWeatherAsync(location);

        var response = new
        {
            jsonrpc = "2.0",
            id = request.Id,
            result = new
            {
                content = new[]
                {
                    new
                    {
                        type = "text",
                        text = $@"Current weather in {weather.Location}:
Temperature: {weather.TemperatureCelsius}°C ({weather.TemperatureFahrenheit:F1}°F)
Condition: {weather.Condition}
Humidity: {weather.Humidity}%
Wind Speed: {weather.WindSpeed} km/h
Last Updated: {weather.Timestamp:yyyy-MM-dd HH:mm:ss} UTC"
                    }
                }
            }
        };

        return JsonSerializer.Serialize(response);
    }

    private string CreateErrorResponse(string message)
    {
        var response = new
        {
            jsonrpc = "2.0",
            error = new
            {
                code = -32603,
                message
            }
        };

        return JsonSerializer.Serialize(response);
    }
}

public class McpRequest
{
    [JsonPropertyName("jsonrpc")]
    public string? JsonRpc { get; set; }

    [JsonPropertyName("id")]
    public object? Id { get; set; }

    [JsonPropertyName("method")]
    public string? Method { get; set; }

    [JsonPropertyName("params")]
    public McpParams? Params { get; set; }
}

public class McpParams
{
    [JsonPropertyName("name")]
    public string? Name { get; set; }

    [JsonPropertyName("arguments")]
    public JsonElement? Arguments { get; set; }
}

Understanding the MCP Protocol Implementation

This code is the heart of your MCP server. Let’s break down what each part does:

The Main Handler: HandleRequestAsync

public async Task<string> HandleRequestAsync(string jsonRequest)

This is the entry point for all MCP requests. It:

  1. Deserializes the incoming JSON-RPC request
  2. Routes to the appropriate handler based on the method field
  3. Returns a JSON-RPC response

The MCP protocol uses three core methods:

  • initialize - Handshake when client connects
  • tools/list - Client asks “what can you do?”
  • tools/call - Client executes a specific tool

HandleInitializeAsync: The Handshake

private Task<string> HandleInitializeAsync(McpRequest request)

When a client first connects, they send an initialize request. Your response tells them:

  • Protocol version: 2024-11-05 (current MCP spec version)
  • Capabilities: What features you support (in this case, just tools)
  • Server info: Your server’s name and version

This is like a handshake - the client learns what your server can do before making any requests.

HandleToolsList: Advertising Your Tools

private string HandleToolsList(McpRequest request)

This is where you advertise your tool to clients. Remember from the AWS MCP post how the AI knew what tool to use? This is where that magic happens!

Each tool advertisement includes:

  • name: The tool identifier (get_current_weather)
  • description: What the tool does (this is what the AI reads!)
  • inputSchema: JSON Schema defining required parameters

The description is crucial - it’s how the AI decides when to use your tool. Make it clear and specific!

HandleToolCallAsync: Doing the Work

private async Task<string> HandleToolCallAsync(McpRequest request)

When the AI decides to use your tool, this method:

  1. Validates the tool name matches (get_current_weather)
  2. Extracts the location parameter from the request
  3. Calls your weather service to get the data
  4. Formats the response according to MCP spec

The response must follow the MCP format:

{
  "jsonrpc": "2.0",
  "id": <request_id>,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "<your formatted response>"
      }
    ]
  }
}

The content array can contain multiple items (text, images, resources, etc.). For simplicity, we’re just returning formatted text.

Error Handling

private string CreateErrorResponse(string message)

When something goes wrong (invalid tool, missing parameter, etc.), you return a JSON-RPC error response with:

  • code: -32603 (Internal error code from JSON-RPC spec)
  • message: What went wrong

The Request Models

public class McpRequest
public class McpParams

These classes map JSON-RPC requests to C# objects. Key points:

  • JsonPropertyName attributes map JSON field names to C# properties
  • JsonElement? for Arguments because we don’t know the structure ahead of time
  • Nullable types (string?, object?) handle optional fields

How It All Flows Together

Here’s a typical conversation:

  1. Client connects 
    → {"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05",...}}
  2. Client asks what tools exist 
    → {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
← {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"get_current_weather",...}]}}
  3. AI reads tool descriptions and decides to call your tool 
    → {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_current_weather","arguments":{"location":"London"}}}
← {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Current weather in London..."}]}}

This is JSON-RPC over MCP - your transport layer (stdio or HTTP) handles the communication, while this class handles the protocol logic.

The core business logic is now complete! You now have:

  • Weather data models
  • Mock weather service
  • MCP protocol handler

Step 4: Implement Stdio Transport

Now wrap your weather service in a stdio transport. Replace the contents of WeatherMcp.Stdio/Program.cs:

using System.Text;
using WeatherMcp.Core.Mcp;
using WeatherMcp.Core.Services;

// Create weather service and MCP server
var weatherService = new MockWeatherService();
var mcpServer = new McpServer(weatherService);

// Read from stdin, write to stdout (stdio transport)
// IMPORTANT: Use UTF8 without BOM to avoid JSON parsing issues
var utf8NoBom = new UTF8Encoding(false);
using var reader = new StreamReader(Console.OpenStandardInput(), utf8NoBom);
using var writer = new StreamWriter(Console.OpenStandardOutput(), utf8NoBom) { AutoFlush = true };

try
{
    while (true)
    {
        var line = await reader.ReadLineAsync();

        if (line == null)
            break; // EOF reached

        if (string.IsNullOrWhiteSpace(line))
            continue;

        var response = await mcpServer.HandleRequestAsync(line);

        await writer.WriteLineAsync(response);
    }
}
catch (Exception)
{
    // Silently handle errors - stderr logging can interfere with Claude Code
}

Important Notes:

  1. UTF-8 without BOM: The new UTF8Encoding(false) is critical. By default, .NET’s UTF-8 encoding includes a Byte Order Mark (BOM) which breaks JSON parsing. Claude Code expects pure JSON output without any BOM.

  2. No stderr logging: We removed all Console.Error logging because Claude Code monitors stderr for errors. Any output to stderr can cause connection issues or timeouts.

  3. Silent error handling: Errors are caught but not logged. In production, you might want to log to a file instead.

Test the Stdio Server

Build and test the stdio server:

# Build the project
dotnet build WeatherMcp.Stdio

# Test it manually
cd WeatherMcp.Stdio/bin/Debug/net9.0

# Run and send a test request
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ./WeatherMcp.Stdio

You should see the initialization response!

Step 5: Implement HTTP Transport

Now create an HTTP endpoint. Replace WeatherMcp.Http/Program.cs:

using WeatherMcp.Core.Mcp;
using WeatherMcp.Core.Services;

var builder = WebApplication.CreateBuilder(args);

// Register services
builder.Services.AddSingleton<IWeatherService, MockWeatherService>();
builder.Services.AddSingleton<McpServer>();

// Configure CORS for development
builder.Services.AddCors(options =>
{
    options.AddDefaultPolicy(policy =>
    {
        policy.AllowAnyOrigin()
              .AllowAnyMethod()
              .AllowAnyHeader();
    });
});

var app = builder.Build();

app.UseCors();

// MCP endpoint
app.MapPost("/mcp", async (HttpContext context, McpServer mcpServer) =>
{
    using var reader = new StreamReader(context.Request.Body);
    var requestBody = await reader.ReadToEndAsync();

    var response = await mcpServer.HandleRequestAsync(requestBody);

    context.Response.ContentType = "application/json";
    await context.Response.WriteAsync(response);
});

// Health check endpoint
app.MapGet("/health", () => Results.Ok(new { status = "healthy", service = "weather-mcp-server" }));

// Root endpoint with instructions
app.MapGet("/", () => Results.Ok(new
{
    message = "Weather MCP Server",
    version = "1.0.0",
    endpoints = new
    {
        mcp = "/mcp (POST)",
        health = "/health (GET)"
    },
    example = "POST to /mcp with MCP JSON-RPC requests"
}));

app.Run("http://localhost:3000");

Test the HTTP Server

# Build and run
cd WeatherMcp.Http
dotnet run

In another terminal, test it:

# Test health endpoint
curl http://localhost:3000/health

# Test MCP initialization
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# Test weather tool
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_current_weather","arguments":{"location":"London"}}}'

Once you’ve ensured both transports are working, move on to the next step.

Step 6: Add Stdio Server to Claude Code

Now integrate the stdio version with Claude Code.

Build a Release Version

cd weather-mcp-server
dotnet publish WeatherMcp.Stdio -c Release -o ./publish/stdio

This creates a .dll file that you’ll run using the dotnet command.

Why .dll instead of standalone executable? By default, dotnet publish creates a framework-dependent deployment (.dll file) that requires the .NET runtime. This is the standard approach most .NET developers are familiar with. It’s smaller, faster to publish, and leverages the .NET SDK already installed on your machine.

Add to Claude Code

Since .NET publish creates a .dll (not a standalone executable), you need to configure Claude Code to run it with the dotnet command.

Option 1: Using Claude Code CLI

Unfortunately, claude mcp add doesn’t support complex command structures like dotnet <dll>, so you’ll need to configure it manually.

Option 2: Manual Configuration (Recommended)

Edit your user-scoped config file:

nano ~/.claude.json

Add the weather-stdio server to the mcpServers section:

{
  "mcpServers": {
    "aws-knowledge": {
      "type": "http",
      "url": "https://knowledge-mcp.global.api.aws"
    },
    "weather-stdio": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["/absolute/path/to/weather-mcp-server/publish/stdio/WeatherMcp.Stdio.dll"],
      "env": {}
    }
  }
}

Important: Replace /absolute/path/to/ with your actual path. To get it:

cd weather-mcp-server/publish/stdio
pwd

For example, it might look like:

"weather-stdio": {
  "type": "stdio",
  "command": "dotnet",
  "args": ["/Users/yourname/weather-mcp-server/publish/stdio/WeatherMcp.Stdio.dll"],
  "env": {}
}

Save and exit (Ctrl+X, then Y, then Enter in nano).

Verify It Works

# Check MCP servers
claude mcp list

# Should show: weather-stdio - ✓ Connected

Start Claude Code and ask:

What's the weather in Sydney?

Claude Code should use your custom weather MCP server!

Step 7: Add HTTP Server to Claude Code

Now add the HTTP version. Since both stdio and HTTP servers provide the same tool (get_current_weather), we’ll temporarily remove the stdio server to clearly test the HTTP version.

Remove Stdio Server

Edit ~/.claude.json and comment out or remove the weather-stdio entry:

nano ~/.claude.json

Remove or comment out the weather-stdio section so it looks like this:

{
  "mcpServers": {
    "aws-knowledge": {
      "type": "http",
      "url": "https://knowledge-mcp.global.api.aws"
    }
  }
}

Save and exit (Ctrl+X, then Y, then Enter).

Verify it’s removed:

claude mcp list

You should only see aws-knowledge now.

Start the HTTP Server

In one terminal:

cd WeatherMcp.Http
dotnet run

This runs on http://localhost:3000.

Add to Claude Code

In another terminal:

claude mcp add --transport http weather-http --scope user http://localhost:3000/mcp

The --scope user flag makes the HTTP server available globally, just like the stdio version.

Alternative: Manual Configuration

If configuring manually, edit ~/.claude.json:

{
  "mcpServers": {
    "weather-stdio": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["/absolute/path/to/WeatherMcp.Stdio.dll"],
      "env": {}
    },
    "weather-http": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Verify Both Work

claude mcp list

# Should show:
# weather-stdio - ✓ Connected
# weather-http - ✓ Connected

Now you have the same weather service exposed through two different transports!

When to Use Which Transport

Now that you’ve built both, when should you use each?

Use Stdio Transport When:

✅ Local development and testing

  • Fast iteration, no network overhead
  • Easy debugging with stderr logs
  • Direct process communication

✅ Personal tools and scripts

  • No need for remote access
  • Simpler deployment (single executable)
  • Lower resource usage

✅ Security-sensitive operations

  • Data never leaves your machine
  • No network exposure
  • Direct file system access

Example Use Cases:

  • Local file system MCP server
  • Database query tools
  • Personal automation scripts
  • Development utilities

Use HTTP Transport When:

✅ Team collaboration

  • Multiple developers share one server
  • Centralized data source
  • Consistent results across team

✅ Remote services

  • MCP server on different machine
  • Cloud-hosted services
  • Containerized deployments

✅ Third-party integrations

  • Public APIs need HTTP
  • Integration with existing web services
  • Cross-platform compatibility

✅ Scalability requirements

  • Load balancing
  • Multiple instances
  • High availability

Example Use Cases:

  • Shared company knowledge base
  • Cloud-based data services
  • External API wrappers
  • Production services

Comparison Table

Feature Stdio HTTP
Setup Complexity Simple Moderate
Network Required No Yes
Remote Access No Yes
Performance Fastest Network latency
Security Local only Authentication needed
Scalability One instance Load balanceable
Debugging Direct logs HTTP tools/logging
Best For Local tools Shared services

Conclusion

Congratulations! You’ve built a complete custom MCP server from scratch using .NET 9. More importantly, you’ve learned the fundamental architectural principle of MCP: separation of business logic from transport.

If you didn’t follow along, you can download the source code of the final version here (the project is in the weather-mcp-server folder)

What You’ve Accomplished

  1. Built a reusable weather service - Core business logic that’s transport-agnostic
  2. Implemented stdio transport - For fast local development and personal tools
  3. Implemented HTTP transport - For remote access and team collaboration
  4. Integrated with Claude Code - Made your custom tools accessible to AI
  5. Understood when to use each - Made informed architecture decisions

Key Takeaways

  • MCP is transport-agnostic - Write once, deploy many ways
  • Stdio is fast and simple - Perfect for local tools
  • HTTP enables sharing - Ideal for team services
  • Protocol is straightforward - JSON-RPC makes it easy to implement
  • Custom servers unlock potential - AI can access your unique data and services

Next Steps

Now that you understand the fundamentals, consider:

  1. Add real data sources - Replace mock weather with actual APIs
  2. Implement authentication - Secure your HTTP server
  3. Add more tools - Forecast, historical data, alerts
  4. Deploy to production - Docker, Kubernetes, cloud platforms
  5. Build domain-specific servers - Database tools, CI/CD integrations, business logic

The MCP ecosystem is growing rapidly. By understanding how to build custom servers, you can create AI-accessible tools tailored to your specific needs.

Resources

]]> <![CDATA[How to Use AWS MCP Servers in Claude Code]]> 2026-08-05T13:15:00+00:00 https://volkanpaksoy.com/archive/2026/08/05/How-to-Use-AWS-MCP-Servers-in-Claude-Code In the previous post, we took a detailed look at Model Context Protocol (MCP). Now it’s time to work on something more practical and utilize that knowledge. AWS has released a comprehensive suite of MCP servers, and since AWS is a ubiquitous cloud provider, I thought it would be a good exercise to integrate them into my workflow when using Claude Code.

AWS provides over 60 MCP servers covering everything from documentation and infrastructure management to AI/ML services and cost analysis. In this tutorial, we’ll focus on the AWS Knowledge MCP Server which recently became generally available.

What is AWS Knowledge MCP Server?

AWS Knowledge MCP Server is a fully managed remote service that provides AI agents and MCP clients with instant access to authoritative AWS information in LLM-compatible format. Think of it as having AWS’s entire knowledge base—documentation, API references, blog posts, What’s New announcements, and Well-Architected best practices—directly accessible to your AI assistant.

Key Features

Comprehensive AWS Knowledge Access:

  • Official AWS documentation
  • API references for all AWS services
  • What’s New announcements
  • Well-Architected Framework best practices
  • AWS Builder Library content
  • AWS blog posts
  • Regional availability of AWS APIs and CloudFormation resources

Fully Managed:

  • No setup or infrastructure management required
  • Publicly accessible at no cost
  • No AWS account required
  • Available globally
  • Subject to rate limits

Benefits:

  1. Accuracy - AI responses anchored in trusted AWS context
  2. Consistency - Reliable execution based on official guidance
  3. Efficiency - No manual context management or copy-pasting from docs

Setting Up AWS Knowledge MCP Server in Claude Code

Before you start, to get a baseline, run the following command to see what MCP servers you have configured. By default you shouldn’t see anything.

claude mcp list

In a default Claude Code installation, your output should look similar to this:

Now, proceed to add the AWS Knowledge MCP Server.

Adding the Server

One of the beauties of AWS Knowledge MCP Server is its simplicity—it’s a remote HTTP service that requires minimal configuration.

First, exit Claude Code by running the following command in the terminal:

exit

Then, use the Claude Code CLI to add the server:

claude mcp add --transport http aws-knowledge https://knowledge-mcp.global.api.aws

This adds the server to your local scope (project-specific). If you want it available across all your projects:

claude mcp add --transport http aws-knowledge https://knowledge-mcp.global.api.aws --scope user

Alternative: Manual Configuration

You can also add it directly to your project’s .mcp.json file:

{
  "mcpServers": {
    "aws-knowledge": {
      "type": "http",
      "url": "https://knowledge-mcp.global.api.aws"
    }
  }
}

Verifying the Connection

Check that the server is properly configured:

claude mcp list

Your output should look like this:

Checking MCP server health...

aws-knowledge: https://knowledge-mcp.global.api.aws (HTTP) - ✓ Connected

You can also verify within Claude Code using the /mcp command.

Testing the Connection

To test that the MCP server is actually being used by Claude Code, ask an AWS-related question such as:

What are the current AWS Lambda timeout limits?

And the output should show that Claude Code knows what tool to use to get this data:

And when you proceed, you should get the answer directly coming from the AWS MCP Server:

How Does Claude Know What Tool to Use?

It’s great that when you ask an AWS-related question, it goes straight to the AWS Knowledge MCP server and gets the answer from the correct resource. But how does it know where to find the correct answer? What if I have an Azure MCP server installed as well, or other tools? How would it know which one to choose?

The MCP Discovery Process

When an MCP server connects to Claude Code, it doesn’t just sit there waiting. It actively advertises its capabilities through the Model Context Protocol. This is called the “capability discovery” phase, and it happens automatically when the server is initialized.

Here’s what happens behind the scenes:

sequenceDiagram
    participant CC as Claude Code
    participant MCP as MCP Server<br/>(AWS Knowledge)
    participant AI as AI Assistant

    CC->>MCP: Initialize connection
    MCP->>CC: Server info & capabilities
    Note over MCP,CC: Server advertises:<br/>- Available tools<br/>- Tool descriptions<br/>- Required parameters
    CC->>MCP: Request tool list
    MCP->>CC: Tools: search_documentation,<br/>read_documentation,<br/>get_regional_availability, etc.

    Note over CC,AI: User asks AWS question

    CC->>AI: Available tools from all MCP servers
    AI->>AI: Analyze question & match tools
    AI->>CC: Use aws___search_documentation
    CC->>MCP: Execute search_documentation("Lambda timeout")
    MCP->>CC: Return AWS documentation results
    CC->>AI: Results from AWS Knowledge
    AI->>CC: Formatted response to user

Tool Descriptions: The Key to Smart Routing

Each MCP server provides detailed metadata about its tools. This metadata is what allows the AI to make intelligent routing decisions. Let’s look at real examples:

AWS Knowledge MCP Server advertises:

{
  "name": "aws___search_documentation",
  "description": "Search AWS documentation, blogs, What's New announcements, and technical guides for information about AWS services, features, and best practices",
  "inputSchema": {
    "type": "object",
    "properties": {
      "search_phrase": {
        "type": "string",
        "description": "Search query for AWS documentation"
      },
      "limit": {
        "type": "integer",
        "description": "Maximum number of results to return"
      }
    }
  }
}

A hypothetical Weather MCP Server would advertise:

{
  "name": "weather___get_forecast",
  "description": "Get weather forecast for a specific location including temperature, precipitation, and conditions for upcoming days",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name or coordinates"
      },
      "days": {
        "type": "integer",
        "description": "Number of days to forecast (1-10)"
      }
    }
  }
}

Notice how different these descriptions are? The AI uses these descriptions to understand what each tool does and when to use it.

The Decision-Making Process

When you ask a question, here’s how the AI decides which tool to use:

graph TD
    A[User asks:<br/>'What are Lambda timeout limits?'] --> B[AI analyzes question]
    B --> C{Check all available<br/>MCP tools}

    C --> D1[aws___search_documentation<br/>AWS docs, services, features]
    C --> D2[weather___get_forecast<br/>Weather data for locations]
    C --> D3[github___search_code<br/>Search code repositories]

    B --> E{Match question to<br/>tool descriptions}

    E --> F{Keywords:<br/>Lambda, timeout, limits}
    F --> G{Best match?}

    G -->|AWS service| H[✓ aws___search_documentation]
    G -->|Weather related| I[✗ weather___get_forecast]
    G -->|Code related| J[✗ github___search_code]

    H --> K[Execute AWS Knowledge query]
    K --> L[Return Lambda timeout documentation]

    style H fill:#2ECC40
    style I fill:#FF4136
    style J fill:#FF4136

What Makes This Work

The AI considers several factors when choosing a tool:

  1. Semantic Matching: Does the tool description align with the question’s intent?
    • “Lambda timeout limits” semantically matches “AWS services, features, and best practices”
    • It does NOT match “weather forecast” or “code repositories”
  2. Domain Context: What domain does the question belong to?
    • AWS services → AWS Knowledge MCP Server
    • Weather information → Weather MCP Server
    • Code search → GitHub MCP Server
  3. Parameter Compatibility: Can the question be translated into the tool’s required parameters?
    • “Lambda timeout limits” → search_phrase: "Lambda timeout limits"
    • This fits the AWS Knowledge schema perfectly
  4. Tool Specificity: More specific tool descriptions get priority
    • A tool described as “AWS Lambda documentation” would beat “General cloud documentation”
    • Specificity helps avoid ambiguity

Multiple MCP Servers Working Together

The beauty of this system is that you can have many MCP servers installed simultaneously, and the AI will route questions to the right one:

graph LR
    A[You ask questions] --> B[AI Assistant]

    B --> C{Analyze & Route}

    C -->|AWS questions| D[AWS Knowledge<br/>MCP Server]
    C -->|Weather queries| E[Weather<br/>MCP Server]
    C -->|GitHub searches| F[GitHub<br/>MCP Server]
    C -->|Database queries| G[PostgreSQL<br/>MCP Server]

    D --> H[AWS Documentation]
    E --> I[Weather API]
    F --> J[GitHub API]
    G --> K[Your Database]

    style D fill:#FF851B
    style E fill:#0074D9
    style F fill:#2ECC40
    style G fill:#B10DC9

Example conversation with multiple servers:

You: What's the weather in Sydney?
AI: [Routes to Weather MCP Server] → Returns forecast

You: Does Lambda support ARM64 in ap-southeast-2?
AI: [Routes to AWS Knowledge MCP Server] → Returns AWS docs

You: Show me my S3 buckets
AI: [Routes to AWS API MCP Server] → Lists actual buckets

You: Find TypeScript code that uses Redis
AI: [Routes to GitHub MCP Server] → Searches repositories

Each question automatically goes to the right server based on the tool descriptions advertised during the MCP handshake.

Writing Good Tool Descriptions

When building your own MCP server, the quality of your tool descriptions directly impacts how effectively the AI can use your tools. Good descriptions should:

  1. Be specific: “Search AWS Lambda documentation” beats “Search docs”
  2. Include domain keywords: Mention the service, technology, or domain
  3. Explain the purpose: What problem does this tool solve?
  4. Define clear parameters: What inputs does the tool need?

This is why AWS Knowledge MCP Server works so well—its tool descriptions are comprehensive, specific, and well-aligned with the questions developers actually ask about AWS.

Conclusion

The AWS Knowledge MCP Server transforms how you access AWS documentation in Claude Code. With instant access to up-to-date AWS information, you can work faster, learn continuously, and make better-informed decisions—all without leaving your development environment.

The MCP standard ensures these integrations are reliable, secure, and maintainable. As AWS continues to add more specialized servers, the ecosystem will only become more powerful.

In this post, we looked into a rather simple MCP server that is hosted remotely. In the upcoming posts, we will delve deeper into custom MCP servers and MCP servers that run on our dev environments.

Resources

]]> <![CDATA[MCP Explained]]> 2026-08-05T13:10:00+00:00 https://volkanpaksoy.com/archive/2026/08/05/MCP-Explained Introduction

Artificial intelligence models are powerful, but they exist in a vacuum. They have knowledge up to their training cutoff date and can only work with information fed directly into a conversation. What happens when you need an AI to access real-time data, query your company’s database, or control devices in your home lab? This is where the Model Context Protocol (MCP) comes in.

MCP is an open standard that acts as a bridge between AI models and external systems. Think of it as a universal translator that allows AI assistants to securely request data from APIs, databases, file systems, and other services without requiring custom integrations for each one. In this post, we’ll explore what MCP is, how it works, and why it matters for the future of AI applications.

What Is the Model Context Protocol?

At its core, MCP is a standardized specification for how AI models can communicate with external data sources and tools. Instead of building custom code for each integration, developers can create MCP “servers” that expose their tools, databases, or APIs in a way that any MCP-compatible model can understand and use.

The key innovation is standardization. Without MCP, every time you wanted an AI model to access a new service, you’d need to describe that service’s API in detail within your prompt or system instructions. The model would then have to figure out how to call the right endpoints with the right parameters. It’s fragile, prone to errors, and doesn’t scale well.

MCP solves this by defining a clear protocol. An MCP server advertises what it can do—what tools it offers, what parameters they take, and what they return. The AI model receives this information in a structured format, understands it automatically, and can reliably invoke the right operations.

graph LR
    A[AI Model<br/>Assistant] <--> B[MCP Protocol<br/>Standardized Interface]
    B <--> C[MCP Server<br/>Database]
    B <--> D[MCP Server<br/>API]
    B <--> E[MCP Server<br/>File System]
    B <--> F[MCP Server<br/>IoT Devices]

    style A fill:#2ECC40
    style B fill:#FF851B
    style C fill:#0074D9
    style D fill:#0074D9
    style E fill:#0074D9
    style F fill:#0074D9

How MCP Works: The Simple Version

Imagine you have a restaurant reservation database and want an AI assistant to help customers check availability. Here’s the flow:

  1. You build an MCP server that exposes a tool called “check_availability” with parameters for date, time, and party size.

  2. The MCP server defines this in a standard schema that clearly states: “This tool requires a date (string), a time (string), and party_size (number).”

  3. When a user asks the AI “Do you have availability for 4 people tomorrow at 7 PM?”, the AI receives the MCP server’s capability list, understands what tools are available, and calls the check_availability tool with the right parameters.

  4. The MCP server processes the request, queries your database, and returns the result to the AI.

  5. The AI presents the answer to the user: “Yes, we have a table available.”

This entire flow is standardized. The AI doesn’t need custom code or special prompting—it just follows the protocol.

sequenceDiagram
    participant User
    participant AI as AI Assistant
    participant MCP as MCP Server<br/>(Restaurant DB)
    participant DB as Database

    User->>AI: "Table for 4 tomorrow at 7 PM?"
    AI->>MCP: Get available tools
    MCP->>AI: Tools: check_availability(date, time, party_size)
    AI->>MCP: check_availability("2025-10-28", "19:00", 4)
    MCP->>DB: Query availability
    DB->>MCP: Available: Yes
    MCP->>AI: Result: Table available
    AI->>User: "Yes, we have a table available."

    Note over AI,MCP: Standardized MCP Protocol

Real-Life Usage Scenarios

Scenario 1: Corporate Data Access A financial analyst asks their AI assistant, “What was our revenue growth in Q3?” Instead of manually pulling data, the AI calls an MCP server that queries the company’s data warehouse. The result is real, current, and accurate. The analyst gets instant answers without leaving the chat interface.

Scenario 2: Home Automation You have smart lights, thermostats, and security cameras in your home lab. An MCP server exposes these as tools. You can ask your AI assistant, “What’s the current temperature?” or “Turn on the lights in the living room,” and the AI reliably interacts with your devices through the MCP server.

Scenario 3: Knowledge Base Integration A support team uses MCP to connect their AI assistant to the internal knowledge base. When helping customers, the AI can search company documentation, policies, and FAQs in real-time. It provides accurate, consistent answers based on actual company knowledge, not hallucinations.

Scenario 4: DevOps and Monitoring An MCP server exposes system monitoring tools—check CPU usage, disk space, running processes, recent errors. An engineer asks their AI assistant, “What’s wrong with the production server?” The AI queries the monitoring tools, analyzes the data, and provides troubleshooting suggestions.

graph LR
    A[AI<br/>Assistant] --> B[MCP Protocol]

    B --> C1[Enterprise:<br/>Data Warehouses,<br/>Knowledge Bases,<br/>CRM Systems]

    B --> C2[Home & Personal:<br/>Smart Devices,<br/>Files,<br/>Media Libraries]

    B --> C3[Development:<br/>Code Repos,<br/>Build Systems,<br/>Package Managers]

    B --> C4[Operations:<br/>Monitoring,<br/>Logs,<br/>Infrastructure]

    style A fill:#2ECC40
    style B fill:#FF851B
    style C1 fill:#0074D9
    style C2 fill:#0074D9
    style C3 fill:#0074D9
    style C4 fill:#0074D9

Why MCP Matters

Without MCP, integrating external systems with AI requires constant manual effort. You write custom code, describe it to the model in prompts, and hope the model interprets your instructions correctly. This approach is error-prone and doesn’t scale.

MCP enables a future where tools and data sources are AI-ready by default. Developers expose their systems through MCP, and any AI model that understands the protocol can use them reliably. It’s a win for security too—you define exactly what operations are allowed and how they should be executed, rather than trusting an AI to interpret natural language instructions.

Conclusion

The Model Context Protocol represents a fundamental shift in how AI systems interact with the real world. By standardizing the interface between models and external systems, MCP makes AI more practical, reliable, and powerful. Whether you’re building enterprise applications, home automation systems, or experimental tools, MCP provides a framework for safely and reliably connecting your data and services to AI.

As MCP adoption grows, we can expect to see a thriving ecosystem of servers and integrations. For developers, the takeaway is clear: if you have data or tools you want AI systems to access, MCP is the modern way to do it. For users, it means AI models will become increasingly useful as practical assistants that can access real information and perform real actions—not just generate text based on training data.

Resources

]]> <![CDATA[LLMs Explained]]> 2026-08-05T13:05:00+00:00 https://volkanpaksoy.com/archive/2026/08/05/LLMs-Explained Large Language Models have become central to modern artificial intelligence, powering everything from chatbots to code generation tools. Yet for many, they remain mysterious black boxes. This post breaks down how LLMs work, from their fundamental architecture to why they’re so remarkably capable.

What Is an LLM?

A Large Language Model is a type of neural network trained to predict the next token (usually a word or subword) in a sequence. The term “large” refers to both the model’s architecture and its training data. Modern LLMs contain billions of parameters—adjustable weights that shape how information flows through the network—and are trained on trillions of tokens of text from diverse internet sources.

The core task sounds deceptively simple: given a sequence of words, predict what comes next. Yet this seemingly elementary objective, applied at massive scale with sophisticated architecture, produces systems capable of reasoning, coding, translation, and creative writing.

The Transformer Architecture

The breakthrough that enabled modern LLMs was the introduction of the Transformer architecture in 2017. Unlike earlier approaches like recurrent neural networks (RNNs), Transformers use a mechanism called attention to process sequences of text.

The attention mechanism allows the model to examine relationships between all words in an input simultaneously, rather than processing them sequentially. When the model encounters the word “bank,” attention helps it determine whether this refers to a financial institution or the side of a river based on context from the entire input. This parallel processing dramatically improved both training efficiency and model performance.

Transformers are built from stacked layers of attention and feed-forward neural networks. Each layer refines its understanding of the input, learning to extract increasingly abstract features. Early layers might recognize simple patterns like parts of speech, while deeper layers understand semantic relationships and complex reasoning.

graph TB
    A[Input Text: Tokens] --> B[Embedding Layer]
    B --> C[Transformer Layer 1]
    C --> D[Attention Mechanism]
    D --> E[Feed-Forward Network]
    E --> F[Transformer Layer 2]
    F --> G[Attention Mechanism]
    G --> H[Feed-Forward Network]
    H --> I[...]
    I --> J[Final Layer]
    J --> K[Output: Next Token Prediction]

    style D fill:#2ECC40
    style G fill:#2ECC40
    style E fill:#0074D9
    style H fill:#0074D9

Training: From Text to Intelligence

LLM training happens in two main phases: pre-training and fine-tuning.

During pre-training, models are exposed to enormous quantities of text—books, websites, code repositories, scientific papers—and learn to predict the next token. This self-supervised learning requires no manually labeled data; the objective is built into the task itself. Through this process, the model absorbs patterns about language, factual knowledge, reasoning patterns, and how ideas connect.

Pre-training is computationally expensive, requiring specialized hardware like GPUs or TPUs and taking weeks or months. After pre-training, the base model is remarkably capable but still rough around the edges.

Fine-tuning comes next. Here, models are trained on smaller, curated datasets with human feedback. Techniques like Reinforcement Learning from Human Feedback (RLHF) help align model outputs with human preferences. Fine-tuning reduces harmful outputs, improves instruction-following, and makes models more helpful and honest.

graph LR
    A[Raw Text Data<br/>Trillions of Tokens] --> B[Pre-training<br/>Next Token Prediction]
    B --> C[Base Model<br/>Raw Capabilities]
    C --> D[Supervised Fine-tuning<br/>Curated Examples]
    D --> E[RLHF<br/>Human Feedback]
    E --> F[Aligned Model<br/>Helpful & Safe]

    style B fill:#FF851B
    style D fill:#0074D9
    style E fill:#2ECC40

Why They’re So Capable

The capability of modern LLMs emerges from scale, architecture, and training data. Research has shown that performance improves predictably as models grow larger and train on more data—a phenomenon called scaling laws. With enough parameters and training data, these models develop unexpected abilities, sometimes called emergent capabilities.

For instance, LLMs weren’t explicitly programmed to write code, summarize text, or translate languages. Yet with sufficient scale, they spontaneously developed these skills. Few-shot learning is another emergent ability: models can adapt to new tasks with just a few examples, rather than requiring retraining.

This happens because language encodes knowledge about the world. When an LLM learns that “Paris is in France” appears frequently in training data, it internalizes this relationship. Scaling and diverse training data compound this effect, enabling models to handle complex reasoning, creative tasks, and specialized domains.

graph TD
    A[Scale: Parameters + Data] --> B[Basic Language Understanding]
    B --> C[Emergent Capabilities]
    C --> D[Code Generation]
    C --> E[Translation]
    C --> F[Few-shot Learning]
    C --> G[Complex Reasoning]
    C --> H[Creative Writing]

    style A fill:#B10DC9
    style C fill:#FF851B
    style D fill:#2ECC40
    style E fill:#2ECC40
    style F fill:#2ECC40
    style G fill:#2ECC40
    style H fill:#2ECC40

The Limitations

Understanding what LLMs cannot do is equally important. Despite their sophistication, they have fundamental limitations:

LLMs are pattern-matching systems, not reasoning engines. They can produce plausible-sounding text that is factually incorrect—a phenomenon called hallucination. They cannot access real-time information or maintain true long-term memory across conversations. Their outputs reflect biases present in training data. They sometimes struggle with novel problems that don’t match learned patterns.

Additionally, LLMs have finite context windows—maximum amounts of text they can process at once. This limits their ability to handle very long documents or maintain extended conversations.

Looking Forward

LLMs represent a significant step forward in AI, but they’re not the final answer. Researchers are exploring hybrid approaches combining LLMs with retrieval systems, symbolic reasoning, and other techniques to address current limitations. The field continues to evolve rapidly, with improvements in efficiency, alignment, and capability.

Understanding how LLMs work—their strengths and limitations—is essential for anyone working with or relying on modern AI systems. They’re powerful tools, not oracles, and using them effectively requires realistic expectations about their nature and capabilities.

]]> <![CDATA[Respond to Twilio Webhooks using AWS Lambda and .NET]]> 2026-08-05T13:00:00+00:00 https://volkanpaksoy.com/archive/2026/08/05/Respond-to-Twilio-Webhooks-using-AWS-Lambda-and-dotNET

This article was originally published on the Twilio Blog.

In this article, you will learn how to develop a web API with .NET 6 to handle Twilio webhooks and deploy it to AWS Lambda. You will also learn how to save call recordings to AWS S3 as MP3 files.

Prerequisites

What are webhooks?

In today’s API-driven world, integrating applications is easier than ever. Most of the time, you can get the information you need from an external system’s API, but sometimes you want to be notified by the external system when something happens. That’s where webhooks come in. You register your own endpoint with the external system, and they post data to your endpoint when the event you’re looking for occurs.

Twilio Webhooks

The type of data you can expect from webhooks depends on the Twilio service. For the Twilio Voice API, there are several types of webhooks, three of which you’ll use in this tutorial:

  • Incoming voice call

  • Status callback

  • Recording status callback

Incoming voice call webhook, as the name implies, is where you handle the incoming calls. When you use a programmable voice service such as Twilio, this is the core functionality you would want to implement. If you don’t handle the incoming call, you hear three beeps when you call your Twilio number, and the call is terminated. The call doesn’t even appear in the logs. As you will see later in this article, when you implement a call handler, you can provide instructions to Twilio to record the call, play audio, and more. Some of these actions also have their own follow up webhooks. These instructions are implemented in TwiML (the Twilio Markup Language). TwiML is an XML-based markup language that has elements such as Say (read text to the caller), Dial (add another party to the call) and Record (record the caller’s voice). You will use Say and Record in your project later.

After a call has been completed (inbound or outbound), Twilio sends an HTTP request to your endpoint. This is called the status callback.

You could receive the recording status callback if you requested to record the call. Then, Twilio sends your endpoint a message with the recording status and a URL to access the recording file. You have to specify your webhook URL to handle this callback message.

!!!warning

By default, Recording URLs don’t require authentication, and recordings are not encrypted. However, you can require basic authentication to access the recordings and configure recordings to be encrypted in the voice settings (Voice → Settings → General).

!!!

In this tutorial you will interact with the Twilio Voice product, but many other products also use webhooks and you can apply the same technique for them as you will for Voice.

Now that you’ve learned about these three webhooks, let’s move on to the next section.

Set up AWS IAM User

You will need credentials to deploy your application to AWS from the command line. To create the credentials, follow the steps below:

First, go to the AWS IAM Users Dashboard and click the Add users button.

Enter the user name such as twilio-webhook-user and tick the Access key - Programmatic access checkbox:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 1

Click the Next: Permissions button at the bottom right.

Then, select Attach existing policies directly and select AdministratorAccess:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 2

Click the Next: Tags button at the bottom right. Tags are optional (and quite valuable information), and it’s a good practice to add descriptive tags to the resources you create. Since this is a demo project, you can skip this step and click the Next: Review button at the bottom.

Confirm your selection on the review page. It should look like this:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 3

Then, click the Create user button.

In the final step of the user creation process, you should see your credentials for the first and the last time.

!!!warning

Take note of your Access key ID and Secret access key before you press the close button.

!!!

Now, open a terminal window and run the following command:

aws configure

You should see a prompt for AWS Access Key ID. Copy and paste your access key ID and press enter.

Then, copy and paste your secret access key and press enter.

Respond to Twilio Webhooks using AWS Lambda and .NET - image 4

When prompted, type us-east-1 as the default region name and press enter.

!!!info

In this example, I will use the us-east-1 region. Regions are geographical locations where AWS have their data centers. It is a good practice to deploy as close to your customers as possible for production deployments to reduce latency. Since this is a demo project, you can use us-east-1 for convenience as it’s the default region in AWS Management Console. You can find more on AWS regions in this document: Regions and Availability Zones.

!!!

As the default output format, type json and press enter.

To confirm you have configured your AWS profile correctly, run the following command:

aws configure list

The output should look like this:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 5

Now that you have set up your AWS credentials, you can move on to setting up the code.

Create an ASP.NET Core project for AWS Lambda

You can download the finished project from GitHub. However, this article will provide step-by-step instructions to set it up yourself.

Open a terminal and navigate to the directory that will be the root of your project.

You will use the Lambda ASP.NET Core Web API project template in the sample project. So, first, install Lambda templates by running the following command:

dotnet new -i Amazon.Lambda.Templates

You should see the results of a successful installation:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 6

Take note of the short name of Lambda ASP.NET Core Web API: serverless.AspNetCoreWebAPI.

Then, run the following command to create the project:

dotnet new serverless.AspNetCoreWebAPI --name TwilioWebhookLambda.WebApi --output .

The command above will create a new project with the following file structure:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 7

Note that the template creates a folder named src and puts the project in that folder. You can move the code to your root folder, but the rest of the article will use the default paths.

You will leverage a new AWS Lambda feature called Function URLs to make the function publicly available. For this to work with your API you need to install the Amazon.Lambda.AspNetCoreServer.Hosting NuGet package. In the terminal window, navigate to the project folder and run:

cd src/TwilioWebhookLambda.WebApi
dotnet add package Amazon.Lambda.AspNetCoreServer.Hosting

Then, open Startup.cs in your IDE, update the ConfigureServices method so that it looks like this:

```csharp hl_lines=”4” public void ConfigureServices(IServiceCollection services) { services.AddControllers(); services.AddAWSLambdaHosting(LambdaEventSource.HttpApi); }


Lambda Function URLs use HttpApi behind the scenes, so you need to use `LambdaEventSource.HttpApi` as the event source type.

You will need the Amazon Lambda Tools .NET tool to deploy the function via the command line. You can install it by running the command below:

```bash
dotnet tool install -g Amazon.Lambda.Tools

Amazon Lambda Tools, use the aws-lambda-tools-defaults.json file to get some details about the installation. Unfortunately, it doesn’t come with all the values it needs. For example, you can store the runtime and the function’s name in this file, so you don’t have to keep entering it whenever you deploy it from scratch.

Open the file and update it so that it looks like this:

{
  "profile": "",
  "region": "",
  "configuration": "Release",
  "function-runtime": "dotnet6",
  "function-memory-size": 256,
  "function-timeout": 30,
  "function-handler": "TwilioWebhookLambda.WebApi",
  "function-name": "TwilioWebhookLambda-WebApi",
  "function-url-enable": true
}

If you don’t provide profile and region values, it uses the default profile and region in your AWS configuration. If you want to override the defaults, update those values as well.

Then, deploy the Lambda function by running the following command:

dotnet lambda deploy-function

Your Lambda function needs an IAM role to execute. The policies attached to this role determine the permissions of the function. By default, the Amazon Lambda Tools create a role on your behalf and attach it to the function.

During the deployment, it lists the existing roles along with an option to create a new role:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 8

Select the Create new IAM Role option.

Give it a descriptive name, such as TwilioWebhookLambda-WebApi-Role, so that you can easily determine its purpose when you see it in your IAM dashboard.

The next step is to select the IAM policy. Your project will need Amazon S3 access to store call recordings. Also, having access to CloudWatch logs is always helpful. So choose 3 - AWSLambdaExecute from the list:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 9

!!!info

As a best practice, you should develop custom policies to grant only the minimum required permissions.

!!!

After the deployment has finished, you should see the successful deployment message:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 10

The publicly available URL shown above is only created because you enabled the Function URL feature in the aws-lambda-tools-defaults.json file.

"function-url-enable": true

Without this feature, you wouldn’t be able to use a Lambda function as a webhook handler.

Now open that URL in a browser and you should see the default GET / endpoint result:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 11

The API works like any other API. This template comes with a sample controller called ValuesController. Test the controller by appending /api/values to your function URL:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 12

You should see an array of strings (value1 and value2) displayed on your browser.

You just deployed your ASP.NET Core web API to Lambda and made it publicly available. Great job!

Receive Incoming Calls

The Twilio .NET SDK and the helper library for ASP.NET make it easier to build Twilio applications. In this tutorial, you’ll use the SDK to generate TwiML and the helper library to respond to webhook requests. Add the SDK and helper library via NuGet:

dotnet add package Twilio
dotnet add package Twilio.AspNet.Core

Under the Controllers folder, add a new file called IncomingCallController.cs and replace its contents with the following code:

using Microsoft.AspNetCore.Mvc;
using Twilio.AspNet.Core;
using Twilio.TwiML;
namespace TwilioWebhookLambda.WebApi.Controllers;
[ApiController]
[Route("api/[controller]")]
public class IncomingCallController : TwilioController
{
    [HttpPost]
    public TwiMLResult Index()
    {
        var response = new VoiceResponse();
        response.Say("Hello. Please leave a message after the beep.");
        return TwiML(response);    
    }
}

In the terminal, deploy the updated function:

dotnet lambda deploy-function

You should get a successful update message on your screen:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 13

At this point, you have a publicly available endpoint but Twilio is not aware of it yet.

Go to the Twilio console. Select your account, and then click Phone Numbers → Manage → Active Numbers on the left pane. (If Phone Numbers isn’t on the left pane, click on Explore Products and then on Phone Numbers.)

Respond to Twilio Webhooks using AWS Lambda and .NET - image 14

!!!warning

You don’t permanently own Twilio numbers; instead, you lease them until you release them. If you release a number after a 10-day grace period, it is returned to the number pool.

!!!

Click on the phone number you want to use for your project and scroll down to the Voice section.

Under the “A Call Comes In” label, set the dropdown to Webhook, the text field next to it to your Lambda Function URL suffixed with the /IncomingCall path, the next dropdown to HTTP POST, and click Save. It should look like this:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 15

To test, call your Twilio number, and you should hear the message “Hello. Please leave a message after the beep.”. It doesn’t actually wait for the message, but at least you know you have implemented an incoming voice webhook. Your code is executed when your Twilio number receives a call.

In the next section, you will handle the second webhook type: Call Status Updates.

Receive Call Status Updates

Create a new file in the Controllers folder called CallStatusChangeController.cs with the code below:

using Microsoft.AspNetCore.Mvc;
using Twilio.AspNet.Core;
namespace TwilioWebhookLambda.WebApi.Controllers;
[ApiController]
[Route("api/[controller]")]
public class CallStatusChangeController : TwilioController
{
    private readonly ILogger<CallStatusChangeController> _logger;
    public CallStatusChangeController(ILogger<CallStatusChangeController> logger)
    {
        _logger = logger;
    }
    [HttpPost]
    public async Task Index()
    {
        var form = await Request.ReadFormAsync();
        var to = form["To"];
        var callStatus = form["CallStatus"];
        var fromCountry = form["FromCountry"];
        var duration = form["Duration"];
        _logger.LogInformation(
            "Message to {to} changed to {callStatus}. (from country: {fromCountry}, duration: {duration})",
            to, callStatus, fromCountry, duration);
    }
}

This code logs some of the values posted to your webhook.

Go back to the active number configuration in the Twilio Console and update the “Call Status Changes” field with your Lambda Function URL suffixed with /CallStatusChange, as shown below:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 16

Save your configuration, and then deploy your project again using dotnet lambda deploy-function.

Now call your Twilio number again, and after the call has been completed, you should see the callback logs in CloudWatch:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 17

You received this message when the call status changed to “completed”.

You can also use the Twilio console to view all call logs: Click Monitor → Calls on the left pane.

Locate the call in the list and click the Call SID link to view the details.

Respond to Twilio Webhooks using AWS Lambda and .NET - image 18

In the Request Inspector section, you can see all the callbacks with their requests and responses in detail:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 19

Next, you will look into the third and final type of voice webhook: Recording Status Updates.

Receive Recording Status Updates

!!!warning

Before you record anything, please make sure to read this article: Legal Considerations with Recording Voice and Video Communications.

!!!

Create a new controller called RecordingStatusChangeController and replace its contents with the code below:

using Microsoft.AspNetCore.Mvc;
using Twilio.AspNet.Core;
namespace TwilioWebhookLambda.WebApi.Controllers;
[ApiController]
[Route("api/[controller]")]
public class RecordingStatusChangeController : TwilioController
{
    private readonly ILogger<RecordingStatusChangeController> _logger;
    public RecordingStatusChangeController(ILogger<RecordingStatusChangeController> logger)
    {
        _logger = logger;
    }
    [HttpPost]
    public async Task Index()
    {
        var form = await Request.ReadFormAsync();
        var callSid = form["CallSid"];
        var recordingStatus = form["RecordingStatus"];
        var recordingUrl = form["RecordingUrl"];
        _logger.LogInformation(
            "Recording status changed to {recordingStatus} for call {callSid}. Recording is available at {recordingUrl}"
            ,recordingStatus, callSid, recordingUrl);
    }
}

Similar to the status change handler, this code only logs some request details. Once you’ve seen all webhooks are working fine, you will update the implementation with more meaningful code.

You also need to modify the IncomingCallController and replace the code in the Index method as below:

var response = new VoiceResponse();
response.Say("Hello. Please leave a message after the beep.");
response.Record(
    timeout: 10, 
    recordingStatusCallback: new Uri("/api/RecordingStatusChange", UriKind.Relative)
);
return TwiML(response);

Now you’re telling Twilio that you’d like to record the phone call. You are also specifying the webhook URL that will receive the recording status update. Unlike the other webhook types, there is no field in the Twilio console to set the recording status callback.

Deploy this update and call your number again. This time you should be able to leave a message after the beep. Once you’ve done that, check your CloudWatch logs, and you should see two status updates: One for the call status and one for the recording status:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 20

As you can see in the logs, the recording URLs are public by default, but the recordings have long random names, so they cannot be iterated through and downloaded by unauthorized parties. To increase the security of the recordings, you can enable Enforce HTTP Auth on Media URLs and Voice Recording Encryption options in Voice Settings in your account.

Save Recording MP3 files to an Amazon S3 Bucket

Now let’s see how you can retrieve the recording file and upload it to an Amazon S3 bucket from your ASP.NET Core project.

!!!info

As of May 2022, Twilio has a built-in feature to store recordings in an Amazon S3 bucket. In this article, however, you will use a different approach and upload the MP3 files programmatically from your Lambda function.

!!!

First, you will need an S3 bucket to store the files. To create the bucket, go to AWS Management Console and search for S3:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 21

Then, click the link to go to the S3 service dashboard.

Click Create Bucket button:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 22

Give it a descriptive and globally unique name, accept all the defaults and click the Create Bucket button at the bottom of the screen.

You should see your bucket in the bucket list:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 23

!!!info

Amazon S3 bucket names are global. If somebody else created a bucket named my-twilio-call-recordings, you can not also use that name. You can find more bucket naming rules in AWS Documentation.

!!!

In your application, you need to install the AWS SDK packages to talk to the Amazon S3 API.

In the terminal, run the following command:

dotnet add package AWSSDK.S3

Update the RecordingStatusChangeController code as below:

using Amazon.S3;
using Amazon.S3.Transfer;
using Microsoft.AspNetCore.Mvc;
using Twilio.AspNet.Core;
namespace TwilioWebhookLambda.WebApi.Controllers;
[ApiController]
[Route("api/[controller]")]
public class RecordingStatusChangeController : TwilioController
{
    [HttpPost]
    public async Task Index()
    {
        string recordingUrl = Request.Form["RecordingUrl"];
        string fileName = $"{recordingUrl.Substring(recordingUrl.LastIndexOf("/") + 1)}.mp3";
        string bucketName = "my-twilio-call-recordings";
        using HttpClient client = new HttpClient(); // use HttpClient factory in production
        using HttpResponseMessage response = await client.GetAsync($"{recordingUrl}.mp3");
        using Stream recordingFileStream = await response.Content.ReadAsStreamAsync();
        using var s3Client = new AmazonS3Client();
        using var transferUtility = new TransferUtility(s3Client);
        await transferUtility.UploadAsync(recordingFileStream, bucketName, fileName);
    }
}

Make sure to set the bucketName with your bucket’s name.

In this code, when you receive the recording URL, you extract the recording file name, retrieve the file content via a stream and pass the stream to S3 TransferUtility which uploads it to the Amazon S3 bucket as {fileName}.mp3.

!!!info

By default, the recording URL doesn’t have a file extension. If you call the URL as is, Twilio returns the WAV version of the recording. To get the MP3 version, you need to append .mp3 to the URL as shown in client.GetAsync call.

!!!

During the setup process, you didn’t explicitly tell AWS that your Lambda function should have access to your S3 bucket. So you might be wondering how you have permission to do that. The reason is you chose AWSLambdaExecute policy to be attached to your function’s role. So if you go to the IAM dashboard and search AWSLambdaExecute, you should see the policy’s permissions are defined like this:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 24

You can see that this policy has permission to put objects into all S3 buckets. Since this is a demo project, I decided to keep things simple. However, in production, I’d recommend writing your own policy and giving the minimum required permissions, such as using the names of the resources instead of using wildcards. You can read more on that here: IAM Best Practices: Apply least-privilege permissions

Deploy the final version of the API and call your number again.

A short while after you’ve completed the call, you should see the recording in your bucket:

Respond to Twilio Webhooks using AWS Lambda and .NET - image 25

!!!warning

As the focus of this article is using AWS Lambda to respond to Twilio webhooks, securing your endpoint is not covered in this article. To learn more about Webhooks Security, you can read this article: Webhooks Security.

!!!

Conclusion

Congratulations! You covered three types of webhooks for the Twilio Voice service and implemented handlers for all of them. In addition, you managed to download recordings to your own storage. Later on, you can download or move the files to cold storage using Amazon S3 Glacier. The possibilities are endless when you can manage all of this programmatically. For example, you could use Amazon Transcribe to transcribe the call recording to text, or you could use Twilio’s transcribe attribute on the record-verb.

If you didn’t follow along and implement the project, don’t worry. You can always download the final project from my GitHub repository and experiment on your own.

If you enjoyed playing with call recordings and webhooks using Twilio API, I’d recommend you take a look at these articles as well:

]]> <![CDATA[Make a Spooky Phone Call using Twilio Voice and Amazon Polly]]> 2026-08-05T12:55:00+00:00 https://volkanpaksoy.com/archive/2026/08/05/Make-a-Spooky-Phone-Call-using-Twilio-Voice-and-Amazon-Polly

This article was originally published on the Twilio Blog.

Technology provides us with countless benefits, and as programmers, we should better ourselves to produce more value all the time. But then again, there are certain seasons in a year when you should just relax and have fun with your skills. In this tutorial, you will use Amazon Polly to create audio files from text, add some optional (ideally spooky) sound effects and play that file to your friends using Twilio Voice and .NET.

!!!warning

Needless to say, all this is meant to be is just some harmless fun between you and your loved ones. Do NOT use it if you’re not sure it will be well-received by the person you call. In a production scenario, make your users opt-in before sending them text messages or automated phone calls.

!!!

Prerequisites

You’ll need the following things in this tutorial:

Project Overview

Let’s take a look at how the application will work.

  • You come up with a message that will sound scary/ominous. You can personalize it by adding your friend’s name or something private in the message to increase the impact.

  • You create an audio file using Amazon Polly based on your crafted text.

  • Optional (but recommended as it makes the experience more fun), you use ffmpeg to add some effects to your audio to add more spookiness.

  • You upload the final audio to Amazon S3.

  • You call your friend and play the audio by using Twilio Voice.

Now that you understand how the application will work let’s get started.

Set up AWS IAM User

You will need credentials to deploy your application to AWS from the command line. To create the credentials, follow the steps below:

First, go to the AWS IAM Users Dashboard and click the Add users button.

Enter the user name, such as twilio-webhook-user and tick the Access key - Programmatic access checkbox:

Make a Spooky Phone Call using Twilio Voice and Amazon Polly - image 1

Click the Next: Permissions button at the bottom right.

Then, select Attach existing policies directly and select AdministratorAccess:

Make a Spooky Phone Call using Twilio Voice and Amazon Polly - image 2

Click the Next: Tags button at the bottom right. Tags are optional (and quite valuable information), and it’s a good practice to add descriptive tags to the resources you create. Since this is a demo project, you can skip this step and click the Next: Review button at the bottom.

Confirm your selection on the review page. It should look like this:

Make a Spooky Phone Call using Twilio Voice and Amazon Polly - image 3

Then, click the Create user button.

In the final step of the user creation process, you should see your credentials for the first and the last time.

!!!warning

Take note of your Access key ID and Secret access key before you press the close button.

!!!

Now, open a terminal window and run the following command:

aws configure

You should see a prompt for AWS Access Key ID. Copy and paste your access key ID and press enter.

Then, copy and paste your secret access key and press enter.

Make a Spooky Phone Call using Twilio Voice and Amazon Polly - image 4

When prompted, type us-east-1 as the default region name and press enter.

!!!info

In this example, I will use the us-east-1 region. Regions are geographical locations where AWS have their data centers. It is a good practice to deploy as close to your customers as possible for production deployments to reduce latency. Since this is a demo project, you can use us-east-1 for convenience as it’s the default region in AWS Management Console. You can find more on AWS regions in this document: Regions and Availability Zones.

!!!

As the default output format, type json and press enter.

To confirm you have configured your AWS profile correctly, run the following command:

aws configure list

The output should look like this:

Make a Spooky Phone Call using Twilio Voice and Amazon Polly - image 5

Now that you have set up your AWS credentials, you can move on to setting up the code.

Create S3 Bucket to Store MP3 Files

The audio files you create and modify locally won’t be accessible for Twilio to play. To fix that issue, you will need a public storage area. In this tutorial, you will use an Amazon S3 bucket for storage.

In a terminal window, run the following command to create a new bucket:

aws s3api create-bucket --bucket  {Your bucket name}

!!!info

{Your bucket name} has to follow these bucket naming rules documented by AWS.

!!!

This bucket will be used by Amazon Polly to store text-to-speech outputs. Also, you’re going to upload modified audio files to this bucket as well.

For Polly to store outputs in this bucket, you need to give write permissions to it. This can be achieved by setting the bucket policy as below:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicRead",
      "Effect": "Allow",
      "Principal": "*",
      "Action": [
        "s3:GetObject",
        "s3:PutObject"
      ],
      "Resource": [
        "arn:aws:s3:::{Your bucket name}",
        "arn:aws:s3:::{Your bucket name}/*"
      ]
    }
  ]
}

Store the above JSON in a file such as policy.json and replace {Your bucket name} with the actual name of your S3 bucket.

Then, run the following command to update permissions on the bucket:

aws s3api put-bucket-policy --bucket {Your bucket name} --policy file://policy.json

!!!warning

This policy is too broad, and I’d not recommend it for a serious project, but for a quick and fun project such as this one, it’s fine. After you’ve finished this tutorial, make sure to delete the contents and the bucket itself.

!!!

Create Audio Messages with Amazon Polly

First, let’s focus on preparing the audio message. At this point, you should have an idea of your message to convert to audio.

Start by creating a console application:

mkdir SpookySeasonPrankPrepareAudio
cd SpookySeasonPrankPrepareAudio
dotnet new console

The easiest way to use AWS APIs with C# is to use their .NET SDK. They have a modular structure so you can only include the libraries for the services you will use. In this section, you will use Amazon Polly so go ahead and run the following command to include that package only:

dotnet add package AWSSDK.Polly

Open the project in your IDE and replace the contents of Program.cs with the code below:

using Amazon.Polly;
using Amazon.Polly.Model;
using (var pollyClient = new AmazonPollyClient())
{
    var startSpeechSynthesisTaskRequest = new StartSpeechSynthesisTaskRequest
    {
        Text = "James! I know what you did last summer!. You're not getting away with it this time!",
        VoiceId = VoiceId.Matthew,
        OutputFormat = OutputFormat.Mp3,
        OutputS3BucketName = "{Your bucket name}",
        OutputS3KeyPrefix = "polly-output",
    };
    await pollyClient.StartSpeechSynthesisTaskAsync(startSpeechSynthesisTaskRequest);
}

This message is crafted for my imaginary friend James. I don’t know anybody named James, so it’s just a test name that I used. Tailor your spooky message to achieve your own “evil” goal! 🎃

You can also change the voice that Amazon Polly is going to use. Again, there are no right or wrong answers here. Just play around with the options and use the ones you like.

Run the application using dotnet run.

Now open Amazon Polly dashboard, and you should see your synthesis task:

Make a Spooky Phone Call using Twilio Voice and Amazon Polly - image 6

It also shows the URL of the output file. Download the file by using AWS CLI:

aws s3api get-object --bucket {Your bucket name} --key polly-output.{Your task ID}.mp3 polly-output-original.mp3

Replace the placeholders for the bucket name and task ID. You can use any name for the local file name.

You can find the MP3 files on the project’s GitHub repository.

Now that you have a semi-spooky customized audio message, move on to the next section to add effects to spook it up a notch!

Audio Effects with ffmpeg

I’m by no means an expert in audio mixing and editing. So if you are blessed with those skills, feel free to do your thing and move on to the next section.

In this tutorial, you will add a rather spooky background to the previous audio generated by Amazon Polly.

One good resource for finding free assets is pixabay.com. The sound clip I used in this tutorial is called Halloween Impact 05 by Charlie Raven. Open the link in a new tab and the download should start automatically. Alternatively, you can go to pixabay.com directly, search for the name of the audio and click the Download button next to it.

Copy the downloaded file next to the Polly-generated file (polly-output-original.mp3) and run the following command in a terminal window in the same folder:

ffmpeg -i polly-output-original.mp3 -i halloween-impact-05-93808.mp3 -filter_complex "[1:a]adelay=2s:all=1[a1];[0:a][a1]amix=inputs=2[a]" -map "[a]" output.mp3

The command above merges both files and adds a 2-second delay to the background audio. This delay is to avoid the loud sound drowning out the name.

This is where you can get creative and experiment with various combinations to produce the scariest results. Once you’re happy with the result, upload it your S3 bucket by running the command below:

aws s3api put-object --bucket {Your bucket name} --key output.mp3 --body output.mp3 --content-type audio/mpeg

Create a Console Application to Use Twilio Voice

Now that you have your final audio ready, the last step is to call your “victim” and play it.

To achieve this, create a new console application.

Back in your terminal window, run the following commands:

cd ..
mkdir SpookySeasonPrank
cd SpookySeasonPrank
dotnet new console

Then, while still in the terminal, add Twilio .NET SDK via NuGet:

dotnet add package Twilio

Twilio SDK makes it easy to generate TwiML and interact with Twilio API.

To make phone calls using Twilio API, you will need your Account Sid and Auth Token, which you can obtain from the Twilio Console.

Open the Twilio Console and log in to your account.

In the welcome screen, you should see your Account SID and Auth Token at the bottom in the Account Info section:

Make a Spooky Phone Call using Twilio Voice and Amazon Polly - image 7

You can use environment variables or a vault service to store these values, but for local development, you can use dotnet user secrets by running the following command:

dotnet user-secrets init

Then, add your Account SID and Auth Token by replacing the placeholders with actual values and running the commands below:

dotnet user-secrets set Twilio:AccountSid {Your Account Sid}
dotnet user-secrets set Twilio:AuthToken {Your auth Token}

Storing them in user secrets would not help much if you didn’t have a way to retrieve them. To get the values back, you’re going to use the .NET configuration builder which is in Microsoft.Extensions.Configuration NuGet package.

In the terminal, add the following configuration extension libraries:

dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.UserSecrets

You can also add command line or environment variable providers, but you won’t use them in this example.

Open the project with your IDE and update Program.cs with the code below:

using Microsoft.Extensions.Configuration;
using Twilio;
using Twilio.Rest.Api.V2010.Account;
IConfiguration config = new ConfigurationBuilder()
    .AddUserSecrets<Program>(optional: true, reloadOnChange: false)
    .Build();
var twilioAccountSid = config["Twilio:AccountSid"];
var twilioAuthToken = config["Twilio:AuthToken"];
TwilioClient.Init(twilioAccountSid, twilioAuthToken);
CallResource.Create(
    url: new Uri("https://{Your bucket name}.s3.amazonaws.com/output.mp3"),
    method: Twilio.Http.HttpMethod.Get, 
    to: new Twilio.Types.PhoneNumber("{Your victim's phone number}"),
    from: new Twilio.Types.PhoneNumber("{Your Twilio Phone Number}")
);

Replace {Your bucket name}, {Your victim’s phone number} and {Your Twilio Phone Number} with the actual values. You can obtain your Twilio phone number from Twilio Console (It should be shown right below your Account SID and Auth Token).

I’d recommend testing the application with your phone first. Once you’ve confirmed your message sounds as scary as you wanted to sound, you can replace your number with your victim’s phone number and execute your evil plan by running:

dotnet run

Happy Spooky Season!

Conclusion

I hope you enjoyed following this tutorial as much as I enjoyed writing it. Having programmatic access to phone calls and SMS messages opens many possibilities. Combined with other cloud services, you can quickly create a wide variety of projects. If you enjoy developing with Twilio and .NET, you might want to take a look at these articles too:

]]> <![CDATA[How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates]]> 2026-08-05T12:50:00+00:00 https://volkanpaksoy.com/archive/2026/08/05/How-to-send-RSS-feed-digest-email-with-CSharp-and-SendGrid-Dynamic-Email-Templates

This article was originally published on the Twilio Blog.

In this article, you will learn how to create a nicely formatted dynamic email using the Twilio Blog RSS feed as source data and send it via the SendGrid API. You will first look into creating the template with test data. Then you will learn how to parse RSS and HTML and send the emails with dynamic data.

Prerequisites

You’ll need the following things for this tutorial:

Create a Dynamic Email Template

Follow the steps below to create the dynamic email template for RSS feed digest email:

Go to the Dynamic Templates dashboard and click Create a Dynamic Template. How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 1

Enter the name of your template (e.g. blog-rss-feed-digest-email) and click Create. How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 2

Expand your template and click Add Version. How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 3

Hover over Blank Template and click the Select button. How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 4

Click the Select button in the Design Editor section. How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 5

Update Version Name to version-1, and then update the Subject to {{subject}}.

Delete the Unsubscribe module by hovering over it and clicking the trash can icon.

How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 6

Confirm the deletion by clicking Confirm button in the dialog box.

How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 7

!!!warning

The sample application shown in this article is meant to be used for learning purposes only. It’s meant to send emails to yourself. If you intend to send emails to third parties, make sure to click Learn more button in the dialog or visit SendGrid documentation on Global Unsubscribes and Group Unsubscribes.

!!!

Now click the Build tab and drag the Code module into the design area that says Drag Module Here. How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 8

The edit module screen will automatically appear. Paste the following code inside the editor and click Update.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <style>
        body { background-color: lightyellow; }
        h2, h3 { color: green; margin-left: 40px; }
        table { border-collapse: collapse; }
        tr.separated td { border-top: 1px dashed black; padding: 5px; }
        a { text-decoration: none; }
        .postTitle { font-size: 20px; }
        .readMoreButton {
            background-color: #04AA6D;
            border: none;
            color: white;
            padding: 8px;
            text-align: center;
            text-decoration: none;
            display: inline-block;
            font-size: 12px;
            margin: 4px 2px;
            cursor: pointer;
            border-radius: 2px;
        }
        .headerImage { padding-right: 10px; }
    </style>
</head>
<body>
<div>
    <h2>Hello, {{recipientName}}</h2>
    <h3>Here are the latest blog posts from Twilio Blog:</h3>
    {{#each blogPostList}}
    <table>
        <tr class="separated">
            <td><img class="headerImage" src="{{this.headerImageUrl}}" width="200" height="112"></td>
            <td>
                <a class="postTitle" href="{{this.Link}}"> {{this.title}} </a>
                <p>by <b>{{this.author}}</b> - <b>{{this.publishDate}}</b></p>
                {{#if this.categories}}
                    <p>Categories: {{this.categories}}</p>
                {{/if}}
                <p>{{{this.description}}}</p>
                <p>
                    <a class="readMoreButton" href="{{this.link}}">Read more</a>
                </p>
            </td>
        </tr>
    </table>
    {{/each}}
</div>
<div>
    <h2>Last Build Date: {{lastBuildDate}}</h2>
</div>
</body>
</html>

Click Save in the top menu.

How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 9

Handlebars Templating Language

SendGrid uses the Handlebars Templating Language to handle variable substitution and add some logic to the templates. You can find all the supported features on SendGrid documentation: Using Handlebars. You might also want to check out this article which also uses Handlebars templating.

Let me show you some of the Handlebars features used in the dynamic email template.

Conditionals

Twilio blog posts can belong to multiple categories. Also, in some cases, they don’t have any categories. So, instead of showing a blank Categories line in the email, you can hide the line if the post does not have any categories.

To check if a string is empty or not, we can use a simple if statement as shown below:

{{#if this.Categories}}
  <p>Categories: {{this.Categories}}</p>
{{/if}}

If the value of this.Categories variable is an empty string, it evaluates to false. In that case, the p element will be hidden.

HTML Injection

As you will see later in the Parsing HTML section, the full HTML post is included in the XML, and you will parse the first paragraph as HTML. In the email, you need to embed this block as HTML; otherwise, it would look broken if other HTML elements were inside the paragraph.

To inject HTML, you can just use triple curly braces as shown below:

<p>{{{this.Description}}}</p>

!!!warning Keep in mind that whenever you are using three curly braces, the variable will not be encoded and susceptible to HTML injection. If this variable holds user input, this can be risky! Make sure to use the HtmlEncoder in .NET to encode user input before passing it into the three curly braces. !!!

Iterations

In the example, you will send an RSS feed digest, meaning there will be multiple blog post sections in the email. Handlebars supports arrays and iterations. You can access each item in the array by using the each keyword. In the example, you did this for the blogPostList array:

{{#each blogPostList}}
…
<p>{{{this.Description}}}</p>
…
{{/each}}

Between {{#each blogPostList}} and {{/each}}, you can access each item in the array by using the this keyword.

Test the Template

The SendGrid designer allows you to preview the rendered output by using hard-coded test data. This is a handy feature as you get to see all the variable substitutions in action right in the designer.

To test your template, click the Preview button in the top menu. You should see something like this:

How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 10

Next, click Show Test Data to open the data panel on the left.

I obtained some test data manually from the actual Twilio Blog to make the test more realistic. Paste the following JSON into the data panel:

{
  "subject": "Latest Posts - 07 July 2022",
  "recipientName": "Volkan",
  "lastBuildDate": "7 July 2022, 12:34",
  "blogPostList": [
    {
      "title": "Automatically Forward Text Messages with No Code Using Twilio Studio",
      "link": "https://www.twilio.com/blog/automatically-forward-text-messages-no-code-studio",
      "headerImageUrl": "https://twilio-cms-prod.s3.amazonaws.com/images/Copy_of_C03_Blog_Text_2.width-808.png",
      "description": "This article explains how to forward any incoming text messages sent to your Twilio phone number to another number automatically using a no-code solution called Twilio Studio.",
      "author": "Ashley Boucher",
      "publishDate": "06 July 2022",
      "categories": [
        "Code, Tutorials and Hacks"
      ]
    },
    {
      "title": "Super SIM now offers VPN connectivity for your IoT devices",
      "link": "https://www.twilio.com/blog/vpn-iot-devices",
      "headerImageUrl": "https://twilio-cms-prod.s3.amazonaws.com/images/VPN_-_Social_Banner.width-808.png",
      "description": "I am excited to announce that Super SIM now has VPN (Virtual Private Network) support, enabling you to set up secure private networks between Twilio and your application data centers and have your Super SIM connected devices use these private networks. With regular Internet breakout, the traffic from devices using Super SIM will go over the Internet and get routed to your application data center. When VPN is used, the same traffic is sent over a secure and private tunnel as shown below:",
      "author": "Vijay Devarapalli",
      "publishDate": "06 July 2022",
      "categories": []
    }
  ]
}

You should now see the rendered output on the right-hand side:

How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 11

As you can see, by using the preview feature, you can see the final output without writing any code and sending any emails. Even though the preview is quite accurate, you might want to see it in your inbox as an email. You can also do that in the designer.

Click the Design button on the top menu.

Then, expand Test Your Email section on the left panel:

How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 12

By default, the From Address field is populated by the email address you used when you created your SendGrid account. However, you can replace it with your verified sender address if you like.

Fill in the Email Addresses field with your recipient’s email address. You can test up to 10 recipients.

Click Send Test Message button. Then, check your inbox, and you should see an email that looks like this:

How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 13

It looks like the real thing, except that SendGrid prepends the subject with “Test - “.

So far, you have developed an email template, reviewed the rendered output and sent out actual emails using the designer. Now, it’s time to write some code to send the emails programmatically using the same hard-coded data.

Set up your Project to Send Emails

This tutorial will start from an existing git repository. To get the application up and running, follow the steps below:

Clone the GitHub repository:

git clone https://github.com/Dev-Power/send-rss-feed-digest-email-with-sendgrid-dynamic-templates.git --branch 00-starter-project

Alternatively, you can open the repository, switch to the 00-starter-project branch and then click Code and Download ZIP button.

How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 14

As a third option, you can download the zip file by clicking on this link.

Navigate into the project folder:

cd send-rss-feed-digest-email-with-sendgrid-dynamic-templates
cd src/RssFeedDigestEmailer.Cli

To store your SendGrid API key securely, add it to the project user secrets by running the following command:

dotnet user-secrets set SendGridSettings:ApiKey [YOUR_SENDGRID_API_KEY]

Replace [YOUR SENDGRID API KEY] with the SendGrid API key you created earlier.

Update appsettings.json and configure the email settings sections:

"emailSettings": {
    "senderEmailAddress": "",
    "senderDisplayName": "",
    "recipientEmailAddress": "",
    "recipientDisplayName": "",
    "templateId": ""
}

Update

  • senderEmailAddress with your SendGrid sender email address,

  • senderDisplayName with any name that you would like the recipient to see,

  • recipientEmailAddress with the email address you want to email,

  • recipientDisplayName with the name of the recipient,

  • and the templateId with the ID of the template you created earlier. You can obtain the Template ID by expanding it in the dashboard:

How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 15

Now that the project has been set up, review the important parts of the code.

Currently, the project contains an EmailService class to talk to the SendGrid API using the SendGridClient class. It uses a data provider to get the template data. In this example, you have a JsonDataProvider class that looks like this:

public async Task<object> GetEmailData()
{
    string jsonFilePath = "./Data/DummyData.json";
    string rawContents = await File.ReadAllTextAsync(jsonFilePath);
    return JsonConvert.DeserializeObject(rawContents);
}

It reads the data from a hard-coded JSON file named DummyData.json under the Data folder. The contents of DummyData.json are exactly the same as you used in the designer preview.

Having a separate provider for data makes the email service data-agnostic. The SendTemplatedEmail implementation looks like this:

public async Task SendTemplatedEmail()
{
    var dynamicEmailData = await _dataProvider.GetEmailData();
    var from = new EmailAddress(_emailSettings.SenderEmailAddress, _emailSettings.SenderDisplayName);
    var to = new EmailAddress(_emailSettings.RecipientEmailAddress, _emailSettings.RecipientDisplayName);
    var msg = MailHelper.CreateSingleTemplateEmail(from, to, _emailSettings.TemplateId, dynamicEmailData);
    var response = await _sendGridClient.SendEmailAsync(msg);
    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Email has been sent successfully");
    }
}

As the email service does not construct the template data itself, you can use different data by swapping out JsonDataProvider with new classes that implement the IDataProvider interface.

The main program is set up like this:

using IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureHostConfiguration(config =>
    {
        config
            .AddUserSecrets(Assembly.GetExecutingAssembly(), true, false);
    })
    .ConfigureServices((hostBuilderContext, services) =>
    {
        services
            .AddTransient<IEmailService, EmailService>()
            .AddTransient<IDataProvider, JsonDataProvider>();
        services
            .AddSendGrid(options => options.ApiKey = hostBuilderContext.Configuration["SendGridSettings:ApiKey"]);
        services
            .Configure<EmailSettings>(hostBuilderContext.Configuration.GetSection("EmailSettings"));
    })
    .Build();
var emailService = (EmailService) ActivatorUtilities.CreateInstance(host.Services, typeof(EmailService));
await emailService.SendTemplatedEmail();

You can see in the setup, user secrets are added to the configuration by calling the AddUserSecrets method. This is required to read the API key from .NET user secrets as you configured in the previous section.

Also, SendGridClient is added to the Dependency Injection (DI) Container using the SendGrid.Extensions.DependencyInjection NuGet package. This way, you don’t have to instantiate the SendGridClient object manually inside the EmailService.

Finally, note that JsonDataProvider is registered for the IDataProvider interface. When you implement getting dynamic data from the RSS feed, you will only have to change the line below, and you won’t have to touch the EmailService:

.AddTransient<IDataProvider, JsonDataProvider>();

Now that you’ve covered the main parts of the application, go ahead and run by running the command:

dotnet run

If all goes well, you should receive an email shortly that looks like this:

How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 16

It’s almost identical to the one you sent using the SendGrid dashboard, except that the subject is not prepended with “Test - ”.

Next, you will learn how to get the Twilio Blog RSS feed, obtain relevant data from XML and blog post HTML pages, and prepare the dynamic data for the email template.

Get the Twilio Blog RSS Feed

To follow the code explanations below, check out the latest code. While still in the project folder, run:

git checkout main

Alternatively, follow the instructions below to get to the last version of the code:

Under the Services folder, create a new file named TwilioBlogDataProvider.cs and replace its contents with the following:

using Microsoft.Extensions.Options;
using RssFeedDigestEmailer.Cli.Configuration;
using RssFeedDigestEmailer.Cli.Services.Interfaces;
namespace RssFeedDigestEmailer.Cli.Services;
public class TwilioBlogDataProvider : IDataProvider
{
    private readonly IRssService _rssService;
    private readonly EmailDataSettings _emailDataSettings;
    public TwilioBlogDataProvider(IRssService rssService, IOptions<EmailDataSettings> emailDataSettings)
    {
        _rssService = rssService;
        _emailDataSettings = emailDataSettings.Value;
    }
    public async Task<object> GetEmailData()
    {
        var blogInfo = await _rssService.GetBlogInfo();
        return new
        {
            recipientName = _emailDataSettings.RecipientName,
            subject = $"{_emailDataSettings.SubjectPrefix} - {FormatDate(DateTime.Today)}",
            lastBuildDate = FormatDate(blogInfo.LastBuildDate, showTime: true),
            blogPostList = blogInfo.BlogPosts.Select(b => new
            {
                title = b.Title, 
                link = b.Link, 
                headerImageUrl = b.HeaderImageUrl, 
                description = b.Description,
                author = b.Author,
                publishDate = FormatDate(b.PublishDate),
                categories = string.Join("; ", b.Categories) 
            })
        };
        string FormatDate(DateTime date, bool showTime = false)
        {
            return (showTime) ? date.ToString("dd MMMM yyyy, HH:mm") : date.ToString("dd MMMM yyyy");
        }
    }
}

Under Services/Interfaces, create IRssService.cs and paste the following code:

using RssFeedDigestEmailer.Cli.Models;
namespace RssFeedDigestEmailer.Cli.Services.Interfaces;
public interface IRssService
{
    Task<BlogInfo> GetBlogInfo();
}

Under Services, create RssService.cs and paste the following code:

using System.Xml;
using Microsoft.Extensions.Options;
using RssFeedDigestEmailer.Cli.Configuration;
using RssFeedDigestEmailer.Cli.Models;
using RssFeedDigestEmailer.Cli.Services.Interfaces;
namespace RssFeedDigestEmailer.Cli.Services;
public class RssService : IRssService
{
    private readonly IHtmlService _htmlService;
    private readonly IHttpClientFactory _httpClientFactory;
    private readonly RssSettings _rssSettings;
    public RssService(IHtmlService htmlService, IHttpClientFactory httpClientFactory, IOptions<RssSettings> rssSettings)
    {
        _htmlService = htmlService;
        _rssSettings = rssSettings.Value;
        _httpClientFactory = httpClientFactory;
    }
    public async Task<BlogInfo> GetBlogInfo()
    {
        var httpClient = _httpClientFactory.CreateClient("RssServiceHttpClient");
        using (HttpResponseMessage response = await httpClient.GetAsync(_rssSettings.FeedUrl))
        using (var rawRssFeedStream = await response.Content.ReadAsStreamAsync())
        { 
            var xmlDocument = new XmlDocument();
            xmlDocument.Load(rawRssFeedStream);
            var blogInfo = new BlogInfo();
            XmlNode lastBuildDateNode = xmlDocument.SelectSingleNode("/rss/channel/lastBuildDate");
            blogInfo.LastBuildDate = DateTime.Parse(lastBuildDateNode.InnerText);
            XmlNodeList itemNodeList = xmlDocument.SelectNodes("/rss/channel/item");
            XmlNamespaceManager xmlNamespaceManager = new XmlNamespaceManager(xmlDocument.NameTable);
            xmlNamespaceManager.AddNamespace("dc", "http://purl.org/dc/elements/1.1/");
            for (int i = 0; i < itemNodeList.Count; i++)
            {
                XmlNode titleNode = itemNodeList[i].SelectSingleNode("title");
                XmlNode linkNode = itemNodeList[i].SelectSingleNode("link");
                XmlNodeList categoryNodes = itemNodeList[i].SelectNodes("category");
                XmlNode descriptionNode = itemNodeList[i].SelectSingleNode("description");
                XmlNode authorNode = itemNodeList[i].SelectSingleNode("dc:creator", xmlNamespaceManager);
                var headerImageUrlAndPublishDate = await _htmlService.GetHeaderImageUrlAndPostDate(linkNode.InnerText);
                var blogPost = new BlogPost
                {
                    Title = titleNode.InnerText,
                    Link = linkNode.InnerText,
                    Categories = categoryNodes.Cast<XmlNode>().Select(node => node.InnerText).ToList(),
                    Author = authorNode.InnerText,
                    HeaderImageUrl = headerImageUrlAndPublishDate.Item1,
                    Description = await _htmlService.GetPostIntroduction(descriptionNode.InnerText),
                    PublishDate = DateTime.Parse(headerImageUrlAndPublishDate.Item2)
                };
                blogInfo.BlogPosts.Add(blogPost);
            }
            return blogInfo;   
        }
    }
}

Under Services/Interfaces, create IHtmlService.cs and paste the following code:

namespace RssFeedDigestEmailer.Cli.Services.Interfaces;
public interface IHtmlService
{
    Task<(string, string)> GetHeaderImageUrlAndPostDate(string blogPostUrl);
    Task<string> GetPostIntroduction(string rawPostHtml);
}

Under Services, create HtmlService.cs and paste the following code:

using AngleSharp;
using AngleSharp.Dom;
using AngleSharp.Html.Parser;
using RssFeedDigestEmailer.Cli.Services.Interfaces;
namespace RssFeedDigestEmailer.Cli.Services;
public class HtmlService : IHtmlService
{
    public async Task<(string, string)> GetHeaderImageUrlAndPostDate(string blogPostUrl)
    {
        var config = AngleSharp.Configuration.Default.WithDefaultLoader();
        var address = blogPostUrl;
        var context = BrowsingContext.New(config);
        var document = await context.OpenAsync(address);
        var cellSelector = "#header_image > img";
        var cell = document.QuerySelector(cellSelector);
        var headerImgSrc = cell.Attributes.GetNamedItem("src");
        var publishDateCellSelector = "body > main > section > ul > article > header > div > div.article-authors > span";
        var publishDateCell = document.QuerySelector(publishDateCellSelector);
        return (headerImgSrc?.Value, publishDateCell?.InnerHtml);
    }
    public async Task<string> GetPostIntroduction(string rawPostHtml)
    {
        var parser = new HtmlParser();
        var document = parser.ParseDocument(rawPostHtml);
        var cellSelector = "div:nth-child(1) > p:nth-child(1)";
        var cell = document.QuerySelector(cellSelector);
        return cell?.InnerHtml;
    }
}

Under Configuration, create EmailDataSettings.cs and paste the following code:

namespace RssFeedDigestEmailer.Cli.Configuration;
public class EmailDataSettings
{
    public string RecipientName { get; set; }
    public string SubjectPrefix { get; set; }
}

Under Configuration, create RssSettings.cs and paste the following code:

namespace RssFeedDigestEmailer.Cli.Configuration;
public class RssSettings
{
    public string FeedUrl { get; set; }
}

Update Program.cs as below:

using System.Reflection;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using RssFeedDigestEmailer.Cli.Configuration;
using RssFeedDigestEmailer.Cli.Services;
using RssFeedDigestEmailer.Cli.Services.Interfaces;
using SendGrid.Extensions.DependencyInjection;
using IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureHostConfiguration(config =>
    {
        config
            .AddUserSecrets(Assembly.GetExecutingAssembly(), true, false);
    })
    .ConfigureServices((hostBuilderContext, services) =>
    {
        services
            .AddTransient<IRssService, RssService>()
            .AddTransient<IEmailService, EmailService>()
            .AddTransient<IHtmlService, HtmlService>()
            .AddTransient<IDataProvider, TwilioBlogDataProvider>()
            .AddHttpClient("RssServiceHttpClient");
        services
            .AddSendGrid(options => options.ApiKey = hostBuilderContext.Configuration["SendGridSettings:ApiKey"]);
        services   
            .Configure<EmailSettings>(hostBuilderContext.Configuration.GetSection("EmailSettings"))
            .Configure<RssSettings>(hostBuilderContext.Configuration.GetSection("RssSettings"))
            .Configure<EmailDataSettings>(hostBuilderContext.Configuration.GetSection("EmailDataSettings"));
    })
    .Build();
var emailService = (EmailService) ActivatorUtilities.CreateInstance(host.Services, typeof(EmailService));
await emailService.SendTemplatedEmail();

Update appsettings.json and add the new configuration settings after the emailSettings section:

    "rssSettings": {
        "feedUrl": "https://www.twilio.com/blog/feed"
    },
    "emailDataSettings": {
        "recipientName": "",
        "subjectPrefix": ""
    }

What is RSS?

RSS (Really Simple Syndication) is an easy way to keep up with news and blogs. It’s an XML-based feed generated by the websites. RSS readers periodically download these feeds and compare them to what they have locally. This way, the user can get notifications for the updates.

In this example, you will only look into downloading and parsing an RSS feed.

Downloading RSS Feed

First, you need to find out the address of the RSS feed. These are generally plain XML files hosted on the blog or website. If you know that there is an RSS feed, but you don’t know how to find it, one way to find out is to check the website’s source code. For example, on the Twilio Blog, you can view the source and search for RSS in the code. Next, you should see the link to the feed:

How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 17

Once you know where to download the feed, the rest is the same as downloading any file from the internet. The project uses the following code snippet to download the RSS feed and create the XmlDocument by loading the XML stream:

var httpClient = _httpClientFactory.CreateClient("RssServiceHttpClient");
using (var response = await httpClient.GetAsync(_rssSettings.FeedUrl))
using (var rssFeedStream = await response.Content.ReadAsStreamAsync())
{ 
    var xmlDocument = new XmlDocument();
    xmlDocument.Load(rssFeedStream);
…

The _httpClientFactory variable shown above is injected during the program setup:

.AddHttpClient("RssServiceHttpClient");

Parsing XML

After you get the raw XML, the next step is to parse and extract the bits you will use in your dynamic template.

You can find the full RSS 2.0 specification here. In the example project, you will use the main required elements: title, link, and description.

How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 18

In the example, the built-in System.XML classes are used to parse the XML. The blog post items are under the /rss/channel/item path, so you get those elements like this:

XmlNodeList itemNodeList = xmlDocument.SelectNodes("/rss/channel/item");

The next step is to loop through the XML nodes in the XmlNodeList object which can be accessed by their index in the array:

for (int i = 0; i < itemNodeList.Count; i++)
{
    XmlNode titleNode = itemNodeList[i].SelectSingleNode("title");
    XmlNode linkNode = itemNodeList[i].SelectSingleNode("link");
    XmlNode descriptionNode = itemNodeList[i].SelectSingleNode("description");
    // ...
}

Other nodes are parsed and used in the example, but for brevity, the code snippet above only shows the required ones.

One thing to note is parsing the elements with namespaces. In the example project, only the author element has a namespace, and that’s why it’s treated a bit differently. For example, an author element looks like this in the RSS feed:

<dc:creator
        xmlns:dc="http://purl.org/dc/elements/1.1/">Firstname Lastname
</dc:creator>

To access this element, first, you need to define an XML namespace:

XmlNamespaceManager xmlNamespaceManager = new XmlNamespaceManager(xmlDocument.NameTable);
xmlNamespaceManager.AddNamespace("dc", "http://purl.org/dc/elements/1.1/");

And in the parsing code, you can access the element like this:

XmlNode authorNode = itemNodeList[i].SelectSingleNode("dc:creator", xmlNamespaceManager);

Parsing HTML

Initially, I was planning to use only the RSS feed to obtain all the data used in the dynamic template. I also wanted to use the blog header image and published date in the digest email. Unfortunately, those bits of information don’t come in the RSS XML data. That’s why I resorted to HTML parsing. The risk of HTML parsing is that Twilio could change its HTML structure and CSS classes at any point, which would break the code.

!!!info

The HTML parsing is implemented by using the AngleSharp library.

!!!

For every blog post in the feed, the sample project parses the post HTML and selects the header image and the publish date:

public async Task<(string, string)> GetHeaderImageUrlAndPostDate(string blogPostUrl)
{
    var config = AngleSharp.Configuration.Default.WithDefaultLoader();
    var address = blogPostUrl;
    var context = BrowsingContext.New(config);
    var document = await context.OpenAsync(address);
    var cellSelector = "#header_image > img";
    var cell = document.QuerySelector(cellSelector);
    var headerImgSrc = cell.Attributes.GetNamedItem("src");
    var publishDateCellSelector = "body > main > section > ul > article > header > div > div.article-authors > span";
    var publishDateCell = document.QuerySelector(publishDateCellSelector);
    return (headerImgSrc?.Value, publishDateCell?.InnerHtml);
}

The important part is finding the CSS selector of the element you’re interested in. This is relatively straightforward with the Developer Tools in your browser.

For example, to get the selector of the header image, open a Twilio blog post. Then right-click on the header image and select Inspect from the context menu. While the element is still selected, right-click again to open the context menu. Click Copy and then Copy selector as shown in the screenshot below:

How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 19

The selector copied should look like this: #header_image > img

This is the selector used in the project to get a reference to the img element. Then the src attribute is accessed by the following line:

var headerImgSrc = cell.Attributes.GetNamedItem("src");

Similarly, you can obtain the CSS selector for the publish date cell and use it to extract the date as a string.

Another use of HTML parsing is to get the introduction part of the blog post. The entire blog post is published in the XML feed, but it would take too much space to put it all in the email, so I decided to pick the first paragraph element (<p>).

Also, I didn’t want to load the URL for this task as it’s already in the XML data downloaded. So a different approach is used to parse the first paragraph of the blog post, as shown below:

public async Task<string> GetPostIntroduction(string rawPostHtml)
{
    var parser = new HtmlParser();
    var document = parser.ParseDocument(rawPostHtml);
    var cellSelector = "div:nth-child(1) > p:nth-child(1)";
    var cell = document.QuerySelector(cellSelector);
    return cell?.InnerHtml;
}

It’s more concise as it doesn’t need to download the HTML over the network and only uses the raw HTML passed in the rawPostHtml argument.

Putting it All Together: Sending the Latest Posts from the Twilio Blog via Email

Finally, it’s time to reap the rewards of all the preparation work you put in. The example project supports one last command you will look into now: Send email command.

You get all the data to use in the email from the IDataProvider.GetEmailData implementation. In this final version of the sample application, you will use TwilioBlogDataProvider, which in turn uses the RssService by calling the GetBlogInfo method.

var blogInfo = await _rssService.GetBlogInfo();

Next, you prepare the dynamic data to be used in the rendered HTML:

return new
{
    recipientName = _emailDataSettings.RecipientName,
    subject = $"{_emailDataSettings.SubjectPrefix} - {FormatDate(DateTime.Today)}",
    lastBuildDate = FormatDate(blogInfo.LastBuildDate, showTime: true),
    blogPostList = blogInfo.BlogPosts.Select(b => new
    {
        title = b.Title, 
        link = b.Link, 
        headerImageUrl = b.HeaderImageUrl, 
        description = b.Description,
        author = b.Author,
        publishDate = FormatDate(b.PublishDate),
        categories = string.Join("; ", b.Categories) 
    })
};
string FormatDate(DateTime date, bool showTime = false)
{
    return (showTime) ? date.ToString("dd MMMM yyyy, HH:mm") : date.ToString("dd MMMM yyyy");
}

The code that sends the email is quite concise:

var dynamicEmailData = await _dataProvider.GetEmailData();
var from = new EmailAddress(_emailSettings.SenderEmailAddress, _emailSettings.SenderDisplayName);
var to = new EmailAddress(_emailSettings.RecipientEmailAddress, _emailSettings.RecipientDisplayName);
var msg = MailHelper.CreateSingleTemplateEmail(from, to, _emailSettings.TemplateId, dynamicEmailData);
var response = await _sendGridClient.SendEmailAsync(msg);

To send the email, run the application, and the final email looks like this:

How to send RSS feed digest email with C# and SendGrid Dynamic Email Templates - image 20

Now you get the same email but with data downloaded from the Twilio Blog RSS feed and individual blog pages and formatted in one nice digest email.

Conclusion

In this article, you learned how to create a Dynamic Email Template. You created an HTML email with CSS and used Handlebars templating to render the email with test JSON data. You also learned how to retrieve and parse RSS XML feeds as well as basic HTML parsing.

I hope you found this article helpful and interesting. The source code is publicly available, so feel free to download and play at will.

If you enjoyed this article, here are a few articles I’d recommend reading about template-based emails:

]]> <![CDATA[How to get secrets from HashiCorp Vault into .NET configuration with C#]]> 2026-08-05T12:45:00+00:00 https://volkanpaksoy.com/archive/2026/08/05/How-to-get-secrets-from-HashiCorp-Vault-into-dotNET-configuration-with-CSharp

This article was originally published on the Twilio Blog.

Configuration management has always been a challenge for developers. It gets especially tricky when it comes to storing sensitive configuration values such as API keys, tokens, certificates, passwords etc. In this article, you will learn how to use Hashicorp Vault with C# .NET to manage your application’s secrets.

Prerequisites

You’ll need the following things in this tutorial:

Problem Statement

Let’s start by implementing a simple application to demonstrate the issue. It’s a simple .NET console application that sends a single SMS via Twilio.

Run the following commands in a terminal to create the project and add the Twilio NuGet package:

mkdir VaultDemo 
cd VaultDemo
dotnet new console
dotnet add package Twilio

Open the project with your IDE and replace the contents of Program.cs with the code below:

using Twilio;
using Twilio.Rest.Api.V2010.Account;
using Twilio.Types;
var accountSid = "{ YOUR TWILIO ACCOUNT SID }";
var authToken = "{ YOUR TWILIO AUTH TOKEN }";
var senderPhoneNumber = "{ SENDER PHONE NUMBER }";
var recipientPhoneNumber = "{ RECIPIENT PHONE NUMBER }";
TwilioClient.Init(accountSid, authToken);
MessageResource.Create(
    body: "Nothing fancy, just a simple SMS.",
    from: new PhoneNumber(senderPhoneNumber),
    to: new PhoneNumber(recipientPhoneNumber)
);

Replace the placeholders with actual values. To obtain your Twilio Account SID, AuthToken, and Twilio Phone Number, log in to the Twilio Console and copy the values shown in the account info section:

How to get secrets from HashiCorp Vault into .NET configuration with C# - image 1

For the recipient phone number, use your actual phone number so that you can receive the SMS and confirm the application is working.

Run the application by running the following command in the terminal:

dotnet run

You now have a working, standalone application without any dependencies on external configuration. Hardcoding secrets this way might only work for throw-away code. Even then, it’s ill-advised, and you should never use this approach. If you forget to delete the code, you will expose your secrets in cleartext.

Most applications use a version control system (such as GitHub, GitLab etc). In enterprise, it’s safe to say all code is pushed to a source code repository. If you hardcode your secrets and push your secrets to the version control system, anybody who has access to the code will have access to your secrets too. If you’re working on a public open-source project, you have now exposed your secrets to the entire world.

!!!warning

If you are using Git as your version control system, even if you delete the sensitive data immediately, it will still exist in your git history.

!!!

As a general rule of thumb, putting secrets in your source code is considered to be a terrible practice.

Environment Variables

A better approach is using environment variables. This way, you can completely separate your code from your config. If you subscribe to the Twelve-Factor-App philosophy, you can see they describe this approach as “Store config in the environment”. You can read more about it in their Config section.

Now, update your application and replace the hardcoded values with the following lines:

var accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");
var authToken = Environment.GetEnvironmentVariable("TWILIO_AUTH_TOKEN");
var senderPhoneNumber = Environment.GetEnvironmentVariable("SENDER_PHONE_NUMBER");
var recipientPhoneNumber = Environment.GetEnvironmentVariable("RECIPIENT_PHONE_NUMBER");

For macOS and Linux, set the environment variable like this:

export {KEY}={VALUE}

If you’re using PowerShell on Windows or another OS, use this command:

$Env:{KEY} = "{VALUE}"

If you’re using CMD on Windows, use this command:

set "{KEY}={VALUE}"

Replace {KEY} with the name of the configuration/secret key (such as TWILIO_ACCOUNT_SID). Replace {VALUE} with the value of the configuration/secret (the values you hardcoded in the previous example).

Repeat the above for all 4 configuration values (TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER and RECIPIENT_PHONE_NUMBER).

Run the application and confirm it’s still working. Now you have given yourself the opportunity of checking in your code to the version control system as there are no sensitive values in it anymore.

User Secrets

You can also improve the local development environment security by using .NET user secrets. This way, the secrets are stored in a JSON configuration file in the user profile directory. Since the secrets are persisted, you don’t have to enter them over and over again, whereas with the environment variable you will lose the values if you close the terminal.

To use user secret in the demo application, run the following command:

dotnet user-secrets init

Now you can add the secrets by running the following commands:

dotnet user-secrets set "KEY" "VALUE"

To be able to read these values back, you will need configuration extension NuGet packages from Microsoft. Run the following commands to add those libraries:

dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.EnvironmentVariables
dotnet add package Microsoft.Extensions.Configuration.UserSecrets

!!!info

You can also use the appSettings.json file, command-line arguments, and more to read the configuration values. You can read more about various configuration options at configuration in .NET.

!!!

Update Program.cs as shown below:

```csharp hl_lines=”1” using Microsoft.Extensions.Configuration; using Twilio; using Twilio.Rest.Api.V2010.Account; using Twilio.Types; IConfiguration config = new ConfigurationBuilder() .AddUserSecrets(optional: true, reloadOnChange: false) .AddEnvironmentVariables() .Build(); var accountSid = config["TWILIO_ACCOUNT_SID"]; var authToken = config["TWILIO_AUTH_TOKEN"]; var senderPhoneNumber = config["SENDER_PHONE_NUMBER"]; var recipientPhoneNumber = config["RECIPIENT_PHONE_NUMBER"]; TwilioClient.Init(accountSid, authToken); MessageResource.Create( body: "Nothing fancy, just a simple SMS.", from: new PhoneNumber(senderPhoneNumber), to: new PhoneNumber(recipientPhoneNumber) );


Run the application, and it should still work. 

This example leverages both user secrets and environment variables. You can still add environment variables to overwrite the values in user secrets. The last key loaded wins, and all the other ones are overwritten. So be careful when specifying multiple providers. The benefit of this approach is now you are not directly reading from environment variables which means you have more control over where you store your configuration.

Now you’re in a more secure position when storing the secrets locally in your development environment. What about deployments, though? When you deploy your application, it will fail because it won’t find the secrets. You can choose to remotely log in to your servers and set the environment variables or user secrets, but it’s impractical and doesn’t scale.  

A better approach is to use a central, secure place to store your configuration so that all instances of your application can easily read those values.

Many services provide this functionality, such as Azure Key Vault, AWS Secrets Manager, and Hashicorp Vault. In this article, you will learn how to set up HashiCorp Vault using Docker and configure your application to get your configuration from it.

## Set Up Hashicorp Vault

Vault is an open-source project and can be found on Hashicorp’s [GitHub repository](https://github.com/hashicorp/vault). Since it’s open-source, you have a few alternatives for using Vault:

- Clone/fork the GitHub repository and build it yourself

- Download and run one of the installers created for your platform

- Run it in a Docker container

- Sign up and use their cloud-based solution

First 3 options are self-hosted and completely free. For the hosted solution, you can sign up for free and evaluate it for 30 days. In this article, you’ll run it in a Docker container. 

!!!info

The focus of the article is not setting up an enterprise-grade Vault cluster, which would be too complicated to cover in a single article. You will see how to run it for your development environment in a single Docker container, but the principle is the same. So if you later purchase a cloud-hosted solution, all you have to do is change the vault address. You can find out more about Vault pricing and packaging [here](https://www.hashicorp.com/products/vault/pricing).

!!!

Vault is one of the select few official images, and it’s quite popular on Docker Hub:

![How to get secrets from HashiCorp Vault into .NET configuration with C# - image 2](/images/vpblogimg/2026/08/How-to-get-secrets-from-HashiCorp-Vault-into-dotNET-configuration-with-CSharp/02.png)

Run the following command to pull the latest Vault image and run Vault in a container:

```bash
docker run -d -p 8200:8200 --cap-add=IPC_LOCK --name=dev-vault vault

In the command above -d flag indicates to run it in the background. --cap-add=IPC_LOCK prevents sensitive values from being swapped to disk. As the name of the container implies, this is for development only. Everything runs in memory and all the secrets will disappear if you stop the container.

Now, open a browser and go to http://localhost:8200. You should see a sign-in screen like this:

How to get secrets from HashiCorp Vault into .NET configuration with C# - image 3

To get your token, first, find the container id by running the command below:

docker ps | grep vault

You should see something like this:

How to get secrets from HashiCorp Vault into .NET configuration with C# - image 4

The first value you see is the container id (in this example it’s 892327726ea3)

Copy that value and run the command below by replacing { YOUR CONTAINER ID } with the value you copied:

docker logs { YOUR CONTAINER ID }

At the end of the logs you should see your root token:

How to get secrets from HashiCorp Vault into .NET configuration with C# - image 5

Copy your root token and use it in the sign-in screen.

!!!info

Vault server starts in a sealed state, meaning it doesn’t know how to decrypt the data. Unsealing is the process of obtaining the plaintext root key necessary to read the decryption key to decrypt the data, allowing access to the Vault. You can read more about sealing and unsealing here.

!!!

You should see the default secrets engines:

How to get secrets from HashiCorp Vault into .NET configuration with C# - image 6

Cubbyhole and key/value secret engines are enabled by default (and they cannot be disabled). The cubbyhole secrets engine is used to store arbitrary secrets. Paths are scoped per token, and no token can access another token’s cubbyhole. In this article, you will use Key/Value secret engine, which is a generic

secret engine.

Click secret to view the existing secrets (which are none at the moment). You should see a screen like this:

How to get secrets from HashiCorp Vault into .NET configuration with C# - image 7

Click the Create secret button.

Set the path to your secret as twilioapp. Add your config values as you did in the previous examples. Your screen should look like this:

How to get secrets from HashiCorp Vault into .NET configuration with C# - image 8

Click the Save button. Now you should see the values saved as Version 1 of your configuration:

How to get secrets from HashiCorp Vault into .NET configuration with C# - image 9

Now that your secrets are Vault, it’s time to modify the application to read these values.

Using Vault C# Client

To access Vault with C#, you are going to use a library called VaultSharp. Run the following command to add the NuGet package to your project:

dotnet add package VaultSharp

Set the user secret VAULT_ADDR to http://127.0.0.1:8200.

Set the VAULT_TOKEN user secret to your root token.

!!!warning

In production, it’s more likely your operations team will provide you with a role that has access to the secrets your application needs, so you won’t have to use tokens this way. This is just for demonstration purposes.

!!!

Update Program.cs as shown below:

using Microsoft.Extensions.Configuration;
using Twilio;
using Twilio.Rest.Api.V2010.Account;
using Twilio.Types;
using VaultSharp;
using VaultSharp.V1.AuthMethods;
using VaultSharp.V1.AuthMethods.Token;
using VaultSharp.V1.Commons;
IConfigurationBuilder configBuilder = new ConfigurationBuilder()
    .AddUserSecrets<Program>(optional: true, reloadOnChange: false)
    .AddEnvironmentVariables();
IConfiguration config = configBuilder.Build();
IAuthMethodInfo authMethod = new TokenAuthMethodInfo(config["VAULT_TOKEN"]);
var vaultClientSettings = new VaultClientSettings(config["VAULT_ADDR"], authMethod);
IVaultClient vaultClient = new VaultClient(vaultClientSettings);
Secret<SecretData> kv2Secret = await vaultClient.V1.Secrets.KeyValue.V2
    .ReadSecretAsync(path: "twilioapp", mountPoint: "secret");
configBuilder.AddInMemoryCollection(kv2Secret.Data.Data.ToDictionary(kv => kv.Key, kv => kv.Value.ToString()));
config = configBuilder.Build();
var accountSid = config["TWILIO_ACCOUNT_SID"];
var authToken = config["TWILIO_AUTH_TOKEN"];
var senderPhoneNumber = config["SENDER_PHONE_NUMBER"];
var recipientPhoneNumber = config["RECIPIENT_PHONE_NUMBER"];
TwilioClient.Init(accountSid, authToken);
MessageResource.Create(
    body: "Nothing fancy, just a simple SMS.",
    from: new PhoneNumber(senderPhoneNumber),
    to: new PhoneNumber(recipientPhoneNumber)
);

Run the application again, and you should now be able to get the secrets from your Vault instance.

The implementation above first gets the user secrets to be able to access Vault. Then, reads the secrets from Vault and adds them back to the .NET configuration so that all configuration values can be managed in one place. To make it more reusable, you can refactor it to use an extension method.

!!!info

If you want to implement a configuration provider to retrieve information from Vault, I recommend reading this article from Hashicorp.

!!!

Vault supports various authentication methods such as app role, AWS auth, Azure auth, etc. Since my focus is on the programming side, I used the basic token authentication method. You can find out more about the other auth methods on the library’s GitHub repo.

Now stop the container by running:

docker stop { YOUR CONTAINER ID }

Run the application, and it will get an error as the Vault is not running anymore. Start the same container again by running

docker start { YOUR CONTAINER ID }

Run your application again, and this time it will fail due to the following error: Unhandled exception. VaultSharp.Core.VaultApiException: {“errors”:[“permission denied”]}

If you check the logs of the container again, you will see the root token is different. Copy that one and sign in to your Vault via UI again, and you will see that your previous secrets are gone now. This is, as discussed before, because we didn’t provide a persistence engine, and everything was kept in memory. In the next section, you will learn how to fix this issue.

Persisting Secrets

When you run Hashicorp Vault in dev mode, everything is stored in-memory, and the web UI is enabled automatically. To persist secrets, you need to run Vault in server mode.

Vault has an extendable model and supports various storage providers for persisting secrets. You can use the file system, an RDBMS such as MySQL or MSSQL, a NoSQL database such as CouchDB or Amazon DynamoDB, or even a cloud-based storage service such as Google Cloud Storage or Amazon S3. You can find the full list of supported providers here. All the data will be encrypted at rest (as well as in transit), so even if a 3rd party gains access to the stored secrets, they wouldn’t be able read them. In this article, you will use the local file system to persist your secrets.

If you created a container in the previous section, stop and delete it by running the following commands:

docker stop { YOUR CONTAINER ID }
docker rm { YOUR CONTAINER ID }

Then, create a folder to store the Vault configuration. It can be placed anywhere you like on your filesystem. The following example uses /dev/vault/config under your user’s home directory.

mkdir -p $HOME/dev/vault/config

Create a file named config.hcl under that folder and update its contents as shown below:

ui = true
disable_mlock = true
storage "file" {
  path = "/vault/file"
}
listener "tcp" {
  address = "0.0.0.0:8200"
  tls_disable = "true"
}
api_addr = "http://127.0.0.1:8200"

Then, run the following command to create the Vault instance:

docker run -d -p 8200:8200 --volume $HOME/dev/vault:/vault vault server

Open a browser tab and go to http://127.0.0.1:8200.

!!!warning

Keep in mind that this article is not meant to teach you how to install a production-grade Vault server, as it requires high-security, high-availability, backups, monitoring, etc. This is still meant to be used for local development.

!!!

This time, you will see a more involved setup since you are now running Vault in server mode: How to get secrets from HashiCorp Vault into .NET configuration with C# - image 10

Enter 1 in both key shares and key threshold fields.

You should see a successful initialization screen:

How to get secrets from HashiCorp Vault into .NET configuration with C# - image 11

Click the Download keys button and get a copy of your keys. Then click the Continue to Unseal button to proceed.

You will then be prompted your Unseal key:

How to get secrets from HashiCorp Vault into .NET configuration with C# - image 12

Open the JSON file you just downloaded which looks like this:

How to get secrets from HashiCorp Vault into .NET configuration with C# - image 13

Copy the value of the keys property (this is an array but since you requested 1 key share, it only has 1 element.

Click the Unseal button.

Now you should be redirected to the sign-in page. Copy your root token from the JSON and use it to log in.

How to get secrets from HashiCorp Vault into .NET configuration with C# - image 14

You must have noticed it looks different from the dev mode. There is no secret engine called secret. To fix this, click Enable new engine.

Select KV and click Next.

How to get secrets from HashiCorp Vault into .NET configuration with C# - image 15

Enter “secret” in the Path field just to match the previous example and click Enable Engine.

How to get secrets from HashiCorp Vault into .NET configuration with C# - image 16

Now click the Create secret button as you did in the previous section and create secrets.

Update your new Vault token by running the following command:

dotnet user-secrets set VAULT_TOKEN { YOUR NEW ROOT KEY }

Replace { YOUR NEW ROOT KEY } with the value you copied from the file you downloaded.

Run your application again and you should receive an SMS as you did before.

Here’s the difference though:

Open a terminal and find the container id by running

docker ps | grep vault

Now run the following command:

docker restart { YOUR CONTAINER ID }

Replace ` { YOUR CONTAINER ID }` with the id you noted from the previous command.

Check the container logs by running

docker logs { YOUR CONTAINER ID }

If you recall, the last time you did this you saw an error. This time you should see something like this:

How to get secrets from HashiCorp Vault into .NET configuration with C# - image 17

So the Vault server is still running.

Go back to the Web UI, and it will ask you for the unseal key again. After you enter the unseal key and the root token, you can see the secrets you entered have persisted successfully.

Conclusion

In this article, I wanted to demonstrate the necessity and benefit of having a centralized, secure system to manage application secrets and configuration. You started from the very primitive hard-coding secrets to code approach to using an external service which is highly reputable and used by many top-level companies all around the world. Granted, your Vault installation is for development only, but the underlying principles still apply to production. I hope you found this article helpful. If you’d like to keep learning about .NET configuration and containerizing applications, I recommend taking a look at these articles:

]]> <![CDATA[Get notified of new magazine issues using web scraping and SMS with C# .NET]]> 2026-08-05T12:40:00+00:00 https://volkanpaksoy.com/archive/2026/08/05/Get-notified-of-new-magazine-issues-using-web-scraping-and-SMS-with-CSharp-dotNET

This article was originally published on the Twilio Blog.

As a Raspberry PI fan, I like to read The MagPi Magazine, which is freely available as PDFs. The problem is I tend to forget to download it manually every month, so I decided to automate the process. If Raspberry Pi is not your thing, you should be able to modify the demo application to work for any periodical publication that offers free downloads.

Prerequisites

You’ll need the following things in this tutorial:

Project Overview

First, let’s understand what the demo intends to achieve. The components involved and the workflow looks like this:

Get notified of new magazine issues using web scraping and SMS with C# .NET - image 1

  • The worker service reads a database to get the latest issues it sends notifications for.

  • The worker service fetches the website for the magazine and gets the latest issue number. Then, it compares the latest issue number in the database to the latest issue number on the website. If the numbers are equal, it means there is no new issue. If the latest issue number on the website is greater, then there is a new issue. If there is no new issue, the worker service goes to sleep. If there is a new issue, it gets the cover image and the direct link URLs from the magazine’s website.

  • The worker service calls Twilio API to send an SMS/MMS message.

  • Twilio sends the message to the user.

  • The worker service updates its database with the latest issue to avoid duplicate messages.

Project Implementation

Let’s start by creating the worker service by running the following commands:

mkdir MagazineTracker
cd MagazineTracker
dotnet new worker

Create the Data Layer

First, let’s look into the data layer. The only piece of information that needs to be stored is the latest issue number that the application processed.

Create a folder inside your project named Data. Then, create a file LatestMagazineIssue.cs, that contains a model class for your data. Add the following code:

namespace MagazineTracker.Data;
public class LatestMagazineIssue
{
    public int IssueNumber { get; set; }
}

Then, create a new file IMagazineIssueRepository.cs in the Data folder that holds a repository interface to outline the data operations you’re going to use. Add the following code to the file:

namespace MagazineTracker.Data;
public interface IMagazineIssueRepository
{
    Task<LatestMagazineIssue> GetLatestIssue();
    Task SaveLatestIssue(int latestIssueNumber);
}

The next step is to decide how to store the data. The requirements of this project are very straightforward, so you don’t need a full-fledged database; a simple JSON file will suffice. Go ahead and create a JSON file named db.json under the Data directory. Update its contents as shown below:

{
  "LatestIssueNumber": 0
}

Then, create another file named JsonMagazineIssueRepository.cs in the Data folder which will contain the repository implementation for the JSON file named that implements the previous interface. Update the code as shown below:

using System.Text.Json;
using Microsoft.Extensions.Options;
namespace MagazineTracker.Data;
public class JsonMagazineIssueRepository : IMagazineIssueRepository
{
    private readonly DatabaseSettings _databaseSettings;
    public JsonMagazineIssueRepository(IOptions<DatabaseSettings> databaseSettings)
    {
        _databaseSettings = databaseSettings.Value;
    }
    public async Task<LatestMagazineIssue> GetLatestIssue()
    {
        var dbAsJson = await File.ReadAllTextAsync(_databaseSettings.JsonFilePath);
        var latestIssue = JsonSerializer.Deserialize<LatestMagazineIssue>(dbAsJson);
        return latestIssue;
    }
    public async Task SaveLatestIssue(int latestIssueNumber)
    {
        var dbAsJson = await File.ReadAllTextAsync(_databaseSettings.JsonFilePath);
        var latestIssue = JsonSerializer.Deserialize<LatestMagazineIssue>(dbAsJson);
        latestIssue.IssueNumber = latestIssueNumber;
        dbAsJson = JsonSerializer.Serialize(latestIssue);
        await File.WriteAllTextAsync(_databaseSettings.JsonFilePath, dbAsJson);
    }
}

The JsonMagazineIssueRepository only needs one parameter: The path to the JSON file. You can encapsulate it in a simple class. Create DatabaseSettings.cs under the Data directory with the following code:

namespace MagazineTracker.Data;
public class DatabaseSettings
{
    public string JsonFilePath { get; set; }
}

Then update your appsettings.json file so that it looks like this:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "DatabaseSettings": {
    "JsonFilePath": "./Data/db.json"
  }
}

Finally, for this stage, update Program.cs as shown below:

using MagazineTracker;
using MagazineTracker.Data;
IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostBuilderContext, services) =>
    {
        services.AddHostedService<Worker>();
        services.AddTransient<IMagazineIssueRepository, JsonMagazineIssueRepository>();
        services.Configure<DatabaseSettings>(hostBuilderContext.Configuration.GetSection("DatabaseSettings"));
    })
    .Build();
// await host.RunAsync();
var repo = host.Services.GetRequiredService<IMagazineIssueRepository>();
await repo.SaveLatestIssue(120);
var latestIssue = await repo.GetLatestIssue();
Console.WriteLine(latestIssue.IssueNumber);

From line 7 to 9, is where you register your services with the concrete implementations in the DI container. Then the IMagazineIssueRepository service is retrieved to get the latest magazine issue and print it to the console.

Line 12 is commented out temporarily to make the implementation/debugging phase easier. As of now, you don’t need to worry about scheduling. That will come later. So, for now, run the application by

dotnet run

And confirm your output looks like this:

120

Now that you have a working data layer move on to the next section, where you will do some HTML parsing.

HTML Parse the Magazine Page

You need 3 things to get from the magazine website:

  • The latest issue number

  • The URL of the magazine (PDF or other formats)

  • The URL of the cover image (Optional)

Every magazine tracker will work differently but you can combine the requirements above in a single interface so that all the trackers can work in a similar fashion.

Create IMagazineTrackerService.cs for the interface and update its code as shown below:

namespace MagazineTracker;
public interface IMagazineTrackerService
{
    Task<int> GetLatestIssueNumber();
    Task<string> GetLatestIssueCoverUrl();
    Task<string> GetIssuePdfUrl(int issueNumber);
}

All your trackers must implement the IMagazineTrackerService interface.

Now, implement your first tracker by creating a file MagPiTrackerService.cs with the following dummy implementation:

namespace MagazineTracker;
public class MagPiTrackerService : IMagazineTrackerService
{
    public async Task<int> GetLatestIssueNumber()
    {
        throw new NotImplementedException();
    }
    public async Task<string> GetLatestIssueCoverUrl()
    {
        throw new NotImplementedException();
    }
    public async Task<string> GetIssuePdfUrl(int issueNumber)
    {
        throw new NotImplementedException();
    }
}

To do the HTML parsing, you will use a library called AngleSharp. It makes the whole process a lot easier, and it can be added to your project via NuGet by running:

dotnet add package AngleSharp

Now, take a look at where to find the latest issue number. The easiest way to find the latest issue number is by going to the issues page, which looks like this at the time of this writing:

Get notified of new magazine issues using web scraping and SMS with C# .NET - image 2

If you look at the source of the page (Right click and click Show/View Page Source depending on your browser). If you search the phrase “The MagPi issue 121 out now” (replace the number with the one you see on your screen) you should find the relevant area that looks something like this:

```html hl_lines=”3 4 5 6”

The MagPi issue 121 cover

The MagPi issue 121 out now!

… ``` This page contains the latest issue number and a URL of the cover image. To parse this page, update the `MagPiTrackerService` code as shown below: ```csharp using AngleSharp; namespace MagazineTracker; public class MagPiTrackerService : IMagazineTrackerService { private const string MagpiRootUrl = "https://magpi.raspberrypi.com"; public async Task GetLatestIssueNumber() { var config = Configuration.Default.WithDefaultLoader(); var context = BrowsingContext.New(config); var document = await context.OpenAsync($"{MagpiRootUrl}/issues/"); var latestCoverLinkSelector = ".c-latest-issue > .c-latest-issue__cover > a"; var latestCoverLink = document.QuerySelector(latestCoverLinkSelector); var rawLink = latestCoverLink.Attributes.GetNamedItem("href").Value; return int.Parse(rawLink.Substring(rawLink.LastIndexOf('/') + 1)); } public async Task GetLatestIssueCoverUrl() { var config = Configuration.Default.WithDefaultLoader(); var context = BrowsingContext.New(config); var document = await context.OpenAsync($"{MagpiRootUrl}/issues/"); var latestCoverImageSelector = ".c-latest-issue > .c-latest-issue__cover > a > img"; var latestCoverImage = document.QuerySelector(latestCoverImageSelector); var latestCoverImageUrl = latestCoverImage.Attributes.GetNamedItem("src").Value; return latestCoverImageUrl; } public async Task GetIssuePdfUrl(int issueNumber) { throw new NotImplementedException(); } } ``` After loading the page with AngleSharp, you have to write your CSS-selector to get the element you’re interested in. In this example, the latest issue number is obtained from the `href` attribute of the `anchor` element (by parsing the number that follows the latest ‘/’ character) Similarly, the cover URL is parsed from the `src` attribute of the `img` element. !!!info Even though both pieces of information are obtained from the same page, they were implemented as separate methods. This might look repetitive, but the reason for this is to accommodate other trackers. Having both the issue number and cover URL on the same page may not be the case for other magazines, so if you combine them into a single method, you might have issues later on with other trackers. !!! To test the latest version, update the Program.cs file as shown below: ```csharp using MagazineTracker; using MagazineTracker.Data; IHost host = Host.CreateDefaultBuilder(args) .ConfigureServices((hostBuilderContext, services) => { services.AddHostedService(); services.AddTransient<IMagazineIssueRepository, JsonMagazineIssueRepository>(); services.AddTransient<IMagazineTrackerService, MagPiTrackerService>(); services.Configure(hostBuilderContext.Configuration.GetSection("DatabaseSettings")); }) .Build(); // await host.RunAsync(); var repo = host.Services.GetRequiredService(); var tracker = host.Services.GetRequiredService(); var latestProcessedIssue = await repo.GetLatestIssue(); var latestIssueNumber = await tracker.GetLatestIssueNumber(); if (latestIssueNumber > latestProcessedIssue.IssueNumber) { Console.WriteLine($"New issue detected: {latestIssueNumber}"); var coverUrl = await tracker.GetLatestIssueCoverUrl(); Console.WriteLine($"Cover URL: {coverUrl}"); } ``` Now the `IMagazineTrackerService` is also configured as a service and retrieved from the service provider. Then `tracker.GetLatestIssueNumber` and `tracker.GetLatestIssueCoverUrl` is used to scrape the data and print it. Run the application, and you should see an output that looks like this: ``` New issue detected: 121 Cover URL: https://magpi.raspberrypi.com/storage/…/MagPi121_COVER_STORE.jpg ``` The third and final piece of information you need is the link to the PDF file. If you click on the “Download Free PDF” link, you get redirected to [https://magpi.raspberrypi.com/issues/121/pdf](https://magpi.raspberrypi.com/issues/121/pdf), which looks like this: ![Get notified of new magazine issues using web scraping and SMS with C# .NET - image 3](/images/vpblogimg/2026/08/Get-notified-of-new-magazine-issues-using-web-scraping-and-SMS-with-CSharp-dotNET/03.png) !!!info I'd strongly recommend everybody to consider donating. This is a great magazine with professional quality, and it's full of valuable knowledge about everything Raspberry Pi. !!! If you click on the "No thanks, take me to the free PDF" link, you get redirected to [https://magpi.raspberrypi.com/issues/121/pdf/download](https://magpi.raspberrypi.com/issues/121/pdf/download), and your download starts automatically. This is done by placing an iframe and setting the src as the link to the URL. If you look at the source code of the download page and search for “iframe”, you should find the relevant code looks like this: ```html
``` To parse this URL, update the `MagPiTrackerService.GetIssuePdfUrl` method as shown below: ```csharp public async Task GetIssuePdfUrl(int issueNumber) { var issueUrl = $"{MagpiRootUrl}/issues/{issueNumber}/pdf/download"; var config = AngleSharp.Configuration.Default.WithDefaultLoader(); var address = issueUrl; var context = BrowsingContext.New(config); var document = await context.OpenAsync(address); var cellSelector = "iframe"; var cell = document.QuerySelector(cellSelector); var iframeSrc = cell.Attributes.GetNamedItem("src").Value; return $"{MagpiRootUrl}/{iframeSrc.TrimStart('/')}"; } ``` Update the test code in Program.cs only to test the latest update: ```csharp … var latestProcessedIssue = await repo.GetLatestIssue(); var latestIssueNumber = await tracker.GetLatestIssueNumber(); if (latestIssueNumber > latestProcessedIssue.IssueNumber) { Console.WriteLine($"New issue detected: {latestIssueNumber}"); var pdfUrl = await tracker.GetIssuePdfUrl(latestIssueNumber); Console.WriteLine($"PDF URL: {pdfUrl}"); } ``` Run the application and confirm you can see the same URL you saw in the download page source: ``` New issue detected: 121 PDF URL: https://magpi.raspberrypi.com/downloads/…/MagPi121.pdf ``` ### Set up Twilio to Send SMS Notifications Before implementing the actual notification mechanism, create a new interface to ensure all notification channels work the same. Create a file named INotificationService.cs and update its code like this: ```csharp namespace MagazineTracker; public interface INotificationService { Task SendNewIssueNotification(int issueNumber, string coverUrl, string mediaUrl); } ``` In the demo project, you will implement SMS/MMS notifications using [Twilio Programmable SMS](https://www.twilio.com/docs/sms). Now that you have all the information, you need to deliver this to Twilio so that you can get SMS notifications on your mobile device. To achieve this, first, add Twilio SDK to your project by running: ```bash dotnet add package Twilio ``` You will need your Account SID and Auth Token to be able to talk to the Twilio API. You can find both of these on the welcome page in the account info section when you log in to the [Twilio Console](https://console.twilio.com/): ![Get notified of new magazine issues using web scraping and SMS with C# .NET - image 4](/images/vpblogimg/2026/08/Get-notified-of-new-magazine-issues-using-web-scraping-and-SMS-with-CSharp-dotNET/04.png) To store these values, you can use environment variables or a vault service, but for local development, you can use [dotnet user secrets](https://docs.microsoft.com/en-us/aspnet/core/security/app-secrets). First, you need to initialize user secrets by running ```bash dotnet user-secrets init ``` Then, create two new user secrets called `Twilio:AccountSid` and `Twilio:AuthToken` and set the values: ```bash dotnet user-secrets set Twilio:AccountSid {YOUR TWILIO ACCOUNT SID} dotnet user-secrets set Twilio:AuthToken {YOUR TWILIO AUTH TOKEN} ``` Create a new file called SmsService.cs and add the following code: ```csharp using Microsoft.Extensions.Options; using Twilio.Rest.Api.V2010.Account; using Twilio.Types; namespace MagazineTracker; public class SmsService : INotificationService { private readonly SmsSettings _smsSettings; public SmsService(IOptions smsSettings) { _smsSettings = smsSettings.Value; } public async Task SendNewIssueNotification(int issueNumber, string coverUrl, string mediaUrl) { MessageResource.Create( body: $"Here's the latest issue (#{issueNumber}) of The MagPi Magazine: {mediaUrl}", from: new PhoneNumber(_smsSettings.FromPhoneNumber), to: new PhoneNumber(_smsSettings.ToPhoneNumber), mediaUrl: string.IsNullOrEmpty(coverUrl) ? null : new [] { new Uri(coverUrl) }.ToList() ); } } ``` The SMS message needs to be sent from your Twilio phone number (which you can find right below Account SID and Auth Token on [Twilio Console](https://console.twilio.com/) welcome page). The reason the code checks whether or not `coverUrl` has a value is that some Twilio Phones Numbers don’t support MMS. For example, Twilio Phone Numbers from the United Kingdom (UK) do not support MMS, so my UK number could only send plain SMS. So, if you are not able to send MMS messages, simply send an empty string as the cover URL so that setting the `coverUrl` in your worker service looks like this: ```csharp var coverUrl = String.Empty; ``` Alternatively, you can create a boolean setting such as `includeCoverUrl` to manage this behaviour. To store both from and to phone numbers, update appsettings.json like this: ```json hl_lines="11 12 13 14" { "Logging": { "LogLevel": { "Default": "Information", "Microsoft.Hosting.Lifetime": "Information" } }, "DatabaseSettings": { "JsonFilePath": "./Data/db.json" }, "SmsSettings": { "FromPhoneNumber": "{YOUR TWILIO PHONE NUMBER}", "ToPhoneNumber": "{YOUR ACTUAL PHONE NUMBER}" } } ``` Create a file called SmsSettings.cs with the following class: ```csharp namespace MagazineTracker; public class SmsSettings { public string FromPhoneNumber { get; set; } public string ToPhoneNumber { get; set; } } ``` Finally, update Program.cs to reflect these changes: ```csharp using MagazineTracker; using MagazineTracker.Data; using Twilio; IHost host = Host.CreateDefaultBuilder(args) .ConfigureServices((hostBuilderContext, services) => { services.AddHostedService(); services.AddTransient<IMagazineIssueRepository, JsonMagazineIssueRepository>(); services.AddTransient<IMagazineTrackerService, MagPiTrackerService>(); services.AddTransient<INotificationService, SmsService>(); services.Configure(hostBuilderContext.Configuration.GetSection("DatabaseSettings")); services.Configure(hostBuilderContext.Configuration.GetSection("SmsSettings")); var accountSid = hostBuilderContext.Configuration["Twilio:AccountSid"]; var authToken = hostBuilderContext.Configuration["Twilio:AuthToken"]; TwilioClient.Init(accountSid, authToken); }) .Build(); // await host.RunAsync(); var repo = host.Services.GetRequiredService(); var tracker = host.Services.GetRequiredService(); var notificationService = host.Services.GetRequiredService(); var latestProcessedIssue = await repo.GetLatestIssue(); var latestIssueNumber = await tracker.GetLatestIssueNumber(); if (latestIssueNumber > latestProcessedIssue.IssueNumber) { Console.WriteLine($"New issue detected: {latestIssueNumber}"); var coverUrl = await tracker.GetLatestIssueCoverUrl(); var pdfUrl = await tracker.GetIssuePdfUrl(latestIssueNumber); await notificationService.SendNewIssueNotification(latestIssueNumber, coverUrl, pdfUrl); await repo.SaveLatestIssue(latestIssueNumber); } ``` !!!info Sending a message via WhatsApp works exactly the same way, except you can only use a sandbox environment unless your account is approved. The sandbox session expires after 3 days, so it’s not a great fit for continuous notifications, but if your account is approved already, you can still use `SmsService` without any modifications. All you have to do is replace the “from phone number” with “whatsapp:+xxxxxxxxxxx”, where xxxxxxxxxxx is the number provided to you by Twilio. Also, prefix the “to phone number” with “whatsapp:” !!! Time to test the final version (which also updates the database with the latest issue number). Run the application, and you should receive an SMS/MMS on your phone. My UK Twilio Phone Number doesn’t support MMS. If I try to set the `coverUrl` to the image URL, I get the following exception: ```bash Twilio.Exceptions.ApiException: Number: +44xxxxxxxxxx has not been enabled for MMS ``` So I set the `coverUrl` to empty string as discussed previously and the SMS I receive on my phone looks like this: ![Get notified of new magazine issues using web scraping and SMS with C# .NET - image 5](/images/vpblogimg/2026/08/Get-notified-of-new-magazine-issues-using-web-scraping-and-SMS-with-CSharp-dotNET/05.png) And when I tap on the link, I get this: ![Get notified of new magazine issues using web scraping and SMS with C# .NET - image 6](/images/vpblogimg/2026/08/Get-notified-of-new-magazine-issues-using-web-scraping-and-SMS-with-CSharp-dotNET/06.png) To test the MMS feature, I purchased a US Twilio Phone Number and sent the same message with the actual `coverURL` (meaning reverted the code to its original version: `var coverUrl = await _magazineTrackerService.GetLatestIssueCoverUrl();`). When I send the message from the US phone number, I get this message: ![Get notified of new magazine issues using web scraping and SMS with C# .NET - image 7](/images/vpblogimg/2026/08/Get-notified-of-new-magazine-issues-using-web-scraping-and-SMS-with-CSharp-dotNET/07.png) It shows the text, the full URL to the PDF and a shortened URL of the cover image. In my case, I prefer the original message. Depending on your phone, carrier and the messaging app you use, your experience may vary. I’d recommend playing around with splitting up the notification into multiple messages, such as sending the text in one message and the cover image in another or sending text, cover image, and URL all in different messages. Try it out and decide which format you like the most. ### Schedule the Worker Service You have a working application but it only functions when you run it manually. To automate the process, move the code into the Worker.cs class shown below: ```csharp using MagazineTracker.Data; namespace MagazineTracker; public class Worker : BackgroundService { private readonly ILogger _logger; private readonly IMagazineIssueRepository _magazineIssueRepository; private readonly IMagazineTrackerService _magazineTrackerService; private readonly INotificationService _notificationService; public Worker(ILogger logger, IMagazineIssueRepository magazineIssueRepository, IMagazineTrackerService magazineTrackerService, INotificationService notificationService) { _logger = logger; _magazineIssueRepository = magazineIssueRepository; _magazineTrackerService = magazineTrackerService; _notificationService = notificationService; } protected override async Task ExecuteAsync(CancellationToken stoppingToken) { while (!stoppingToken.IsCancellationRequested) { _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now); var latestProcessedIssue = await _magazineIssueRepository.GetLatestIssue(); var latestIssueNumber = await _magazineTrackerService.GetLatestIssueNumber(); if (latestIssueNumber > latestProcessedIssue.IssueNumber) { _logger.LogInformation("New issue detected: {latestIssueNumber}", latestIssueNumber); var coverUrl = await _magazineTrackerService.GetLatestIssueCoverUrl(); var pdfUrl = await _magazineTrackerService.GetIssuePdfUrl(latestIssueNumber); await _notificationService.SendNewIssueNotification(latestIssueNumber, coverUrl, pdfUrl); await _magazineIssueRepository.SaveLatestIssue(latestIssueNumber); } else { _logger.LogInformation("No new issue is detected."); } await Task.Delay(1000 * 60 * 60, stoppingToken); // Run hourly } } } ``` This way, you can remove all the previous test code and initializations and Program.cs becomes very concise: ```csharp using MagazineTracker; using MagazineTracker.Data; using Twilio; IHost host = Host.CreateDefaultBuilder(args) .ConfigureServices((hostBuilderContext, services) => { services.AddHostedService(); services.AddTransient<IMagazineIssueRepository, JsonMagazineIssueRepository>(); services.AddTransient<IMagazineTrackerService, MagPiTrackerService>(); services.AddTransient<INotificationService, SmsService>(); services.Configure(hostBuilderContext.Configuration.GetSection("DatabaseSettings")); services.Configure(hostBuilderContext.Configuration.GetSection("SmsSettings")); var accountSid = hostBuilderContext.Configuration["Twilio:AccountSid"]; var authToken = hostBuilderContext.Configuration["Twilio:AuthToken"]; TwilioClient.Init(accountSid, authToken); }) .Build(); await host.RunAsync(); ``` Now run the application again (reset the database first to a value lower than the latest issue number), and you should receive an SMS/MMS; your database should be updated with the latest issue number, and your service should wait for 1 hour and then run the code again. You can, of course, change how often you would like to check for new issues by changing the delay. ## Conclusion My favorite projects are the ones that I develop to solve a real problem of mine. This one was a small issue, but I like the idea of automating something that otherwise I’d forget. Even though there is one implementation of a magazine tracker service, you can adapt the existing code for your favorite publication. As long as you add a new class that implements the same interface, you can replace the registration code in Program.cs and your application will start fetching that magazine. The same goes for the notification. You can replace SMS/MMS with email using [SendGrid](https://www.twilio.com/blog/send-emails-using-the-sendgrid-api-with-dotnetnet-6-and-csharp) or [WhatsApp](https://www.twilio.com/blog/send-a-whatsapp-message-with-c-in-30-seconds). If you'd like to keep learning, I recommend taking a look at these articles: - [How to send vCards with WhatsApp using C# and .NET](https://www.twilio.com/blog/send-vcards-with-whatsapp-using-csharp-and-dotnet) - [Send Emails with C#, Handlebars templating, and Dynamic Email Templates](https://www.twilio.com/blog/send-emails-with-csharp-handlebars-templating-and-dynamic-email-templates) - [Render Emails Using Razor Templating](https://www.twilio.com/blog/render-emails-using-razor-templating)
]]> <![CDATA[Generate images with DALL·E 2 and Twilio SMS using ASP.NET Core]]> 2026-08-05T12:35:00+00:00 https://volkanpaksoy.com/archive/2026/08/05/Generate-images-with-DALL-E-2-and-Twilio-SMS-using-ASPNET-Core

This article was originally published on the Twilio Blog.

Recently, there has been a massive boost in AI-generated art. It came to a point that an AI-generated piece of art won a contest a few months ago. There are many art generation programs available such as OpenAI DALL·E 2, Midjourney, Stable Diffusion, etc. In this article, you will use DALL·E 2 to generate images. They recently made their system available to the general public without a waitlist and also opened their API. They also give free credits so you can follow this article for free. You can also get the final source code from my GitHub repository.

Prerequisites

You’ll need the following things in this tutorial:

OpenAI and DALL-E 2

OpenAI started as a non-profit artificial intelligence research organization founded by Elon Musk and Sam Altman. Elon Musk later quit the company. Currently, it operates under OpenAI LP, a “capped-profit” company (a hybrid of profit and non-profit models).

DALL-E, is a machine learning model that uses GPT-3 to generate realistic images from a description. It was initially announced in January 2021. The latest iteration of the system, DALL-E 2, was announced in April 2022. It initially required joining a waiting list, and after you’ve been accepted, you could only generate images using their web front-end. Those limitations have now been lifted, and you can sign up and start using their API to generate images.

Overview of DALL-E 2 Front-End

When you go to the DALL-E 2 website and log in, you see an input box and a Generate button.

Generate images with DALL·E 2 and Twilio SMS using ASP.NET Core - image 1

The simplicity in the design reminds me of the Google homepage. It even has a “Surprise me” option which is similar to the “I’m feeling lucky” button.

Enter your description and press the Generate button. In a matter of seconds, you will see 4 image suggestions generated for you based on your description as shown below.

Generate images with DALL·E 2 and Twilio SMS using ASP.NET Core - image 2

You get 50 credits upon sign up but they expire after a month. After that, you get 15 free credits every month. 1 image generation costs 1 credit. You can check your credit status by clicking on your profile image on the upper right-hand corner.

Generate images with DALL·E 2 and Twilio SMS using ASP.NET Core - image 3

If you hover over the images, you see a “…” button appear. Click on it and the “Quick Actions” menu opens.

Generate images with DALL·E 2 and Twilio SMS using ASP.NET Core - image 4

Here you can download the image or generate more variations based on this. The new variations are quite similar to the original one though, as they are all based on the same description.

Generate images with DALL·E 2 and Twilio SMS using ASP.NET Core - image 5

You can keep on generating variations from variations as well. Generating variations also costs 1 credit.

Overview of OpenAI Account

To be able to use the OpenAI API, you will need an API key and some credits. When you sign up, OpenAI gives you free credits. Note that this is different from the 50 credits DALL-E 2 gave.

To check your credit status, go to your account page.

You should see your usage breakdown and your credit status.

Generate images with DALL·E 2 and Twilio SMS using ASP.NET Core - image 6

You get quite a lot of credits ($18) considering 1 image generation costs $0.02. There are even cheaper options depending on the image size and generation model.

Generate images with DALL·E 2 and Twilio SMS using ASP.NET Core - image 7

You can check the pricing page for full details.

After you’ve confirmed you have free credits granted, click on API Keys on the left menu.

Here, click on the Create new secret key button.

As the prompt says, save your secret key somewhere safe as you’ll not have another chance to see it.

Generate images with DALL·E 2 and Twilio SMS using ASP.NET Core - image 8

Now that you’ve familiarized yourself with image generation, have your API key and credits available, move on to the next section to implement your own API to send the DALL-E-2-generated images.

Project Implementation

To be able to generate the images, you will need to receive the image description from the user via SMS. To achieve this, you will implement a web API that responds to Twilio SMS webhook requests.

Create the API by running the following commands in a terminal:

mkdir Dalle2ImageSmsApi
cd Dalle2ImageSmsApi
dotnet new webapi

Since you’re going to use Twilio, add Twilio .NET SDK and ASP.NET helper library via NuGet:

dotnet add package Twilio
dotnet add package Twilio.AspNet.Core

Open the project with your IDE.

Under the Controllers directory, create a new file called IncomingSmsController.cs and update its contents with the code below:

using Microsoft.AspNetCore.Mvc;
using Twilio.AspNet.Core;
using Twilio.TwiML;
using Twilio.TwiML.Messaging;
namespace Dalle2ImageSmsApi.Controllers;
[ApiController]
[Route("[controller]")]
public class IncomingSmsController : TwilioController
{
    [HttpPost]
    public async Task<TwiMLResult> Index()
    {
        var form = await Request.ReadFormAsync();
        var incomingText = form["Body"];
        var message = new Message();
        message.Body($"Here's the image for your query: {incomingText}");
        message.Media(new Uri("https://picsum.photos/1024/1024"));
        return new MessagingResponse()
            .Append(message)
            .ToTwiMLResult();
    }
}

The code above extracts the text message sent by the user (which is sent in the Body paramater field of the form encoded request body.).

This message will be used to generate the image. For now, just for testing purposes, you will ignore this message and return a random photo from an online service called picsum.photos which is a handy service to create random placeholder images. You can use this service to test and format your response messages without wasting your OpenAI credits.

Run the application by running the following command in the terminal window:

dotnet run

You should see your application running on your localhost.

Generate images with DALL·E 2 and Twilio SMS using ASP.NET Core - image 9

You want Twilio to send webhook requests to your API, but currently Twilio cannot access your localhost. To fix this issue, you will tunnel your localhost to the internet with ngrok.

Copy the localhost URL, open another terminal and run the following command:

ngrok http { YOUR LOCALHOST URL }

Replace { YOUR LOCALHOST URL } with the value you copied from the other terminal (It would be http://localhost:5252 in this example)

You should see ngrok generate a random Forwarding URL and ngrok will now forward the traffic from this URL to your local API:

Generate images with DALL·E 2 and Twilio SMS using ASP.NET Core - image 10

Now that you have a publicly accessible URL, you can tell Twilio where to send webhook requests.

Go to Twilio Console. Then go to Phone Numbers → Manage → Active Numbers and click on your number.

Scroll down to the messaging section. Select Webhook in the “A MESSAGE COMES IN” part and enter your ngrok URL followed by /IncomingSms as shown below:

Generate images with DALL·E 2 and Twilio SMS using ASP.NET Core - image 11

Click Save.

Now that the environment is set up, send an SMS to your Twilio phone and see if you can receive a random image as response. If you can receive the image, it means it’s now time to generate images using the OpenAI API.

Implement OpenAI Client

The image generation API is still in beta as of this writing. Using image generation is quite straightforward. You send the description of the image, size, and the number of images you want to get. In this project, you will use an open-source client library which has recently been updated to support DALL-E.

Stop your application if it’s still running and run the following command in the terminal window:

dotnet add package Betalgo.OpenAI.GPT3

You will need your OpenAI API key to use the API that you created in the previous section. You will use .NET user secrets to store it. Run the following command to initialize the user secrets:

dotnet user-secrets init

Then, add the API key to the secrets by running the following command, replacing {YOUR OPENAI API KEY} with the actual API key value:

dotnet user-secrets set OpenAIServiceOptions:ApiKey {YOUR OPENAI API KEY}

Update Program.cs and add the highlighted lines:

```csharp hl_lines=”1 11” using OpenAI.GPT3.Extensions; var builder = WebApplication.CreateBuilder(args); // Add services to the container. builder.Services.AddControllers(); // Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(); builder.Services.AddOpenAIService();


Now you can inject the service to your `IncomingSmsController` controller as shown below. The highlighted lines are what’s new and updated.

```csharp hl_lines="2 3 14 16 17 18 19 20 21 22 23 24 25 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 56"
using Microsoft.AspNetCore.Mvc;
using OpenAI.GPT3.Interfaces;
using OpenAI.GPT3.ObjectModels.RequestModels;
using Twilio.AspNet.Core;
using Twilio.TwiML;
using Twilio.TwiML.Messaging;
namespace Dalle2ImageSmsApi.Controllers;
[ApiController]
[Route("[controller]")]
public class IncomingSmsController : TwilioController
{
    private readonly ILogger<IncomingSmsController> _logger;
    private readonly IOpenAIService _openAiService;
    public IncomingSmsController(
        ILogger<IncomingSmsController> logger, 
        IOpenAIService openAiService
    )
    {
        _logger = logger;
        _openAiService = openAiService;
    }
    [HttpPost]
    public async Task<TwiMLResult> Index()
    {
        var form = await Request.ReadFormAsync();
        var incomingText = form["Body"];
        var createImageRequest = new ImageCreateRequest
        {
            Size = "1024x1024",
            N = 1,
            Prompt = incomingText,
            ResponseFormat = "url"
        };
        var createImageResponse = await _openAiService.Image.CreateImage(createImageRequest);
        if(!createImageResponse.Successful)
        {
            var errorMessage = "An error occurred trying to create OpenAI image." +
                $" {createImageResponse.Error.Code}: {createImageResponse.Error.Message}.";
            _logger.LogError(errorMessage);
            return new MessagingResponse()
                .Message("An unexpected error occurred. Try again later.")
                .ToTwiMLResult();
        }
        var image = createImageResponse.Results.First();
        var message = new Message();
        message.Body($"Here's the image for your query: {incomingText}");
        message.Media(new Uri(image.Url));
        return new MessagingResponse()
            .Append(message)
            .ToTwiMLResult();
    }
}

The action now construct a CreateImageRequest object with size set to 1024x1024, the number of images requested set to 1, and passes in the image description received from the incoming text message. It also sets the response format to url as it will pass Twilio the URL of the image. Valid values for ResponseFormat are url and b64_json.

Run the application again. To test the implementation, send an SMS to your Twilio phone again. This time the image returned should match your description.

For example, I sent the following description: “a golden retriever puppy playing with a kitten”:

Generate images with DALL·E 2 and Twilio SMS using ASP.NET Core - image 12

When I clicked the link, I got the following image:

Generate images with DALL·E 2 and Twilio SMS using ASP.NET Core - image 13

I’m happy with the puppy but the kitten seems a bit odd. Of course, the nice thing about it is, if you don’t like the result, you can always request more.

As an improvement, you can make the image size and the number of images customizable.

Conclusion

In this tutorial, you learned the basics of DALL-E 2 via using the front-end. Then implemented your own service to interact with OpenAI API. The service responds to Twilio SMS webhooks and uses DALL-E 2 to generate images based on the user’s description and sends the image back to the user.

The resulting image may or may not be satisfactory based on the description. These are the early days of AI-generated images and I’m sure they will keep on getting better and better.

If you’d like to keep learning, I recommend taking a look at these articles:

]]> <![CDATA[Forward Voicemails with Transcript to your Email using C# and ASP.NET Core]]> 2026-08-05T12:30:00+00:00 https://volkanpaksoy.com/archive/2026/08/05/Forward-Voicemails-with-Transcript-to-your-Email-using-CSharp-and-ASPNET-Core

This article was originally published on the Twilio Blog.

Whether you like it or not, phone calls are essential to our daily communications. However, sometimes nobody is available to take the call right there and then. Luckily, Twilio Programmable Voice lets you record voicemail so the caller can leave a message. But what if instead of having to call into a voicemail box, you could receive the voicemail and transcript in as an email instead? In this article, you will build a Twilio Voice app that sends voicemails and the call transcript to your email address using SendGrid.

Prerequisites

You’ll need the following things in this tutorial:

Project Overview

Before jumping into the code, let’s take a look at how the application will work.

Take a look at this diagram of the application flow:

Forward Voicemails with Transcript to your Email using C# and ASP.NET Core - image 1

  • Someone calls your Twilio Phone Number. Twilio picks up the call and forwards the details via HTTP to your Web API.

  • Your Web API responds with TwiML instructions. These instructions tell Twilio what to do with the phone call. You’ll learn more about TwiML later. Your TwiML instructions tell Twilio to record a voicemail and to send the recording transcript back to your Web API.

  • The caller leaves a message which Twilio records and transcribes.

  • When Twilio is done transcribing the recording, Twilio sends the transcription via HTTP to your Web API.

  • Your Web API will download the voicemail audio file (as MP3) and then use SendGrid to send an email with the phone number of the caller, the transcript of the voicemail, and the voicemail audio file itself.

  • SendGrid will deliver the email to your email inbox.

When Twilio receives a phone call, Twilio will send the details as an HTTP request to a URL that you configure and expect instruction as an HTTP response. This concept is called a webhook and is commonly used across Twilio products.

However, Twilio can only send HTTP requests to publicly available URLs, and you’ll be developing your application locally. To solve this, you’ll tunnel your localhost publicly using the free ngrok service. This wouldn’t be necessary in production, but is necessary for Twilio to reach your locally running web application. More on this later!

To instruct Twilio what to do with the phone call, you need to respond to the webhook HTTP request using a specific set of instructions called the Twilio Markup Language, or TwiML for short. TwiML is a specific set of XML tags that you can use to tell Twilio how to respond to voice calls and text messages. In this application you will use these two TwiML verbs: <Say> and <Record>.

<Say> will convert text to speech and send the audio to the caller. <Record> will record the audio of the phone call which you will use to implement voicemail functionality. These TwiML verbs can also have attributes and nested noun-tags. To instruct Twilio to transcribe the recording and send the transcription to your web application, you’ll be using the transcribe and the transcribeCallback attribute. Using these TwiML verbs and attributes, you’ll generate TwiML that looks like this:

<?xml version="1.0" encoding="utf-8"?>
<Response>
  <Say>Hello. I'm not available at the moment. Please leave a message after the beep.</Say>
  <Record timeout="10" transcribe="true" transcribeCallback="/TranscribeCallback"></Record>
</Response>

!!!info

When you pass in a relative URL to transcribeCallback, Twilio will resolve the relative URL relatively to the URL it sent the HTTP request to. When using an absolute URL, Twilio will resolve the URL relatively to the root path of the URL it sent the HTTP request to.

!!!

This is all the TwiML you’ll be using in this application, but I recommend learning more about TwiML for Voice in the docs, and specifically to look deeper into the Say-verb and the Record-verb.

Now that you understand how the application will work, let’s get started.

Create the ASP.NET Core Web API

!!!info

If you’d prefer to get the final project directly, you can get it from my GitHub repository, or follow the steps below to implement it yourself.

!!!

The first step is to create a new Web API project to handle the Twilio webhooks and send the emails. You can do this by opening a terminal and running these commands:

mkdir VoicemailForwarderWebApi
cd VoicemailForwarderWebApi
dotnet new webapi

Run the application to confirm everything is in good order:

dotnet run

Your output should look like this:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7117
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5162
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.

This project template comes with a WeatherForecast controller. Open a new browser tab and browse to your HTTP URL with the /WeatherForecast path (in this example: http://localhost:5162/WeatherForecast). You should see results like this:

[{"date":"2022-08-17T13:41:31.816102+01:00","temperatureC":18,"temperatureF":64,"summary":"Cool"},{"date":"2022-08-18T13:41:31.817042+01:00","temperatureC":52,"temperatureF":125,"summary":"Balmy"},{"date":"2022-08-19T13:41:31.817048+01:00","temperatureC":21,"temperatureF":69,"summary":"Mild"},{"date":"2022-08-20T13:41:31.81705+01:00","temperatureC":-10,"temperatureF":15,"summary":"Mild"},{"date":"2022-08-21T13:41:31.817051+01:00","temperatureC":-19,"temperatureF":-2,"summary":"Mild"}]

This setup works fine in your local environment, but for Twilio to be able to send HTTP requests to your endpoints, your API needs to be publicly accessible over the internet.

You can achieve that with ngrok, which tunnels public requests to your local machine.

Leave your .NET app running, then open a separate terminal and run ngrok with the following command:

ngrok http YOUR_HTTP_PORT

You should see some random URL generated for you which is forwarding to your local API:

Forward Voicemails with Transcript to your Email using C# and ASP.NET Core - image 2

Now append the endpoint path /WeatherForecast to the Forwarding URL and open it in a browser tab.

!!!info

If this doesn’t work for you, comment out app.UseHttpsRedirection(); in Program.cs and restart the application hitting ctrl + c and running dotnet run again. Alternatively, you can start ngrok with the following command:

ngrok http https://localhost:YOUR_HTTPS_PORT --host-header="localhost:YOUR_HTTPS_PORT"

!!!

You may see a warning message from ngrok:

Forward Voicemails with Transcript to your Email using C# and ASP.NET Core - image 3

Click Visit Site to proceed.

You should see similar results to before, but now via ngrok’s public forwarding URL. This means that your API is publicly accessible and Twilio can send HTTP requests to it.

Receive Incoming Calls

Twilio provides libraries to make it easier to build Twilio applications. You will use two of those in this tutorial: The Twilio .NET SDK and the helper library for ASP.NET. You’ll use the SDK to generate TwiML and the helper library to respond to webhook requests.

Back in the terminal where your app is running, stop the application using ctrl + c and add the SDK and helper library for ASP.NET Core via NuGet:

dotnet add package Twilio
dotnet add package Twilio.AspNet.Core

Open the project in your IDE and add a new file in the Controllers folder called IncomingCallController.cs. Update the controller with the code below:

using Microsoft.AspNetCore.Mvc;
using Twilio.AspNet.Core;
using Twilio.TwiML;
namespace VoicemailForwarderWebApi.Controllers;
[ApiController]
[Route("[controller]")]
public class IncomingCallController : TwilioController
{
    [HttpPost]
    public TwiMLResult Index()
    {
        var response = new VoiceResponse();
        response.Say("So far, so good!");
        return TwiML(response);
    }
}

When Twilio sends an HTTP POST request to /IncomingCall this action will generate TwiML including the Say-verb which will instruct Twilio to say “So far, so good!” to the caller.

For Twilio to know where to send webhook requests, you need to update the webhook settings on your Twilio Phone Number.

Go to the Twilio Console. Select your account, and then click Phone Numbers → Manage → Active Numbers on the left pane. (If Phone Numbers isn’t on the left pane, click on Explore Products and then on Phone Numbers.)

Click on the phone number you want to use for your project and scroll down to the Voice section.

Under the “A Call Comes In” label, set the dropdown to Webhook, the text field next to it to the ngrok Forwarding URL suffixed with the /IncomingCall path, the next dropdown to HTTP POST, and click Save. It should look like this:

Forward Voicemails with Transcript to your Email using C# and ASP.NET Core - image 4

Now, run the application (dotnet run) and call your Twilio number, and you should hear the message “So far, so good” on your phone. Great job if this is working. If not, there are a couple of places where you can go to debug:

  • You may see errors in the output from your .NET application in the terminal

  • Check the output of the ngrok command in the other terminal, or browse to the ngrok dashboard (http://127.0.0.1:4040) where you can inspect HTTP requests and responses.

  • You can find errors and call details in the Twilio Console under the Monitor tab.

Now that you verified the webhook is working, let’s update the TwiML so the caller can leave a voicemail. To do this, update the Say-verb to prompt the user to leave a message, and use the Record-verb to record the call.

Update your Index method as below:

var response = new VoiceResponse();
response.Say("Hello. I'm not available at the moment. Please leave a message after the beep.");
response.Record(
    timeout: 10,
    transcribe: true,
    transcribeCallback: new Uri("/TranscribeCallback", UriKind.Absolute)
);
return TwiML(response);

The timeout attribute tells Twilio to end the recording after a number of seconds of silence has passed. The default is 5 seconds. You can change this to your liking.

By setting the transcribe attribute to true, you’ll instruct Twilio to transcribe the recording. Twilio will also store the transcription so you can retrieve the transcription later via the Twilio API.

The transcription process happens asynchronously. Twilio can send the transcript data to your application when it is ready. Use the transcribeCallback attribute to tell Twilio to which URL to send the transcription data when it is ready.

Now move on to handle the transcription webhook.

Receive Transcription Text and Recording Info

Twilio returns the transcription text and the recording URL in the transcribe callback message. So you can gather everything you need by handling the transcribe callback.

Add a new file under the Controllers folder named TranscribeCallbackController.cs. Update its contents as below:

using Microsoft.AspNetCore.Mvc;
using Twilio.AspNet.Core;
namespace VoicemailForwarderWebApi.Controllers;
[ApiController]
[Route("[controller]")]
public class TranscribeCallbackController : TwilioController
{
    private readonly ILogger<TranscribeCallbackController> _logger;
    public TranscribeCallbackController(ILogger<TranscribeCallbackController> logger)
    {
        _logger = logger;
    }
    [HttpPost]
    public async Task Index()
    {
        var form = await Request.ReadFormAsync();
        var recordingSid = form["RecordingSid"].ToString();
        var recordingUrl = form["RecordingUrl"].ToString();
        var transcriptionText = form["TranscriptionText"].ToString();
        var callingNumber = form["From"].ToString();
        _logger.LogInformation("Transcription details -> CallingNumber: [{callingNumber}] TranscriptionText: [{transcriptionText}], RecordingSid: [{recordingSid}], RecordingUrl: [{recordingUrl}]", 
            callingNumber, transcriptionText, recordingSid, recordingUrl);
    }
}

To test your changes, restart your .NET application, then call your Twilio number again and leave a message. After a few seconds, you should see a new log line like this in your terminal:

Forward Voicemails with Transcript to your Email using C# and ASP.NET Core - image 5

!!!warning

By default, Recording URLs don’t require authentication, and recordings are not encrypted. However, you can require basic authentication to access the recordings and configure recordings to be encrypted in the voice settings (Voice → Settings → General).

!!!

Download the call recording

The next step is to get the recording audio. The audio is available in two formats: WAV and MP3. WAV files are uncompressed and have larger file sizes. Since they will be sent as attachments, in this example, you will download the MP3 version for efficiency.

First, you will need an HttpClient to download the file. Add the highlighted line below to your Program.cs file:

```csharp hl_lines=”3” builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(); builder.Services.AddHttpClient();


Update TranscribeCallbackController.cs so that the constructor and the private variables look like below:

```csharp hl_lines="2 4 7"
private readonly ILogger<TranscribeCallbackController> _logger;
private readonly IHttpClientFactory _httpClientFactory;
public TranscribeCallbackController(ILogger<TranscribeCallbackController> logger, IHttpClientFactory httpClientFactory)
{
    _logger = logger;
    _httpClientFactory = httpClientFactory;
}

Now you can instantiate an HttpClient and download the file at recordingUrl by adding the following code to your Index() method in the TranscribeCallbackController:

var httpClient = _httpClientFactory.CreateClient();
var recordingBytes = await httpClient.GetByteArrayAsync($"{recordingUrl}.mp3");
var recordingFilePath = $"{recordingUrl.Substring(recordingUrl.LastIndexOf("/") + 1)}.mp3";
System.IO.File.WriteAllBytes(recordingFilePath, recordingBytes);

By default, the recording URL doesn’t have a file extension. If you call the URL as is, Twilio returns the WAV version of the recording. To get the MP3 version, you need to append the .mp3 extension to the URL as shown above.

Restart your application, call your Twilio number again and leave a message. Once Twilio sends the transcription to your application, you should see an MP3 file appear in your project folder. You won’t actually need to save the file to disk for this tutorial, but you can do this to quickly test that it works so far.

Send the Voicemail via Email

Now that you have the transcribed text and the call recording audio, the final step is to create an email and send these to your email address.

To achieve this, you’re going to use SendGrid SDK.

Stop the application and add the following packages via NuGet:

dotnet add package SendGrid
dotnet add package SendGrid.Extensions.DependencyInjection

To send emails via SendGrid, you will need to use your API key and store it somewhere. You can use environment variables or a vault service, but for local development you can use dotnet user secrets. First, you need to initialize user secrets by running

dotnet user-secrets init

Then, create a new user secret called SendGrid:ApiKey and set your API key:

dotnet user-secrets set SendGrid:ApiKey {YOUR SENDGRID API KEY}

Replace {YOUR SENDGRID API KEY} with your SendGrid API Key (see prerequisites).

Now apply the following code changes. First, update Program.cs as shown below:

```csharp hl_lines=”4” builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(); builder.Services.AddHttpClient(); builder.Services.AddSendGrid(options => options.ApiKey = builder.Configuration[“SendGrid:ApiKey”]);


And add the following using statement to the top of the Program.cs file:

```csharp
using SendGrid.Extensions.DependencyInjection;

Then, update your TranscribeCallbackController to inject the ISendGridClient and store it in a private field:

```csharp hl_lines=”3 8 13” private readonly ILogger _logger; private readonly IHttpClientFactory _httpClientFactory; private readonly ISendGridClient _sendGridClient; public TranscribeCallbackController( ILogger logger, IHttpClientFactory httpClientFactory, ISendGridClient sendGridClient ) { _logger = logger; _httpClientFactory = httpClientFactory; _sendGridClient = sendGridClient; }


Also, add these using statements to the top of the TranscribeCallbackController.cs file:

```csharp
using SendGrid;
using SendGrid.Helpers.Mail;

Finally, update the Index method of the TranscribeCallbackController controller so that the final version looks like this:

var form = await Request.ReadFormAsync();
var recordingSid = form["RecordingSid"].ToString();
var recordingUrl = form["RecordingUrl"].ToString();
var transcriptionText = form["TranscriptionText"].ToString();
var callingNumber = form["From"].ToString();
_logger.LogInformation("Transcription details -> CallingNumber: [{callingNumber}] TranscriptionText: [{transcriptionText}], RecordingSid: [{recordingSid}], RecordingUrl: [{recordingUrl}]", 
    callingNumber, transcriptionText, recordingSid, recordingUrl);
var httpClient = _httpClientFactory.CreateClient();
var recordingBytes = await httpClient.GetByteArrayAsync($"{recordingUrl}.mp3");
var from = new EmailAddress("{your sender email}", "{your sender display name}");
var to = new EmailAddress("{your recipient email}", "{your recipient display name}");
var subject = "You've got voicemail!";
var plainTextContent = $"Calling Number: {callingNumber}{Environment.NewLine}Transcription: {transcriptionText}";
var htmlContent = $"<p>Calling Number: {callingNumber}</p><p>Transcription: {transcriptionText}</p>";
var msg = MailHelper.CreateSingleEmail(from, to, subject, plainTextContent, htmlContent);
msg.AddAttachment(
    new Attachment
    {
        Content = Convert.ToBase64String(recordingBytes),
        Filename = "voicemail.mp3",
        Type = "audio/mpeg",
        Disposition = "attachment"
    });
var sendEmailResponse = await _sendGridClient.SendEmailAsync(msg);
_logger.LogInformation(sendEmailResponse.IsSuccessStatusCode ? "Email queued successfully!" : "Something went wrong!");

!!!warning

Since you don’t know what’s in the recording and the transcription text, you should assume it could contain personal information. I am logging the transcription text for debugging purposes, but you should avoid doing so in production to protect PII.

!!!

Before running the application, replace {your verified sender email}, {your sender display name}, {your recipient email} and {your recipient display name} with actual values. Display names can be anything you choose. The sender email address needs to be a verified sender in SendGrid (see prerequisites).

Start your application again as before:

dotnet run

The code above creates a new email with the MP3 file as an attachment, and the phone number and transcribed text as the body of the email.

Test your application one last time by calling your Twilio number and leaving a voice message. After a few seconds, you should receive an email that looks like this:

Forward Voicemails with Transcript to your Email using C# and ASP.NET Core - image 6

Conclusion

The email you send may not look pretty, but it does the job. You can use SendGrid Dynamic Email Templates and create beautiful HTML email templates. If you are interested in sending templated emails with SendGrid, take a look at these articles:

To find out more about using voicemails with Twilio, tunneling, and ngrok, here are some of the articles to read:

]]> <![CDATA[Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS]]> 2026-08-05T12:25:00+00:00 https://volkanpaksoy.com/archive/2026/08/05/Create-an-SMS-chatbot-using-CSharp-Amazon-Lex-and-Twilio-SMS

This article was originally published on the Twilio Blog.

There is a tough competition in the business world to acquire and retain customers. One key step to achieve this goal is to keep your customers happy with your customer support. Having an automated chatbot helps your business provide a faster and more accessible customer support to your customers. In this article, you will learn how to build a chatbot using C#, AWS Lambda, Amazon Lex, Amazon DynamoDB, and Twilio SMS.

Prerequisites

You’ll need the following things in this tutorial:

What is Amazon Lex?

Amazon Lex is an artificial intelligence service that allows developers to create voice or text-based conversational interfaces. This service powers Amazon’s own Alexa.

Lex provides automatic speech recognition and natural language understanding technologies. It takes the user’s input, runs it through a Natural Language Processing (NLP) engine and determines the user’s intent. The value of this is the user does not need to remember a set of commands to interact with your bot. They can talk to the bot just like they would to a human being.

This project uses several AWS services: Lex, Lambda and DynamoDB. To follow along, you will need an IAM user setup in your development environment. Proceed to the next section for the IAM setup. If you already have it configured, you can skip the next section and move on to the Project Overview.

If you created a new AWS account, this project shouldn’t cost you anything, as all these services have free tiers. If you are on an older account, it shouldn’t cost too much. Still, I recommend checking the pricing pages of the services anyway: Amazon Lex Pricing, AWS Lambda Pricing and Amazon DynamoDB pricing.

Set up AWS IAM User

You will need credentials to deploy your application to AWS from the command line. To create the credentials, follow the steps below:

First, go to the AWS IAM Users Dashboard and click the Add users button.

Enter the user name, such as twilio-webhook-user and tick the Access key - Programmatic access checkbox:

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 1

Click the Next: Permissions button at the bottom right.

Then, select Attach existing policies directly and select AdministratorAccess:

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 2

Click the Next: Tags button at the bottom right. Tags are optional (and quite valuable information), and it’s a good practice to add descriptive tags to the resources you create. Since this is a demo project, you can skip this step and click the Next: Review button at the bottom.

Confirm your selection on the review page. It should look like this:

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 3

Then, click the Create user button.

In the final step of the user creation process, you should see your credentials for the first and the last time.

!!!warning

Take note of your Access key ID and Secret access key before you press the close button.

!!!

Now, open a terminal window and run the following command:

aws configure

You should see a prompt for AWS Access Key ID. Copy and paste your access key ID and press enter.

Then, copy and paste your secret access key and press enter.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 4

When prompted, type us-east-1 as the default region name and press enter.

!!!info

In this example, I will use the us-east-1 region. Regions are geographical locations where AWS have their data centers. It is a good practice to deploy as close to your customers as possible for production deployments to reduce latency. Since this is a demo project, you can use us-east-1 for convenience as it’s the default region in AWS Management Console. You can find more on AWS regions in this document: Regions and Availability Zones.

!!!

As the default output format, type json and press enter.

To confirm you have configured your AWS profile correctly, run the following command:

aws configure list

The output should look like this:

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 5

Now that you have set up your AWS credentials, you can move on to the demo project.

Project Overview

The application you will implement is an imaginary online stock broker customer service. It will accept requests like buy, sell, show portfolio, etc.

Take a look at this diagram of the application flow:

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 6

  • Customer sends an SMS to customer service (which is a Twilio Phone Number).

  • Twilio receives the message and invokes the Amazon Lex callback.

  • Amazon Lex identifies the user’s intent and calls the corresponding Lambda function.

  • The Lambda function executes the application logic based on the request, gets the customer info from the DynamoDB database, and prepares the response.

  • Lex sends the response to Twilio using the Twilio SMS integration.

  • Twilio delivers the response message to the customer’s phone.

Without further ado, let’s get the demo application and start exploring the existing code.

Set up the Demo Project

The focus of this article is developing a chatbot using Amazon Lex and Twilio SMS. To save time, the fundamental business logic of the fictional stock broker is implemented in the starter project.

Clone the project to get started:

git clone https://github.com/cloudinternals/amazon-lex-stock-broker-bot-with-twilio-sms.git --branch starter-project

Open the solution (src/StockBrokerBot/StockBrokerBot.sln) in your IDE and take a look at the project structure. The StockBrokerBot.Core project looks like this:

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 7

The main functionality is in 2 services: IPortfolioService and IStockMarketService.

IPortfolioService shows the behaviour of the service:

public interface IPortfolioService
{
    Task<UserPortfolio> GetUserPortfolio(string userId);
    Task<UserPortfolio> BuyStocks(string userId, string stockName, decimal numberOfShares);
    Task<UserPortfolio> SellStocks(string userId, string stockName, decimal numberOfShares);
}

It supports 3 operations: Get portfolio, buy stocks, and sell stocks.

The core library includes one implementation of the portfolio service called PortfolioService. It depends on a stock market service and a portfolio data provider:

private readonly IStockMarketService _stockMarketService;
private readonly IPortfolioDataProvider _dataProvider;
public PortfolioService(IStockMarketService stockMarketService, IPortfolioDataProvider dataProvider)
{
    _stockMarketService = stockMarketService;
    _dataProvider = dataProvider;
}

PortfolioService performs validations during buy and sell operations (user has sufficient funds to buy, or shares available to sell, etc.)

IStockMarketService is responsible for fetching the current stock price:

public interface IStockMarketService
{
    Task<decimal> GetStockPrice(string stockName);
}

There are 2 different stock market service implementations: StockMarketService, and FluctuatingStockMarketService.

StockMarketService simply fetches the stock price from its data provider. FluctuatingStockMarketService is meant to “spice things up” a little bit. It calculates a random price by adding a small price swing within 2%. You can, of course, change this rate to create higher swings. This way, you will get a new price every time. So you can buy low and sell high and make some imaginary profits!

The starter project also includes a demo console application. The demo application uses JSON files to persist user portfolios and stock prices. In the actual chatbot, you will use DynamoDB tables. The demo project uses the FluctuatingStockMarketService. You can replace it with StockMarketService to get more consistent results.

UserPortfolio and Stock entities are already annotated to be used as DynamoDB entities:

[DynamoDBTable("user-portfolio")]
public class UserPortfolio
{
    [DynamoDBHashKey]
    public string UserId { get; set; }

!!!info

In a real project, I wouldn’t recommend creating a dependency on a storage provider from your business library but for the sake of brevity, the same entities will be used in this project.

!!!

Open a terminal, navigate to the demo project, and run the application by running:

cd StockBrokerBot.Demo
dotnet run

You should see the results that look like this:

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 8

Take some time to look into the core library and the consuming demo application. There is also a Lambda function project in the solution called StockBrokerBot.ChatbotLambda, but it’s empty at the moment. You will implement it while following this article.

When you are more familiar with the project, move on to the next section to create the chatbot.

Create the Chatbot with Amazon Lex

To start implementing your bot, go to Lex Console and click Create bot.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 9

In the settings, leave the Create a blank bot option selected.

In the Bot name field, enter StockBrokerBot.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 10

In IAM permissions, select Create a role with basic Amazon Lex permissions.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 11

Select No in the COPPA section and click Next.

In the Add languages step, leave the default language (English (US)). You can choose to support multiple languages and even assign a different voice to each language. In this article, you will use a single language and text interaction only. Click the Voice interaction dropdown, scroll to the bottom and select None. This is only a text-based application option.

Click Done to create your bot.

Your bot has now been created, and Lex redirects you to create your first intent. An intent is an action your bot takes to fulfil a user’s request.

In the Intent name field, enter CheckStockPrice.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 12

Leave Contexts blank and scroll to Sample utterances.

An utterance is a phrase that corresponds to this intent. In conversations, we use many different phrases to express the same thing. For example, if you have a Hello intent, sample utterances can be “Hello”, “Hi”, “Hey” etc.

Click Plain Text and paste the following utterances in the field:

check the {stockName} price
check {stockName}
how much is {stockName} ?
what is the price of {stockName} ?
get the price of {stockName}
{stockName}
price {stockName}
what is the current {stockName} price?
check the current price of {stockName}
price of {stockName} ?

In the above text block, you can see many occurrences of {stockName}. This is what is called a slot. It’s essentially a placeholder for a piece of data you need Lex to extract for you and pass it on to your code. If you recall the core library introduced earlier in the article, GetStockPrice method requires the stock name. A user might express their intention in a lot of different ways. Extracting this data is Lex’s responsibility so that, as the bot developer, you can focus on your bot’s business logic.

!!!warning

The space between the slot and the question mark at the end is intentional. Lex requires spaces surrounding the slots. If you remove those spaces, you will get an error while saving the intent.

!!!

Scroll down to the Slots section.

As discussed above, you’re using a slot in your utterances, but it’s not defined yet. Lex needs to know the type and whether or not it’s mandatory. Lex performs much better if you train what kind of data it’s looking for. In the stock name example, there is a finite set of company names, so you will create your own data type to train the model better. Skip adding a slot for now. You’ll revisit this part very soon.

Click the Save intent button and the Back to intents list link on the left pane. Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 13

!!!info

FallbackIntent is one of the built-in intents. If the user’s request doesn’t match any of the intents, FallbackIntent is invoked. You can read more about Lex’s built-in intents here.

!!!

On the left menu, click Slot types which is right under Intents.

Click Add slot type and select Add blank slot type.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 14

Enter StockName in the Slot type name field.

In the Slot value resolution, leave the Expand values option selected. You can also choose to restrict the slot values, but then you will need to enter every stock name that your service supports. It almost becomes a lookup table. Lex is smart enough to identify similar values based on your training set. The more comprehensive your training set is, the better results you will get.

Enter Apple, Alphabet, Microsoft, Tesla, and Twilio as stock names and click Save slot type.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 15

Click the Slot types link on the left, then Intents, and finally, click on the CheckStockPrice intent to get back to intent settings.

Scroll down to the Slots section and click Add slot.

Leave Required for this intent checkbox ticked.

Enter stockName in the Name field and select StockName in the Slot type list.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 16

In the Prompts field, enter What is the name of the stock?

This is a very useful feature. You don’t have to worry about asking the user for the stock name if it’s missing. Lex will automatically ask the user and fill in the missing values, so you can rest assured that it will always deliver the required values to your bot’s backend. You’ll see this in practice while testing the bot later on.

Click Add to close the dialog and then click Save Intent.

Now focus on the top of the screen.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 17

You should see the version you’re looking at (Draft version), the language (English (US)) and a label next to it that says “Not built”.

Click the Build button for Lex to build the machine learning (ML) model for your bot. You cannot test your bot without creating the ML model first. When the build is complete, you will see a notification on your screen.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 18

Click the Test button.

In the bottom field (with the Type a message placeholder), enter “What is the price of Apple?” and press enter.

You should see a message that says “Intent CheckStockPrice is fulfilled”

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 19

Click the Inspect button to see more details. You can see the stockName slot has Apple as the value. If you recall, you made the stockName a required slot. To test what happens if a user enters a message without providing sufficient information, enter “price” as the message and press enter.

!!!info

Note the title of the dialog says “Test Draft version”. When you test, you test the entire model for the selected language, not a single intent, even if you open the dialog while you are on an intent page.

!!!

You should see Lex now asks the name of the stock explicitly. The question it asks is the prompt message you entered when you created the slot type.

Just to emphasise how it works, it’s not directly looking up the utterances and matching strings to determine the intent. For example, you can express the same intent by entering “show the price of Tesla stock”, and you should still see the intent is fulfilled message even though it’s not part of the utterance list. If the expected intent is not fulfilled, you can modify your utterances, rebuild, and retest the model.

!!!warning

Before you test, make sure to build your model if you’ve made any changes. Otherwise, you’d be testing the previous model.

!!!

After the intent is recognized, what Lex will do with it is determined by the Fulfillment settings. By default, fulfilment is not active. Scroll down to the Fulfillment section and click the Active radio button. Lex invokes the Lambda function associated with your bot by default. You can confirm this behaviour by expanding the parameters and clicking the Advanced options button.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 20

Set the Fulfilment to active and ensure the Use a Lambda function for fulfilment option is ticked.

Click Save Intent and then click the Back to intents list link on the left.

Click the Add Intent button. It will show you two options: Add empty intent and Use built-in intent)

Select Add empty intent.

Enter GetPortfolio as intent name in the dialog and click Add.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 21

In the Sample utterances section, switch to Plain Text view and paste the following utterances:

​​get portfolio
show my portfolio
my portfolio
my stocks
show me the money!

In the Fulfillment section, set the Active option to true.

Click the Save intent button and Back to intents list link on the left.

Click Add intent again and set the intent name to BuyStocks. Update the utterances with the ones below as you did before:

buy {numberOfShares} of {stockName} 
buy shares {numberOfShares} ,stock {stockName}
buy {numberOfShares} {stockName}
purchase {numberOfShares} of {stockName} stock
get {numberOfShares} shares of {stockName}
buy {stockName} {numberOfShares}  shares
buy {numberOfShares} shares of {stockName}
buy {numberOfShares} shares of {stockName} stock

In the Slots section, click the Add slot button.

In the Add slot dialog, set Required for this intent to true, enter stockName as the name, select StockName as slot type and “What is the name of the stock?” as the prompt.

Click Add.

Click the Add slot button again.

This time, set the name to numberOfShares, slot type to AMAZON.Number and the prompt to “How many shares?”.

Click Add again to save the second slot.

In the Fulfilment section, set the Active option to true.

Click the Save intent button and Back to intents list link on the left.

Click Add intent for one last time and set the intent name to SellStocks. Update the utterances with the ones below as you did before:

sell {numberOfShares} shares of {stockName}
sell shares, number: {numberOfShares} , stock: {stockName}
sell {numberOfShares} of {stockName}

SellStocks intent is very similar to the BuyStocks intent. Create the same slot types as the BuyStocks intent as described above.

In the Fulfilment section, set the Active option to true.

Click the Save Intent button.

Now that all the intents have been described, click the Build button to rebuild the model.

After a show while, you should get a Successfully built notification:

Dismiss the notification and click the Bot: StockBrokerBot link in the breadcrumb.

In the left menu, under your bot there is a Bot versions link, and under it the Draft version which you’ve been working on.

Click Bot versions, and then click Create version.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 22

In the Description field, enter a description such as “Initial version with four intents” and click Create button at the bottom of the page.

You don’t assign version numbers, they are auto-incrementing integers. After you’ve created the version, it should appear in the version list:

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 23

A version is essentially a read-only snapshot of your bot. You cannot modify a version after you’ve published it.

Now, take a look at another important concept: Aliases.

Click Aliases link on the left menu. It should show the default TestBotAlias:

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 24

!!!info

An alias is associated with a specific version of your bot. The benefit of this is you can have multiple aliases such as test and live. If you publish a new version, you can point the test alias to the new version. This way your live alias is not affected until you test your changes. After you’re satisfied your new version is ready to go live, you can simply associate the live alias with the new version and all the new requests will come to the new version of your bot. Also, if you experience issues with your latest version, you can simply assign the previous version to your alias to roll back. This kind of separation between the versions and aliases makes change management a lot easier.

!!!

Click the Create alias button.

Enter Live as Alias name.

In the Associate with a version section, choose Version 1. The language comes already enabled so leave it like that.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 25

Click the Create button.

You should see the alias is successfully created and shown in the list:

Now Version 1 of your bot has been published.

You will assign a Lambda function to your bot, but first, move on to the next section to create the backend of your bot.

Create the Backend

Open a terminal and navigate to the directory that will be the root of your project.

You will need the Amazon Lambda Tools .NET tool to deploy the function via the command line. You can install it by running the command below:

dotnet tool install -g Amazon.Lambda.Tools

As shown in the demo project, you will need two data sources: one to store users’ portfolios and the other to store stock prices. (The following scripts can be found in the Setup/InfrastructureSetup.sh file in the ChatbotLambda project.)

To create the user portfolio table, run the following command:

aws dynamodb create-table \
    --table-name user-portfolio \
    --attribute-definitions \
        AttributeName=UserId,AttributeType=S \
    --key-schema \
        AttributeName=UserId,KeyType=HASH \
    --provisioned-throughput \
        ReadCapacityUnits=5,WriteCapacityUnits=5 \
    --table-class STANDARD

The script above creates a DynamoDB table with the UserId partition key, which you will use to query and fetch the users’ records.

To keep things simple, the account creation process is omitted. To create the account, add your user’s portfolio directly to the database by running the following command (replace { YOUR PHONE NUMBER WITH COUNTRY CODE } with your actual phone number before you run):

!!!warning

This phone number will be used to identify the user, so it must match the number sent by Twilio. It will be sent in the SessionId field, and it will not start with a “+”. So, for example, if your country code is 1, enter the number as 17407593063, without the leading plus sign.

!!!

aws dynamodb put-item \
    --table-name user-portfolio \
    --item \
      '{"UserId": {"S": "{ YOUR PHONE NUMBER WITH COUNTRY CODE }"}, "AvailableCash": {"N": "1000"}, "StockPortfolio": {"L": []}}'

This scripts creates you an account with no stocks and $1000 available cash.

Since the customers will come to your chatbot via SMS, UserId is used as the unique customer id. In a more complex scenario, you would have a different unique id to identify users. Twilio sends the phone number with the county code so you create your record in the same format for convenience.

Similarly, to create the stock prices table, run the following command:

aws dynamodb create-table \
     --table-name stock-prices \
     --attribute-definitions \
         AttributeName=Name,AttributeType=S \
     --key-schema \
         AttributeName=Name,KeyType=HASH \
     --provisioned-throughput \
         ReadCapacityUnits=5,WriteCapacityUnits=5 \
     --table-class STANDARD

Then, run the following to add some stock prices:

aws dynamodb put-item --table-name stock-prices --item '{"Name": {"S": "Apple"}, "Price": {"N": "144.00"} }'
aws dynamodb put-item --table-name stock-prices --item '{"Name": {"S": "Alphabet"}, "Price": {"N": "96.00"} }'
aws dynamodb put-item --table-name stock-prices --item '{"Name": {"S": "Microsoft"}, "Price": {"N": "144.00"} }'
aws dynamodb put-item --table-name stock-prices --item '{"Name": {"S": "Tesla"}, "Price": {"N": "182.00"} }'
aws dynamodb put-item --table-name stock-prices --item '{"Name": {"S": "Twilio"}, "Price": {"N": "46.00"} }'

Now that the database is ready, prepare the IAM roles and policies that your Lambda function will need. The easiest way to set those up is to run the following commands when you’re in the root of the cloned project:

cd src/StockBrokerBot/StockBrokerBot.ChatbotLambda/Setup/
aws iam create-role --role-name stockbrokerbot-lambda-role --assume-role-policy-document file://LambdaBasicRole.json
aws iam attach-role-policy --role-name stockbrokerbot-lambda-role --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
aws iam put-role-policy --role-name stockbrokerbot-lambda-role --policy-name dynamodb-table-access --policy-document file://LambdaDynamoDBAccessPolicy.json

LambdaBasicRole.json contains the role for the Lambda function by assuming Lambda service role. Then you attach AWS-managed AWSLambdaBasicExecutionRole policy that grants access to CloudWatch logs. Then, you attach the custom policy specified in LambdaDynamoDBAccessPolicy.json file that grants permissions to access the two DynamoDB tables you created earlier.

Enough with the infrastructure stuff; now it’s time to write some code!

Your Lambda function will receive events from the Amazon Lex service and will use the Amazon DynamoDB service to read/write data. In your terminal, navigate to the root of the Lambda project (src/StockBrokerBot/StockBrokerBot.ChatbotLambda) and run the following commands to add the necessary NuGet packages to your project:

dotnet add package Amazon.Lambda.LexV2Events
dotnet add package AWSSDK.DynamoDBv2

In the Lambda project, create a new directory called IntentProcessors, and under it, a file called AbstractIntentProcessor.cs and set its contents as shown below:

using Amazon.Lambda.Core;
using Amazon.Lambda.LexV2Events;
namespace StockBrokerBot.ChatbotLambda.IntentProcessors;
public abstract class AbstractIntentProcessor
{
    internal const string MessageContentType = "PlainText";
    internal const string IntentStateFulfilled = "Fulfilled";
    internal const string IntentStateFailed = "Failed";
    internal const string DialogActionClose = "Close";
    public abstract Task<LexV2Response> Process(LexV2Event lexEvent, ILambdaContext context);
    protected LexV2Response Close(string intentName, Dictionary<string, string> sessionAttributes, string fulfillmentState, string responseMessage)
    {
        return new LexV2Response
        {
            SessionState = new LexV2SessionState
            {
                Intent = new LexV2Intent { Name = intentName, State = fulfillmentState },
                SessionAttributes = sessionAttributes,
                DialogAction = new LexV2DialogAction  { Type = DialogActionClose }
            },
            Messages = new List<LexV2Message>
            {
                new()
                {
                    ContentType = MessageContentType,
                    Content = responseMessage
                }
            }
        };
    }
}

The abstract class leaves the Process method abstract to be implemented by the inheriting intent processors. It also contains the constants and Close method, which is shared among all the intent processors, so they are placed in the base class to avoid repetition.

In the demo application, you used two JSON-based data providers to manage user portfolio and stock price data. This approach doesn’t work with Lambda functions, as the JSON files will be gone when the function returns. Every time a new copy will be created from scratch, which doesn’t work for databases.

To persist data, you will need DynamoDB providers. Similar to the demo console application, create a directory named Persistence and, under it, create a new file called PortfolioDynamoDBDataProvider.cs.

Update the code as shown below:

using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using StockBrokerBot.Core.Entities;
using StockBrokerBot.Core.Persistence;
namespace StockBrokerBot.ChatbotLambda.Persistence;
public class PortfolioDynamoDBDataProvider : IPortfolioDataProvider
{
    private AmazonDynamoDBClient _dynamoDbClient;
    private DynamoDBContext _dynamoDbContext;
    public PortfolioDynamoDBDataProvider()
    {
        _dynamoDbClient = new AmazonDynamoDBClient();
        _dynamoDbContext = new DynamoDBContext(_dynamoDbClient);
    }
    public async Task<UserPortfolio> GetUserPortfolio(string userId)
    {
        return await _dynamoDbContext.LoadAsync<UserPortfolio>(userId);
    }
    public async Task SaveUserPortfolio(UserPortfolio userPortfolio)
    {
        await _dynamoDbContext.SaveAsync(userPortfolio);
    }
}

Create another file called StockMarketDynamoDBDataProvider.cs and update the code:

using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using StockBrokerBot.Core.Entities;
using StockBrokerBot.Core.Persistence;
namespace StockBrokerBot.ChatbotLambda.Persistence;
public class StockMarketDynamoDBDataProvider : IStockMarketDataProvider
{
    private AmazonDynamoDBClient _dynamoDbClient;
    private DynamoDBContext _dynamoDbContext;
    public StockMarketDynamoDBDataProvider()
    {
        _dynamoDbClient = new AmazonDynamoDBClient();
        _dynamoDbContext = new DynamoDBContext(_dynamoDbClient);
    }
    public async Task<decimal> GetStockPrice(string name)
    {
        var stock = await _dynamoDbContext.LoadAsync<Stock>(name);
        return stock.Price;
    }
}

Now you can implement your first concrete intent processor. Create a new file under the IntentProcessors directory called CheckStockPriceIntentProcessor.cs with the following code:

using Amazon.Lambda.Core;
using Amazon.Lambda.LexV2Events;
using StockBrokerBot.ChatbotLambda.Persistence;
using StockBrokerBot.Core.Services;
namespace StockBrokerBot.ChatbotLambda.IntentProcessors;
public class CheckStockPriceIntentProcessor : AbstractIntentProcessor
{
    public override async Task<LexV2Response> Process(LexV2Event lexEvent, ILambdaContext context)
    {
        var slots = lexEvent.SessionState.Intent.Slots;
        var requestedStockName = slots["stockName"].Value.InterpretedValue;
        var stockMarketService = new FluctuatingStockMarketService(new StockMarketDynamoDBDataProvider());
        var price = await stockMarketService.GetStockPrice(requestedStockName);
        var responseMessage = $"Current price of {requestedStockName} is ${price:N2}";
        return Close(
            lexEvent.SessionState.Intent.Name,
            lexEvent.SessionState.SessionAttributes,
            IntentStateFulfilled,
            responseMessage
        );
    }
}

Lex sends the stockName in the slots dictionary. After getting that value, you pass it on to the StockMarketService, format the output, and send it back to Lex to deliver to the user.

Next, implement the get user portfolio intent. Create a file named GetPortfolioIntentProcessor.cs under the IntentProcessors directory and update the code to:

using Amazon.Lambda.Core;
using Amazon.Lambda.LexV2Events;
using StockBrokerBot.ChatbotLambda.Persistence;
using StockBrokerBot.Core.Services;
namespace StockBrokerBot.ChatbotLambda.IntentProcessors;
public class GetPortfolioIntentProcessor : AbstractIntentProcessor
{
    public override async Task<LexV2Response> Process(LexV2Event lexEvent, ILambdaContext context)
    {
        var userId = lexEvent.SessionId;
        var userPortfolioService = new PortfolioService(
                new FluctuatingStockMarketService(new StockMarketDynamoDBDataProvider()), 
                new PortfolioDynamoDBDataProvider()
        );
        var userPortfolio = await userPortfolioService.GetUserPortfolio(userId);
        return Close(
            lexEvent.SessionState.Intent.Name,
            lexEvent.SessionState.SessionAttributes,
            IntentStateFulfilled,
            userPortfolio.ToString()
        );
    }
}

Twilio sends the user’s phone number to Lex and it sends it to your Lambda function in the SessionId field. You use it to fetch the user portfolio and send it back to the user.

!!!info

Constructing complex objects manually is not ideal. Setting up Dependency Injection is left out as it’s not the focus of this project. You can take a look at this article and implement DI as an improvement.

!!!

Next, create a new intent processor under the IntentProcessors directory called BuyStocksIntentProcessor.cs with the following code:

using Amazon.Lambda.Core;
using Amazon.Lambda.LexV2Events;
using StockBrokerBot.ChatbotLambda.Persistence;
using StockBrokerBot.Core.Services;
namespace StockBrokerBot.ChatbotLambda.IntentProcessors;
public class BuyStocksIntentProcessor : AbstractIntentProcessor
{
    public override async Task<LexV2Response> Process(LexV2Event lexEvent, ILambdaContext context)
    {
        var slots = lexEvent.SessionState.Intent.Slots;
        var requestedStockName = slots["stockName"].Value.InterpretedValue;
        var numberOfShares =  decimal.Parse(slots["numberOfShares"].Value.InterpretedValue);
        var userId = lexEvent.SessionId;
        var userPortfolioService = new PortfolioService(new FluctuatingStockMarketService(new StockMarketDynamoDBDataProvider()), new PortfolioDynamoDBDataProvider());
        try
        {
            var updatedPortfolio = await userPortfolioService.BuyStocks(userId, requestedStockName, numberOfShares);
            var responseMessage = $"Your request has been fulfilled. {updatedPortfolio}";
            return Close(
                lexEvent.SessionState.Intent.Name,
                lexEvent.SessionState.SessionAttributes,
                IntentStateFulfilled,
                responseMessage
            );
        }
        catch (Exception e)
        {
            var responseMessage = $"Error while buying stock: {requestedStockName}. {e.Message}. Call us at +0800 555-555 if the problem persists.";
            return Close(
                lexEvent.SessionState.Intent.Name,
                lexEvent.SessionState.SessionAttributes,
                IntentStateFailed,
                responseMessage
            );
        }
    }
}

And implement the final intent for selling stocks by creating a new file called SellStocksIntentProcessor.cs under the IntentProcessors directory.

Update the code as shown below:

using Amazon.Lambda.Core;
using Amazon.Lambda.LexV2Events;
using StockBrokerBot.ChatbotLambda.Persistence;
using StockBrokerBot.Core.Services;
namespace StockBrokerBot.ChatbotLambda.IntentProcessors;
public class SellStocksIntentProcessor : AbstractIntentProcessor
{
    public override async Task<LexV2Response> Process(LexV2Event lexEvent, ILambdaContext context)
    {
        var slots = lexEvent.SessionState.Intent.Slots;
        var requestedStockName = slots["stockName"].Value.InterpretedValue;
        var numberOfShares =  decimal.Parse(slots["numberOfShares"].Value.InterpretedValue);
        var userId = lexEvent.SessionId;
        var userPortfolioService = new PortfolioService(new FluctuatingStockMarketService(new StockMarketDynamoDBDataProvider()), new PortfolioDynamoDBDataProvider());
        try
        {
            var updatedPortfolio = await userPortfolioService.SellStocks(userId, requestedStockName, numberOfShares);
            var responseMessage = $"Your request has been fulfilled. {updatedPortfolio}";
            return Close(
                lexEvent.SessionState.Intent.Name,
                lexEvent.SessionState.SessionAttributes,
                IntentStateFulfilled,
                responseMessage
            );
        }
        catch (Exception e)
        {
            var responseMessage = $"Error while selling stock: {requestedStockName}. {e.Message}. Call us at +0800 555-555 if the problem persists.";
            return Close(
                lexEvent.SessionState.Intent.Name,
                lexEvent.SessionState.SessionAttributes,
                IntentStateFailed,
                responseMessage
            );
        }
    }
}

Most of the business logic is defined in the core library so what these intents do is to collect data from the user (via Lex and Twilio) and call the corresponding method of the services.

Finally, update your Function.cs as shown below to tie them all together:

using Amazon.Lambda.Core;
using Amazon.Lambda.LexV2Events;
using StockBrokerBot.ChatbotLambda.IntentProcessors;
// Assembly attribute to enable the Lambda function's JSON input to be converted into a .NET class.
[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]
namespace StockBrokerBot.ChatbotLambda;
public class Function
{
    public async Task<LexV2Response> FunctionHandler(LexV2Event lexEvent, ILambdaContext context)
    {
        AbstractIntentProcessor process = lexEvent.SessionState.Intent.Name switch
        {
            "CheckStockPrice" => new CheckStockPriceIntentProcessor(),
            "GetPortfolio" => new GetPortfolioIntentProcessor(),
            "BuyStocks" => new BuyStocksIntentProcessor(),
            "SellStocks" => new SellStocksIntentProcessor(),
            _ => throw new Exception($"Intent with name {lexEvent.SessionState.Intent.Name} is not supported")
        };
        return await process.Process(lexEvent, context);
    }
}

Now you invoke the correct processor based on the intent name specified in the LexV2Event object.

Now deploy your function to AWS by running the following command in the terminal:

dotnet lambda deploy-function

You have created your bot and backend separately. Now it’s the time to bring them together by pointing your bot to your Lambda function, which you will do in the next section.

Connect your Chatbot to Lambda

Go to the Lex Console. Click Bots, then click StockBrokerBot. Click Aliases link, andon the Aliases page, click the Live alias.

In the languages section, click the English (US) link.

Now you should see a page that allows you to select a Lambda function and version of the function. In the Source list, select StockBrokerBot Lambda function and in the Lambda function version or alias list $LATEST should be automatically selected.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 26

Click the Save button.

Now when a request comes to Live alias, Lex will identify the intent and invoke your Lambda function. It will pass all the slot values and user info in a LexV2Event structure that your Lambda expects.

Almost everything is wired up. What’s left is to allow users to interact with your bot via SMS. Proceed to the next section to integrate with Twilio SMS.

Connect your Chatbot to Twilio

On the left menu, right under Aliases, there is a link to Channel integrations. Click that to list the existing integrations.

Click the Add channel button.

Amazon Lex supports 3 integration platforms: Facebook, Slack and Twilio SMS.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 27

Select Twilio SMS.

In the Integration configuration section, enter TwilioIntegration as the name, select Live in the Alias list and English (US) in the language list.

In the Additional configuration section, you will need your Twilio Account SID and Authentication token.

Open the Twilio Console. On the main page, you should see the Account Info section.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 28

Copy your Account SID and Auth Token values and paste them in the corresponding inputs in the AWS console.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 29

Click the Create button.

The Twilio SMS integration should now appear in the list.

Click the channel name to view the details.

Scroll down to the Callback URL section.

You should see an auto-generated webhook URL that Lex expects Twilio to post data to.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 30

To complete the integration, copy the link and go to the Twilio console. Select your account, and then click Phone Numbers → Manage → Active Numbers on the left pane. (If Phone Numbers isn’t on the left pane, click Explore Products and then on Phone Numbers.)

Click the phone number you want to use for your project and scroll down to the Messaging section.

In the “A MESSAGE COMES IN” section, select Webhook and paste the callback URL into the input field. Select HTTP POST in the next dropdown.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 31

Click the Save button at the bottom of the screen.

Test your chatbot via SMS

Finally, it’s time to test your chatbot.

From your phone, send an SMS to your Twilio Phone Number with the following message: check price. You should get a response asking for the stock name. Send the name of one of the stocks in your database such as Tesla. It also understands the stock name directly as it’s in your utterance list. So you can simplify it by sending the stock name directly and you should still get an answer.

Create an SMS chatbot using C#, Amazon Lex, and Twilio SMS - image 32

Now send the following message “buy shares” and your bot should reply by asking the stock name first and then the number of shares. You should see your updated portfolio after the stocks have been bought for you.

You can play around with different utterances and intents.

Conclusion

In this tutorial, you learned how to implement your chatbot from scratch using C#. You also used the Twilio SMS integration with your Amazon Lex chatbot to allow users to interact with your bot via SMS.

A chatbot can be very useful to automate some processes saving time and money for your business. It’s also beneficial for the users as they can use your system outside of business hours.

If you’d like to keep learning, I recommend taking a look at these articles:

]]> <![CDATA[Create an SMS chatbot using Amazon Lex and Twilio SMS]]> 2026-08-05T12:20:00+00:00 https://volkanpaksoy.com/archive/2026/08/05/Create-an-SMS-chatbot-using-Amazon-Lex-and-Twilio-SMS

This article was originally published on the Twilio Blog.

Customer service is an integral part of any business. Today, people expect speed and convenience from customer services when they need to get answers. Twilio already has built-in solutions to improve customer service. In addition to that, you can implement your chatbot with Amazon Lex and integrate it with Twilio SMS so that your customers can interact with your bot easily using SMS. In this article, you will learn how to achieve this.

Prerequisites

You’ll need the following things in this tutorial:

What is Amazon Lex?

Amazon Lex is an artificial intelligence service that allows developers to create voice or text-based conversational interfaces. This service powers Amazon’s own Alexa.

Lex provides automatic speech recognition and natural language understanding technologies. It takes the user’s input, runs it through a Natural Language Processing (NLP) engine and determines the user’s intent. The value of this is the user does not need to remember a set of commands to interact with your bot. They can talk to the bot just like they would to a human being.

Create your Chatbot

Go to Lex dashboard and click the Create bot button.

In this article, you will use one of the demo bots that LexV2 comes with, as it is sufficient to illustrate how to connect a Lex chatbot to Twilio SMS.

In the Configure bot settings page, click Start with an example.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 1

In the Example bots section, select BookTrip.

In the Bot configuration section, enter BookTripBot as the name. You can enter a description if you like.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 2

In IAM permissions, select Create a role with basic Amazon Lex permissions. AWS will generate the role name for you, so you don’t have to set the name.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 3

In the Children’s Online Privacy Protection Act (COPPA) section, select No. This only applies if you collect information from children under 13 therefore, it doesn’t apply to your demo project.

Leave the remaining settings with their default values and click the Next button.

In the next section, you can choose to add multiple languages. The supported language and locale list can be found here. You can even assign a different voice to each language. In this project, you will use SMS-based interaction, so select “None. This is only a text-based application” in the Voice interaction dropdown list.

Leave the default for the score threshold and click Done.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 4

After the bot creation, Lex takes you to the intent list. An intent is an action your bot takes to fulfil a user’s request. It’s different from traditional command-based interactions, where you need to know the exact command and the order of arguments. In this model, you interact with the bot just like you would talk to a human being. Your input is put through an NLP engine to determine your intent.

Scroll down to the Sample utterances section. You can see the same intent is expressed in multiple ways as humans do in a normal conversation.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 5

{Nights} and {Location} shown in the third utterance are called slots. Scroll down to the Slots section to see how they are defined.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 6

A slot is another important concept. As you can see in the utterances, some of the slots are used as placeholders and can be extracted from the utterance to fill those values. A slot can be defined as required, which is the case here. Expand the Location panel to see the details:

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 7

This slot is marked as required, meaning that if the user does not supply this value, Lex will keep asking it until it fills the slot. The question it will ask is determined by the phrase you put in the Prompts field (“What city will you be staying in?” In this example).

Another thing to note is the data type. This slot has the AMAZON.City built-in slot type. It’s not a free-form string field. Amazon provides these built-in slot types. These are pre-defined models that are trained by Amazon.

You can also create your custom slot types as you can see in the RoomType slot, which has a custom RoomTypeValues slot type.

Click the Save Intent button

Scroll to the top and click Language: English (US) link in the breadcrumb. On the left pane, you should see two links under the language: Intents and Slot types.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 8

You looked into intents; now click the Slot types link to see how the custom types are defined. For this example bot, Amazon defined two custom slots:

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 9

Click RoomTypeValues.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 10

The default value resolution method is Expand values which is the one used in this example. This way, you are not providing a closed set of values but rather a sample dataset to train your machine learning model.

Lex performs better when you train your models with comprehensive values for your slots and utterances.

Click the Build button at the top of the screen.

After a show while, you should get a Successfully built notification.

Dismiss the notification and click the Bot: BookTripBot link in the breadcrumb. Take a look at the left pane again and note two important concepts: Versions and Aliases.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 11

Currently, you are on the Draft version. The draft version is the work-in-progress version of your bot. When you want your updates to take effect, you have to publish a new numbered version. These are simple integer auto-incremented numbers. They are read-only snapshots of the current state of your bot.

To publish your first version, click the Bot versions link on the left pane, then click the Create version button.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 12

It’s useful to give a meaningful description as the number of versions grows you tend to forget which feature was released with which version.

Put a description such as “The initial version of the example project with three intents and two slot types” and click the Create button at the bottom of the page.

After a few seconds, you should see your new version in the list.

Click Version 1 then Intents. You should a reminder from Amazon saying that this is a read-only version.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 13

As mentioned above, this is an immutable snapshot of your bot. If you make further changes, you will need to publish a new version. You cannot update existing versions.

Now click Aliases on the left menu. It should show the default TestBotAlias:

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 14

An alias is associated with a specific version of your bot. The benefit of this is you can have multiple aliases, such as test and live. If you publish a new version, you can point the test alias to the new version. This way, your live alias is not affected until you test your changes. After you’re satisfied your new version is ready to go live, you can simply associate the live version with the new version and all the new requests will come to the new version of your bot. Also, if you experience issues with your latest version, you can simply assign the previous version to your alias to roll back. This kind of separation between the versions and aliases makes change management a lot easier.

Click the Create alias button.

Enter Live as Alias name. In the Associate with a version section, choose Version 1. The language comes already enabled, so leave it like that.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 15

Click the Create button.

You should see the alias is successfully created and shown in the list.

Now that your bot has been published, move on to the next section to integrate it with Twilio.

Connect your Chatbot to Twilio

Your bot is live, but the users don’t have a way to interact with it.

To fix this, click the Channel integrations link on the left menu.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 16

Click the Add channel button.

Amazon Lex supports 3 integration platforms: Facebook, Slack, and Twilio SMS.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 17

Select Twilio SMS.

In the Integration configuration section, enter TwilioIntegration as the name, select Live in the Alias list and English (US) in the language list.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 18

In the Additional configuration section, you will need your Twilio Account SID and Authentication token.

Open the Twilio Console. On the main page, you should see the Account Info section.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 19

Copy your Account SID and Auth Token values and paste them in the corresponding inputs in the AWS console.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 20

Click the Create button.

Twilio SMS integration should appear in the list. Click the channel name to view the details.

Scroll down to the Callback URL section.

You should see an auto-generated webhook URL that Lex expects Twilio to post data to.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 21

To complete the integration, copy the link and go to the Twilio console. Select your account, and then click Phone Numbers → Manage → Active Numbers on the left pane. (If Phone Numbers isn’t on the left pane, click Explore Products and then on Phone Numbers.)

Click the phone number you want to use for your project and scroll down to the Messaging section.

In the “A MESSAGE COMES IN” section, select Webhook and paste the callback URL into the input field. Select HTTP POST in the next dropdown.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 22

Click the Save button at the bottom of the screen.

Test your chatbot via SMS

Finally, it’s time to test your chatbot.

From your phone, send an SMS to your Twilio phone number with the following message: Book a trip.

You should get a response from the bot asking the city.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 23

Remember this is the prompt message saw earlier and it’s shown now because the City slot is required. Send a city name to your liking and follow the bot’s prompts to complete the booking process.

Below is a screenshot of an example conversation:

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 24

To the city question. I responded: “I will stay in London”. My answer was not a single word, but Lex was able to get the city name from the context.

Another thing is I didn’t specify the exact date. I said “Next Monday” yet it was smart enough to understand the date I meant.

Lex asks these questions without coming to your backend so that when it does post this data to your backend Lambda function, you can rest assured that the heavy lifting was already done and all the variables are already filled in. By default, invoking a Lambda function is not enabled. You can configure this behavior by enabling the fulfillment and ticking the Use a Lambda function for fulfilment checkbox in the Advanced options. You can read more about fulfillment and using Lambda functions on AWS documentation.

Create an SMS chatbot using Amazon Lex and Twilio SMS - image 25

Conclusion

In this tutorial, you learned how to create a chatbot using Amazon’s Lex service. You also created a Twilio SMS integration so that users can interact with your bot via SMS.

Amazon Lex leverages machine learning and captures the user’s intent and the values your program needs. SMS is probably the most ubiquitous client application in the world. Users can interact with your chatbot without having to install anything on their phones. Having these two technologies combined gives you great power to develop smart chatbots.

If you’d like to keep learning, I recommend taking a look at these articles:

]]> <![CDATA[Build a Voicemail Inbox using Twilio Voice and Blazor (Part 2)]]> 2026-08-05T12:15:00+00:00 https://volkanpaksoy.com/archive/2026/08/05/Build-a-Voicemail-Inbox-using-Twilio-Voice-and-Blazor-Part-2

This article was originally published on the Twilio Blog.

In Part 1 of this series, you implemented a voicemail service that you can manage by calling your own Twilio number. You could then listen to the voice messages and choose to save or delete them. In this article, you will improve your voicemail service by adding a GUI so that you can carry out the same operations via the web and also see more information about the call, such as the caller number, duration and even the transcript of the message. If this sounds interesting to you, let’s get started!

Prerequisites

You’ll need the following things in this tutorial:

Project Overview

The project will start where Part 1 ended. The older version relies on filenames to keep the state of the recordings (new vs saved). In this version, you will introduce a SQLite database to store the metadata such as caller number, call duration, etc.

Project setup

The easiest way to set up the starter project is by cloning the sample GitHub repository.

Open a terminal, change to the directory you want to download the project (on the starter-project branch) and run the following command:

git clone https://github.com/Dev-Power/voicemail-service-with-gui-using-twilio-and-blazor --branch starter-project

Before making any changes, ensure the current version is in working order.

Run the following command to start tunneling:

ngrok http http://localhost:5096

Update the Twilio incoming call webhook URL with the Forwarding URL assigned to you by ngrok, and add the /IncomingCall path. Leave the ngrok tunnel running and open a separate shell for the upcoming commands.

In a new shell, change directories to the web API project.

cd voicemail-service-with-gui-using-twilio-and-blazor/src/VoicemailDirectory.WebApi

To test leaving a voicemail, remove your phone number from the Voicemail:Owners array in

appsettings.json and run the application with the following command:

dotnet run

Call your Twilio phone number, and you should be able to record a message. The saved message should appear under the wwwroot/Voicemails directory.

Update the appsettings.json by adding your number to the owner’s list (using E. 164 formatting) and call your Twilio phone number again.

This time you should be greeted with a message telling you have one new message and no saved messages, followed by the recorded message.

If your project works so far, you’re ready to move on to the next section to refactor and improve. If not, please refer to the original article and make sure your setup works.

Use EF Core and a SQLite database to store metadata

In the first version, you used the filename to store very limited metadata about the recording: Call status, which can be “New” or “Saved”. This was used to order the recordings to play the new ones first.

In this version, you will use a local SQLite database instead. First, start by adding the EF Core SQLite NuGet package to your API project:

dotnet add package Microsoft.EntityFrameworkCore.Sqlite

Create a new directory called Data and add a new C# file under it called RecordingContext.cs. Update the contents as below:

using Microsoft.EntityFrameworkCore;
namespace VoicemailDirectory.WebApi.Data;
public class RecordingContext : DbContext
{
    public DbSet<Recording>? Recordings { get; set; }
    public RecordingContext(DbContextOptions<RecordingContext> options) : base(options)
    {
    }
}

The context class you created above refers to an entity class called Recording which you will use to save the recording metadata. Next, create a new file under the Data directory called Recording.cs and update it as shown below:

namespace VoicemailDirectory.WebApi.Data;
public class Recording
{
    public int Id { get; set; }
    public string RecordingSID { get; set; }
    public DateTime Date { get; set; }
    public TimeSpan Duration { get; set; }
    public string CallerNumber { get; set; }
    public string Transcription { get; set; }
    public RecordingStatus Status { get; set; }
}
public enum RecordingStatus
{
    New,
    Saved
}

SQLite is a file-based SQL database engine. EF Core is going to create the database for you, as you will see later, but first, you have to specify the path for the database file.

Open Program.cs file and add the highlighted lines as shown below:

```csharp hl_lines=”3 4 5 6” builder.Services.AddControllers(); var folder = Environment.SpecialFolder.LocalApplicationData; var path = Environment.GetFolderPath(folder); var dbPath = Path.Join(path, “recordings.db”); builder.Services.AddDbContext(options => options.UseSqlite($"Data Source={dbPath}")); // Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle builder.Services.AddEndpointsApiExplorer();


Also, add the using statements at the top:

```csharp
using Microsoft.EntityFrameworkCore;
using VoicemailDirectory.WebApi.Data;

You can use any path or file name you like. The above example uses the local data path and uses “recordings.db” as the filename.

You can now inject the RecordingContext class wherever you want to carry out database operations. Alternatively, you can create a separate class to encapsulate all the database operations. This way your business logic doesn’t become tied to the implementation. To achieve this, create an interface under the Data directory called IRecordingRepository.cs with the following code:

namespace VoicemailDirectory.WebApi.Data;
public interface IRecordingRepository
{
    Task NewRecording(Recording recording);
    Task UpdateCallerAndTranscription(string recordingSID, string caller, string transcriptionText);
    Task ChangeStatusToSaved(string recordingSID);
    Task Delete(string recordingSID);
    List<Recording> GetAll();
}

This interface defines all the database operations you will need:

  • NewRecording: Creates and inserts a new Recording object when a new message comes in.

  • UpdateCallerAndTranscription: It takes a while to get the transcription, and it’s handled in a different endpoint. When Twilio calls your endpoint with the transcript info, this method is called to update the record. It also updates the caller number as it’s not present in the recording status callback.

  • ChangeStatusToSaved: Updates the status column to Saved for the specified recording.

  • Delete: Removes the recording metadata from the database.

  • GetAll: Returns all recordings in the database.

To implement this interface, create a new class called RecordingRepository under the Data directory:

using VoicemailDirectory.WebApi.Data;
public class RecordingRepository : IRecordingRepository
{
    private readonly RecordingContext _recordingContext;
    public RecordingRepository(RecordingContext recordingContext)
    {
        _recordingContext = recordingContext;
    }
    public async Task NewRecording(Recording recording)
    {
        await _recordingContext.Recordings.AddAsync(recording);
        await _recordingContext.SaveChangesAsync();
    }
    public async Task UpdateCallerAndTranscription(string recordingSID, string caller, string transcriptionText)
    {
        var recording = _recordingContext.Recordings.Single(rec => rec.RecordingSID == recordingSID);
        recording.CallerNumber = caller;
        recording.Transcription = transcriptionText;
        await _recordingContext.SaveChangesAsync();
    }
    public async Task ChangeStatusToSaved(string recordingSID)
    {
        var recording = _recordingContext.Recordings.Single(rec => rec.RecordingSID == recordingSID);
        recording.Status = RecordingStatus.Saved;
        await _recordingContext.SaveChangesAsync();
    }
    public async Task Delete(string recordingSID)
    {
        var recording = _recordingContext.Recordings.Single(rec => rec.RecordingSID == recordingSID);
        _recordingContext.Recordings.Remove(recording);
        await _recordingContext.SaveChangesAsync();
    }
    public List<Recording> GetAll()
    {
        return _recordingContext.Recordings.ToList();
    }
}

The repository class encapsulates RecordingContext and carries out the DB operations via EF Core.

You also have to register it to the IoC container by updating Program.cs as shown below:

```csharp hl_lines=”2” builder.Services.AddTransient(); builder.Services.AddTransient<IRecordingRepository, RecordingRepository>(); builder.Services.Configure(builder.Configuration.GetSection("Voicemail"));


Finally, it's time to create the database. Run the following commands to scaffold the migrations and create the database:

```bash
dotnet tool install --global dotnet-ef
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet ef migrations add InitialCreate
dotnet ef database update

You should now see a directory inside your project called Migrations and the recordings.db file in your local data path.

Build a Voicemail Inbox using Twilio Voice and Blazor (Part 2) - image 1

Refactor Controllers and Services

Now that you have a database layer, it’s time to refactor the controllers to make use of it.

Open RecordController.cs under the Controllers directory and set up IRecordingRepository as shown below:

```csharp hl_lines=”3 8 13” private readonly ILogger _logger; private readonly FileService _fileService; private readonly IRecordingRepository _recordingRepository; public RecordController( ILogger logger, FileService fileService, IRecordingRepository recordingRepository ) { _logger = logger; _fileService = fileService; _recordingRepository = recordingRepository; }


Also add this required using statement:

```csharp
using VoicemailDirectory.WebApi.Data;

Replace the RecordingStatus action with the code below:

   [HttpPost]
    public async Task RecordingStatus(
        [FromForm] string callSid,
        [FromForm] string recordingUrl,
        [FromForm] string recordingSid,
        [FromForm] string recordingStatus,
        [FromForm] string recordingStartTime,
        [FromForm] string recordingDuration
    )
    {
        _logger.LogInformation(
            "Recording status changed to {recordingStatus} for call {callSid}. Recording is available at {recordingUrl}",
            recordingStatus, callSid, recordingUrl
        );
        if (recordingStatus == "completed")
        {
            await _recordingRepository.NewRecording(new Recording
            {
                RecordingSID = recordingSid,
                Status = Data.RecordingStatus.New,
                Date = DateTime.Parse(recordingStartTime),
                Duration = TimeSpan.FromSeconds(double.Parse(recordingDuration)),
                CallerNumber = string.Empty,
                Transcription = string.Empty
            });
            await _fileService.DownloadRecording(recordingUrl, recordingSid);
        }
    }

The previous version only downloaded the file. Now, in addition to that, you also insert the metadata into the database.

Another change in the controller needs to be done in the Index method. You will instruct Twilio to transcribe the call and send you the transcription by updating the Record call as below:

```csharp hl_lines=”7 8” response.Record( timeout: 10, action: new Uri(Url.Action(“Bye”)!, UriKind.Relative), method: Twilio.Http.HttpMethod.Post, recordingStatusCallback: new Uri(Url.Action(“RecordingStatus”)!, UriKind.Relative), recordingStatusCallbackMethod: Twilio.Http.HttpMethod.Post, transcribe: true, transcribeCallback: new Uri(Url.Action(“TranscribeCallback”)!, UriKind.Relative) );


And add the method to handle the transcription callback:

```csharp
[HttpPost]
public async Task TranscribeCallback(
    [FromForm] string recordingSid,
    [FromForm] string transcriptionText,
    [FromForm] string from
)
{
    _logger.LogInformation(
        "Updating the recording {recordingSid} from {from} with transcription: {transcriptionText}",
        recordingSid, from, transcriptionText
    );
    await _recordingRepository.UpdateCallerAndTranscription(recordingSid, from, transcriptionText);
}

Update your settings and remove your phone from the owner list to test recording a new message again. Repeat the previous test. This time, you should also see a new record in the recordings.db database.

!!!info

If you don’t have an application to manage SQLite databases already installed, you can download DB Browser for SQLite for free.

!!!

After you’ve saved your message, you should see a new call to your API:

Build a Voicemail Inbox using Twilio Voice and Blazor (Part 2) - image 2

The record is first inserted in the /Record/RecordingStatus endpoint. Then updated with the caller number and the call transcription in the /Record/TranscribeCallback endpoint.

Your recording row should look something like this in your database:

Build a Voicemail Inbox using Twilio Voice and Blazor (Part 2) - image 3

Next step is refactoring the DirectoryController class to use the database. Like RecordController, you need to inject the repository to handle the database operations.

Open DirectoryController.cs and set up IRecordingRepository as shown below:

```csharp hl_lines=”3 8 13” private readonly ILogger _logger; private readonly FileService _fileService; private readonly IRecordingRepository _recordingRepository; public DirectoryController( ILogger logger, FileService fileService, IRecordingRepository recordingRepository ) { _logger = logger; _fileService = fileService; _recordingRepository = recordingRepository; }


Then, add the required using statement:

```csharp
using VoicemailDirectory.WebApi.Data;

Current version gets the recordings from the FileService. In this version, you will get that data from the database.

Update the first 3 lines of the Index method as shown below:

var allRecordings = _recordingRepository.GetAll();
var newMessages = allRecordings.Where(rec => rec.Status == RecordingStatus.New).ToList();
var savedMessages = allRecordings.Where(rec => rec.Status == RecordingStatus.Saved).ToList();

Another change in this method is at the bottom, where you filter the recordings. Again, you will now use the RecordingRepository instead of the FileService. Replace the var allMessages = _fileService.GetRecordingSids; call with the code below:

var allMessages = allRecordings
    .OrderBy(rec => rec.Status) // So the new ones come on top
    .ThenByDescending(rec => rec.Date) // Descending so that the newest ones come on top
    .Select(rec => rec.RecordingSID)
    .ToList();

Final modification in this controller will be in the Gather method. Update the actions as shown below:

case 2: // Save
    await _recordingRepository.ChangeStatusToSaved(currentMessage);
    queuedMessages.Remove(currentMessage);
    break;
case 3: // Delete
    _fileService.DeleteRecording(currentMessage);
    await _recordingRepository.Delete(currentMessage);
    queuedMessages.Remove(currentMessage);
    break;

This way, in addition to managing the actual MP3 files, you keep the database accurate.

For this update to work, you have to convert the Gather method to async by making the following change in the method signature:

```csharp hl_lines=”1” public async Task Gather( [FromQuery] List queuedMessages, [FromForm] int digits )


Due to all these changes, the functionality of the `FileService` has also changed. You don't have to prefix the file name with its status anymore. Therefore, you don't need a save method. Update the current service with the simplified version as shown below:

```csharp
namespace VoicemailDirectory.WebApi.Services;
public class FileService
{
    private readonly HttpClient _httpClient;
    private readonly string _rootVoicemailPath;
    public FileService(IHttpClientFactory httpClientFactory, IWebHostEnvironment webHostEnvironment)
    {
        _rootVoicemailPath = $"{webHostEnvironment.WebRootPath}/Voicemails";
        _httpClient = httpClientFactory.CreateClient();
    }
    public async Task DownloadRecording(string recordingUrl, string recordingSid)
    {
        using HttpResponseMessage response = await _httpClient.GetAsync($"{recordingUrl}.mp3");
        response.EnsureSuccessStatusCode();
        await using var fs = new FileStream(
            $"{_rootVoicemailPath}/{recordingSid}.mp3",
            FileMode.CreateNew
        );
        await response.Content.CopyToAsync(fs);
    }
    public void DeleteRecording(string recordingSid) => File.Delete(GetRecordingPathBySid(recordingSid));
    private string GetRecordingPathBySid(string recordingSid)
        => Directory.GetFiles($"{_rootVoicemailPath}/", "*.mp3")
            .Single(s => s.Contains(recordingSid));
}

Leave another message for yourself and test the existing functionality by adding your number to the owner list and calling back. Once you’ve confirmed everything is still working as expected, move on to the next section to implement a new controller for your future front-end.

Implement the new controller

Currently, you have a voice-based user interface where you’re prompted with options when you call your own number. The GUI you will implement will need to have a new API endpoint that it can talk to. To achieve this, create a new controller under the Controllers directory called RecordingManagementController and update its code as shown below:

using Microsoft.AspNetCore.Mvc;
using VoicemailDirectory.WebApi.Data;
using VoicemailDirectory.WebApi.Services;
namespace VoicemailDirectory.WebApi.Controllers;
[ApiController]
[Route("[controller]/[action]")]
public class RecordingManagementController : ControllerBase
{
    private readonly FileService _fileService;
    private readonly IRecordingRepository _recordingRepository;
    public RecordingManagementController(IRecordingRepository recordingRepository, FileService fileService)
    {
        _recordingRepository = recordingRepository;
        _fileService = fileService;
    }
    [HttpGet]
    public ActionResult Index()
    {
        var recordings = _recordingRepository.GetAll();
        return Ok(recordings.OrderByDescending(m => m.Date));
    }
    [HttpPatch("{recordingSid}")]
    public async Task<ActionResult> Save(string recordingSid)
    {
        await _recordingRepository.ChangeStatusToSaved(recordingSid);
        return NoContent();
    }
    [HttpDelete("{recordingSid}")]
    public async Task<ActionResult> Delete(string recordingSid)
    {
        await _recordingRepository.Delete(recordingSid);
        _fileService.DeleteRecording(recordingSid);
        return NoContent();
    }
}

As you can see, the goal here is to have the same functionality via the GUI.

Now that you have your API ready for the front-end, proceed to implement it.

Implement the front-end

In the terminal, navigate to the solution level and run the following command:

dotnet new blazorwasm -o VoicemailDirectory.Console
dotnet sln add ./VoicemailDirectory.Console/VoicemailDirectory.Console.csproj

This should create a new Blazor WebAssembly project and add it to your solution.

The Blazor application sets up and HTTP client to resolve HTTP requests to its own app URL, but you’ll need to make HTTP requests to the API project running on a separate URL. The web API runs on http://localhost:5096, so update your VoicemailDirectory.Console/Program.cs as shown below to reflect this:

```csharp hl_lines=”3” builder.RootComponents.Add("head::after"); builder.Services.AddScoped(sp => new HttpClient { BaseAddress = new Uri("http://localhost:5096") }); await builder.Build().RunAsync();


To get rid of the default navigation and sample pages, update the MainLayout.razor as shown below:

```csharp
@inherits LayoutComponentBase
<div class="page">
    <main>
        <article class="content px-4">
            @Body
        </article>
    </main>
</div>

Also remove the following files to keep things clean:

  • Shared/SurveyPrompt.razor

  • Shared/NavMenu.razor

  • Shared/NavMenu.razor.cs

  • Pages/Counter.razor

  • Pages/FetchData.razor

Replace the contents of Index.razor with the code below:

@page "/"
@inject HttpClient Http
<PageTitle>Voicemail Management Console</PageTitle>
<h1>Voicemail Management Console</h1>
@if (recordingMetadata == null)
{
    <p>No recording found.</p>
}
else
{
    <table class="table">
        <thead>
            <tr>
                <th>Date</th>
                <th>Caller</th>
                <th>Duration</th>
                <th>Transcription</th>
                <th>Status</th>
                <th>Recording</th>
                <th>Actions</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var recording in recordingMetadata)
            {
                <tr>
                    <td>@recording.Date.ToShortDateString() @recording.Date.ToShortTimeString()</td>
                    <td>@recording.CallerNumber</td>
                    <td>@recording.Duration</td>
                    <td>@recording.Transcription</td>
                    <td>@recording.Status</td>
                    <td>
                        <audio controls>
                            <source src=@($"{Http.BaseAddress}/Voicemails/{recording.RecordingSID}.mp3") type="audio/mpeg">
                        </audio>
                    </td>
                    <td>
                        <button type="button" class="btn btn-primary" @onclick="() => SaveRecording(recording.RecordingSID)">Save</button>
                        <button type="button" class="btn btn-danger" @onclick="() => DeleteRecording(recording.RecordingSID)">Delete</button>
                    </td>
                </tr>
            }
        </tbody>
    </table>
}
@code {
    private Recording[]? recordingMetadata;
    protected override async Task OnInitializedAsync() => await UpdateTable();
    private async Task SaveRecording(string recordingSid)
    {
        await Http.PatchAsync($"/RecordingManagement/Save/{recordingSid}", null);
        await UpdateTable();
    }
    private async Task DeleteRecording(string recordingSid)
    {
        await Http.DeleteAsync($"/RecordingManagement/Delete/{recordingSid}");
        await UpdateTable();
    }
    private async Task UpdateTable() => recordingMetadata = await Http.GetFromJsonAsync<Recording[]>("/RecordingManagement/Index");
}

This page calls the newly created API endpoints to get the list of Recording objects and save/delete operations.

Create a new class called Recording inside the Blazor project as well, and paste the same code as the API:

namespace VoicemailDirectory.Console;
public class Recording
{
    public int Id { get; set; }
    public string RecordingSID { get; set; }
    public DateTime Date { get; set; }
    public TimeSpan Duration { get; set; }
    public string CallerNumber { get; set; }
    public string Transcription { get; set; }
    public RecordingStatus Status { get; set; }
}
public enum RecordingStatus
{
    New,
    Saved
}

!!!info

Instead of duplicating the code this way, you can create a class library with the data classes and share between the API and the Blazor app. This tutorial creates a copy of the recording class to keep things simple.

!!!

For this setup to work, you also need to update the CORS policy of your API. Even though both applications run locally, they run on different ports and thus on different origins. For security reasons, browsers don’t allow one origin to send HTTP requests to other origins. You can provide Cross-Origin Resource Sharing (CORS) headers from your API project to tell the browser which origins are allowed to send HTTP requests to the API project. So in order for Blazor to call the API, you need to enable a permissive CORS policy in the API project.

!!!info

Sometimes in development environments, and especially in production, a reverse proxy is used to host the front-end and the back-end on a single origin, thus avoiding the need for CORS. Here’s a tutorial that shows you how to host a client and API on a single origin using YARP, Microsoft’s ASP.NET Core based reverse proxy.

!!!

Open the Program.cs file in the API project and the highlighted lines as shown below:

```csharp hl_lines=”3 4 5 6 7 8 9” builder.Services.AddDbContext(options => options.UseSqlite($"Data Source={dbPath}")); builder.Services.AddCors(policy => { policy.AddPolicy("CorsPolicy", opt => opt .AllowAnyOrigin() .AllowAnyHeader() .AllowAnyMethod()); }); // Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle builder.Services.AddEndpointsApiExplorer();


!!!warning

Do not allow any origin (`AllowAnyOrigin()`) in production. Instead, explicitly configure the individual origins you'd like to allow.

!!!

And the following line to enable the policy:

```csharp hl_lines="3"
app.MapControllers();
app.UseCors("CorsPolicy");
app.Run();

Then, restart your API for your changes to take effect.

So the final step is to run the front-end test the functionality using the Blazor WebAssembly front-end.

Test via the front-end

While your API is still running, open another terminal inside the console application and run it with the following command:

dotnet run

Open a browser and go to your application at http://localhost:{YOUR APPLICATION’S PORT}.

It should look like this:

Build a Voicemail Inbox using Twilio Voice and Blazor (Part 2) - image 4

If you have lots of messages, you can play them very quickly as the play button for all of them will be directly accessible to you, whereas if you tried to achieve the same via the voice UI, you would have to go through all the messages one-by-one. Also, you can see the transcriptions, so you may not even want to play the messages in the first place.

Conclusion

In this tutorial, you implemented using a SQLite database with EF Core, and also implemented your Blazor WebAssembly front-end to add more functionality to your voicemail service. I hope you enjoyed following this tutorial as much as I enjoyed writing it.

If you’d like to keep learning, I recommend taking a look at these articles:

]]> <![CDATA[Build a Voicemail Inbox using Twilio Voice and ASP.NET Core]]> 2026-08-05T12:10:00+00:00 https://volkanpaksoy.com/archive/2026/08/05/Build-a-Voicemail-Inbox-using-Twilio-Voice-and-ASPNET-Core

This article was originally published on the Twilio Blog.

Most mobile networks provide a voicemail service letting people who call you leave a message when you can’t answer, and letting you listen to those messages by calling your voicemail number. When you have programmatic access to your calls using Twilio, you can implement your voicemail service and customize it to you or your business’s needs.

In this tutorial, you will learn how to implement an Interactive Voice Response (IVR) app using ASP.NET Core Web API project to record and serve your voicemails and how to manage them (play/save/delete) by calling your Twilio phone number.

Prerequisites

You’ll need the following things in this tutorial:

Project overview

In this tutorial, you will implement an ASP.NET Core Web API to record and manage your voicemails. Before getting into the implementation details, let’s take a look at what it does:

The flow of your IVR starts when someone calls your Twilio phone number which Twilio picks up. Twilio passes the call details to your Web API and expects TwiML instructions to manage the call. If the caller’s phone number is one of the “owners” phone numbers, the voicemail directory flow will be invoked, otherwise the voicemail recording flow will be invoked.

Voicemail recording flow:

  • The IVR asks the caller to leave a message after the beep, after which the call is being recorded.

  • Once the caller finishes recording, the IVR thanks the caller for leaving a message and ends the call.

  • When Twilio saves the recording, Twilio will notify your Web API of the location of the recording and your Web API downloads the recording to disk.

Voicemail directory flow:

  • The IVR informs the user how many new and saved messages are available, and creates a queue of the messages

  • The IVR plays the current message in the queue and asks to press the dial pad buttons to either 1-replay, 2-save, or 3-delete the message.

  • If 1 is pressed, the message and the queue are not changed. If 2 is pressed, the message is saved, and then the message is removed from the queue. If 3 is pressed, the message is deleted, and then the message removed from the queue. If there are more messages in the queue, go to step 7.

  • The IVR informs the caller that there are no more messages and ends the call.

Now that you are more familiar with the end result, let’s get started.

Project set up

The easiest way to set up the starter project is by cloning the sample GitHub repository.

Open a terminal, change to the directory you want to download the project and run the following command:

git clone https://github.com/Dev-Power/voicemail-service-using-twilio.git --branch starter-project

The project can be found in the src\VoicemailDirectory.WebApi subfolder. Open the project in your IDE.

The project comes with empty files that you will implement as you go along. Before starting the implementation, let’s take a look at the key points in the starter project:

The API will download the audio recordings and store them under the wwwroot/Voicemails directory. To let Twilio have access to these files, static file hosting is enabled in the API by adding the following line to the Program.cs file:

app.UseStaticFiles();

!!!warning

The voicemail recordings will be stored on your web server and served as static files, meaning that anyone would be able to download them. In production, you should validate that the incoming HTTP requests, requesting these static files originate from Twilio, and not someone else. Follow the documentation for the Twilio helper library for ASP.NET on how to validate Twilio requests for static files and your webhooks.

!!!

The downloading operation and all local I/O operations will be handled via FileService, which is added to the IoC by the following statements in Program.cs:

builder.Services.AddHttpClient();
builder.Services.AddTransient<FileService>();

As explained in the project overview section, you must add the owner’s phones to the configuration to access your voicemails. You can only listen to your voicemails by calling from one of those numbers.

Update your configuration by adding your phone number(s) to the appsettings.json file:

 "Voicemail": {
    "Owners": [
      "{ YOUR PHONE NUMBER }"
    ]
  }

Next, for Twilio to be able to send HTTP requests to your Web API, you’ll need to make your locally running Web API publicly available over the internet. You can use ngrok for this, a free secure tunneling service. Run the following command to create a tunnel with ngrok:

ngrok http http://localhost:5096

!!!info

http://localhost:5096 is the local URL that your Web API will listen to for HTTP requests.

!!!

Note the forwarding URL on your screen, which should look like this:

Forwarding                    https://{random-url}.{region}.ngrok.io -> http://localhost:5096

Ngrok has now created a secure tunnel that will accept HTTP requests at the temporary Forwarding URL and forward those requests to http://localhost:5096.

When your Twilio phone number receives a phone call, Twilio will send an HTTP request to your Web API passing in the call information and expecting instructions. You need to configure where this HTTP request is sent when a call comes in.

To do this, go to the Twilio Console, select your account, and then click Phone Numbers → Manage → Active Numbers on the left pane. (If Phone Numbers isn’t on the left pane, click on Explore Products and then on Phone Numbers.)

Click on the phone number you want to use for your project and scroll down to the Voice section.

Under the A Call Comes In label, set the dropdown to Webhook, the text field next to it to the ngrok Forwarding URL suffixed with the /IncomingCall path, the next dropdown to HTTP POST, and click Save. It should look like this:

Build a Voicemail Inbox using Twilio Voice and ASP.NET Core - image 1

Note that you have to use HTTPS as the protocol when setting the webhook URL.

Now that all the plumbing is done, move on to the next section to implement the application.

Project implementation

The first step to recording voicemails is to receive the calls. As you added the /IncomingCall path to your webhook URL, your controller must match this.

Update the IncomingCallController.cs file with the following code:

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;
using Twilio.AspNet.Core;
using Twilio.TwiML;
namespace VoicemailDirectory.WebApi.Controllers;
[ApiController]
[Route("[controller]")]
public class IncomingCallController : TwilioController
{
    private readonly VoicemailOptions _voicemailOptions;
    public IncomingCallController(IOptionsSnapshot<VoicemailOptions> voicemailOptions)
    {
        _voicemailOptions = voicemailOptions.Value;
    }
    [HttpPost]
    public TwiMLResult Index([FromForm] string from)
    {
        var response = new VoiceResponse();
        var redirectUrl = _voicemailOptions.Owners.Contains(from)
            ? Url.Action("Index", "Directory")!
            : Url.Action("Index", "Record")!;
        response.Redirect(
            url: new Uri(redirectUrl, UriKind.Relative),
            method: Twilio.Http.HttpMethod.Post
        );
        return TwiML(response);
    }
}

The default action (Index) is invoked when somebody calls your Twilio phone number. The calling number is checked here to see if the caller is an owner or anybody else. If the caller is unknown, it redirects to the RecordController’s Index action. If the caller is an owner, it redirects to the DirectoryController’s Index action.

!!!info

Using IOptionsSnapshot allows you to update the phone numbers configured in appsettings.json in the Voicemail:Owners array without having to stop the application. This is especially useful when testing because you can quickly change the mode of operation by updating the configuration.

!!!

Update the RecordController.cs with the following code:

using Microsoft.AspNetCore.Mvc;
using Twilio.AspNet.Core;
using Twilio.TwiML;
using VoicemailDirectory.WebApi.Services;
namespace VoicemailDirectory.WebApi.Controllers;
[ApiController]
[Route("[controller]/[action]")]
public class RecordController : TwilioController
{
    private readonly ILogger<IncomingCallController> _logger;
    private readonly FileService _fileService;
    public RecordController(
        ILogger<IncomingCallController> logger,
        FileService fileService
    )
    {
        _logger = logger;
        _fileService = fileService;
    }
    [HttpPost]
    public TwiMLResult Index()
    {
        var response = new VoiceResponse();
        response.Say("Hello, please leave a message after the beep.");
        response.Record(
            timeout: 10,
            action: new Uri(Url.Action("Bye")!, UriKind.Relative),
            method: Twilio.Http.HttpMethod.Post,
            recordingStatusCallback: new Uri(Url.Action("RecordingStatus")!, UriKind.Relative),
            recordingStatusCallbackMethod: Twilio.Http.HttpMethod.Post
        );
        return TwiML(response);
    }
    [HttpPost]
    public TwiMLResult Bye() => new VoiceResponse()
        .Say("Thank you for leaving a message, goodbye.")
        .ToTwiMLResult();
    [HttpPost]
    public async Task RecordingStatus(
        [FromForm] string callSid,
        [FromForm] string recordingUrl,
        [FromForm] string recordingSid,
        [FromForm] string recordingStatus
    )
    {
        _logger.LogInformation(
            "Recording status changed to {recordingStatus} for call {callSid}. Recording is available at {recordingUrl}",
            recordingStatus, callSid, recordingUrl
        );
        if (recordingStatus == "completed")
        {
            await _fileService.DownloadRecording(recordingUrl, recordingSid);
        }
    }
}

Recording the voicemails is a 3-step process:

  • Respond with TwiML instruction to tell Twilio to record the call, which is done in the Index action.

  • When the caller is done recording, Twilio will send an HTTP request to the Bye action, because that’s the action URL configured on the Record TwiML. The Bye action will acknowledge the message has been taken to the caller, and because there’s no further TwiML instructions, the call will be ended.

  • When the recording status changes, Twilio will send an HTTP request to the RecordingStatus action, because that’s the recordingStatusCallback URL configured on the Record TwiML. The HTTP request sent to the RecordingStatus action will contain data such as the recording URL, SID, status, and more. If the status is completed, the action will download the audio recording and store it locally.

The caller may hang up before reaching the timeout, in which case they will not hear the acknowledgement message, but the recording will still be downloaded.

!!!warning

By default, Recording URLs don’t require authentication, and recordings are not encrypted. However, you can require basic authentication to access the recordings and configure recordings to be encrypted in the voice settings (Voice → Settings → General). If you enable basic authentication, you’ll need to provide the Twilio Account SID and Auth Token, or API Key SID and API Key Secret as the username and password. This tutorial assumes basic authentication is not enabled for recordings.

!!!

Next, update the third and final controller, DirectoryController, with the following code:

using Microsoft.AspNetCore.Mvc;
using Twilio.AspNet.Core;
using Twilio.TwiML;
using Twilio.TwiML.Voice;
using VoicemailDirectory.WebApi.Services;
namespace VoicemailDirectory.WebApi.Controllers;
[ApiController]
[Route("[controller]/[action]")]
public class DirectoryController : TwilioController
{
    private readonly ILogger<DirectoryController> _logger;
    private readonly FileService _fileService;
    public DirectoryController(
        ILogger<DirectoryController> logger,
        FileService fileService
    )
    {
        _logger = logger;
        _fileService = fileService;
    }
    [HttpPost]
    public TwiMLResult Index()
    {
        var newMessages = _fileService.GetRecordingSids(Constants.New);
        var savedMessages = _fileService.GetRecordingSids(Constants.Saved);
        var response = new VoiceResponse();
        string GetWordingSingularOrPlural(int messageCount) => messageCount == 1 ? "message" : "messages";
        string GetNumberOrNo(int messageCount) => messageCount == 0 ? "no" : messageCount.ToString();
        response.Say(
            $"Hello, you have {GetNumberOrNo(newMessages.Count)} new {GetWordingSingularOrPlural(newMessages.Count)} " +
            $"and {GetNumberOrNo(savedMessages.Count)} saved {GetWordingSingularOrPlural(savedMessages.Count)}. "
        );
        // If there are no new or saved messages, end the call
        if (newMessages.Count == 0 && savedMessages.Count == 0)
        {
            response.Say("Goodbye!");
            return TwiML(response);
        }
        // Start with the new messages if there are any
        string recordingType = newMessages.Count > 0 ? Constants.New : Constants.Saved;
        response.Say($"Playing {recordingType} messages.");
        // No filter to get all recordings. Order alphabetically so that the new ones come at top
        // Can prepend datetime as well to order more precisely
        var allMessages = _fileService.GetRecordingSids(string.Empty)
            .OrderBy(s => s)
            .ToList();
        response.Append(
            CreateGatherTwiml(allMessages)
                .Append(PlayNextMessage(allMessages))
                .Append(SayOptions())
        );
        return TwiML(response);
    }
    [HttpPost]
    public TwiMLResult Gather(
        [FromQuery] List<string> queuedMessages,
        [FromForm] int digits
    )
    {
        _logger.LogInformation(
            "QueuedMessages: {queuedMessages}, user entered: {digits}",
            queuedMessages, digits
        );
        var currentMessage = queuedMessages.First();
        var isCurrentMessageNew = currentMessage.StartsWith(Constants.New);
        var response = new VoiceResponse();
        switch (digits)
        {
            case 1: // Replay
                // No action. The existing message will stay at the top of the queue to be replayed
                break;
            case 2: // Save
                _fileService.SaveRecording(currentMessage);
                queuedMessages.Remove(currentMessage);
                break;
            case 3: // Delete
                _fileService.DeleteRecording(currentMessage);
                queuedMessages.Remove(currentMessage);
                break;
            default: // Invalid key. Play error message then say the valid options again.
                response.Say("Sorry, that key is not valid.");
                response.Append(
                    CreateGatherTwiml(queuedMessages)
                        .Append(SayOptions())
                );
                return TwiML(response);
        }
        if (queuedMessages.Count == 0)
        {
            response.Say("No more messages. Goodbye!");
            return TwiML(response);
        }
        if (isCurrentMessageNew && queuedMessages.First().StartsWith(Constants.Saved))
        {
            response.Say("No more new messages. Here are your saved messages.");
        }
        response.Append(
            CreateGatherTwiml(queuedMessages)
                .Append(PlayNextMessage(queuedMessages))
                .Append(SayOptions())
        );
        return TwiML(response);
    }
    private Gather CreateGatherTwiml(List<string> queuedMessages) => new Gather(
        input: new List<Gather.InputEnum> {Twilio.TwiML.Voice.Gather.InputEnum.Dtmf},
        timeout: 5,
        numDigits: 1,
        action: new Uri(
            Url.Action("Gather", new {queuedMessages})!,
            UriKind.Relative
        ),
        method: Twilio.Http.HttpMethod.Post
    );
    private Say SayOptions()
        => new Say("To replay press 1. To save the message press 2. To delete the message press 3.");
    private Play PlayNextMessage(List<string> queuedMessages)
    {
        var nextMessage = queuedMessages.First();
        return new Play(new Uri($"/Voicemails/{nextMessage}.mp3", UriKind.Relative));
    }
}

The response comprises three TwiML verbs:

  • Gather: Used to collect caller input which the caller provides by pressing a button in their dial keypad (DTMF)

  • Play: Used to play audio recordings to the caller

  • Say: Used to communicate the actions they can take after listening to the recordings.

!!!info

The queued messages are passed in the query string, so the number of voicemails the system supports is limited by the maximum length of a URL (which is around 2,000 characters). You may bump into issues after approximately 40 - 50 messages if you never delete them. If this is an issue you could store this in cookies, in session, or in some other data store.

!!!

When you call your Twilio phone number as the owner, the Index action will be executed. You haven’t implemented the FileService yet (which is next), but from the function names, you can deduce that this action does the following:

  • Get the new and saved recordings separately

  • Prepare a welcome message to indicate how many new and how many saved messages are in the directory

  • Get a list of all recordings and prepare the TwiML response to play the first message in the queue, followed by prompting the available options.

After the first message is played to the caller and the caller has made their decision, Twilio passes this information to the Gather action of the controller. Now you have to decide what to do based on the caller’s action, which is what the switch statement in the Gather action does.

Before going over the logic in this controller, implement the FileService as well, as the controller uses that service heavily.

Update the FileService.cs file with the following code:

namespace VoicemailDirectory.WebApi.Services;
public class FileService
{
    private readonly HttpClient _httpClient;
    private readonly string _rootVoicemailPath;
    public FileService(IHttpClientFactory httpClientFactory, IWebHostEnvironment webHostEnvironment)
    {
        _rootVoicemailPath = $"{webHostEnvironment.WebRootPath}/Voicemails";
        _httpClient = httpClientFactory.CreateClient();
    }
    public async Task DownloadRecording(string recordingUrl, string recordingSid)
    {
        using HttpResponseMessage response = await _httpClient.GetAsync($"{recordingUrl}.mp3");
        response.EnsureSuccessStatusCode();
        await using var fs = new FileStream(
            $"{_rootVoicemailPath}/{Constants.New}_{recordingSid}.mp3",
            FileMode.CreateNew
        );
        await response.Content.CopyToAsync(fs);
    }
    public List<string> GetRecordingSids(string recordingType)
        => Directory.GetFiles($"{_rootVoicemailPath}/", $"{recordingType}*.mp3")
            .Select(s => Path.GetFileNameWithoutExtension(s))
            .ToList();
    public void SaveRecording(string recordingSid)
    {
        var currentPath = GetRecordingPathBySid(recordingSid);
        var newPath = currentPath.Replace($"{Constants.New}", $"{Constants.Saved}");
        File.Move(currentPath, newPath);
    }
    public void DeleteRecording(string recordingSid) => File.Delete(GetRecordingPathBySid(recordingSid));
    private string GetRecordingPathBySid(string recordingSid)
        => Directory.GetFiles($"{_rootVoicemailPath}/", "*.mp3")
            .Single(s => s.Contains(recordingSid));
}

If the user has pressed 1 to replay the message, you don’t have to do anything in your API other than return the same response. As long as the message is left at the top of the queue, it will be played to the caller.

If the user has pressed 2 to save the message, the controller calls the SaveRecording method of the FileService, which renames the file by replacing “New” with “Saved”. This way, the next time you call your voicemail service, this recording will be treated as an old recording.

If the user has pressed 3 to delete the message, the controller calls the DeleteRecording method of the FileService, which deletes the file from the file system.

If the caller has pressed any other key, the action returns the TwiML to say that the key was invalid, replays the valid options, and listens for the next dialpad button to be pressed, so that they can correct their mistake.

Test the application

First, to test leaving a voicemail, remove your phone number from appsettings.json and run the application with the following command:

dotnet run

Call your Twilio phone number. You should be greeted with “Hello, please leave a message after the beep.”. Leave your message. After a few seconds, you should see a new MP3 file saved under wwwroot/Voicemails directory prefixed with “New_” indicating that it has not been played to the user before (at least not saved by the user, so it’s treated as a new message).

Update the appsettings.json by adding your number in the owner’s list and call your Twilio phone number again.

This time you should be greeted with a message telling you have 1 new message and no saved messages, followed by the recorded message. You can then take action and choose what to do with the messages.

Conclusion

When determining the scope and business logic of this voicemail service, I used my own phone provider as a guide. I was able to add all the features that they provide, so by implementing this project you created yourself a voicemail service that actually matches the features of a real voicemail service. You can deploy this to a cloud provider and give your Twilio number to receive voicemails when you don’t want to distribute your own phone number.

Apart from that, you learned how to deal with call recordings and user input. If you’d like to keep learning, I recommend taking a look at these articles:

]]> <![CDATA[Build a Soundboard using GCP Speech-To-Text, Twilio Voice Media Streams, and ASP.NET Core]]> 2026-08-05T12:05:00+00:00 https://volkanpaksoy.com/archive/2026/08/05/Build-a-Soundboard-using-GCP-Speech-To-Text-Twilio-Voice-Media-Streams-and-ASPNET-Core

This article was originally published on the Twilio Blog.

Twilio Media Streams give programmers access to the raw audio of a phone call in real-time. This allows you to process the media and enhance your applications by running sentiment analysis, speech recognition, etc. In this tutorial, you will learn how to receive the raw audio via WebSockets, transcribe the call using Google Cloud’s Speech-to-Text service and play audio files based on the user’s commands.

Prerequisites

You’ll need the following things in this tutorial:

Set up GCP Speech-to-Text

To use the Speech-to-Text API, you must enable it in the Google Cloud console. If you have never used GCP, you can log in to your Google account and go to the free trial start page and

click the Start free button.

You will be asked to enter your personal information through a 2-step process. Once you’ve completed the process, you should gain access to $300 free credits that will be valid for 90 days.

To start developing your application, you will need to create a project in Google Cloud. In my account, Google automatically created a new project called “My First Project”. If you don’t have this or would like to create a brand new one, go to Menu > IAM & Admin > Create a Project.

You should see the new project creation screen with a default name already chosen for you. You can change it to your liking:

Build a Soundboard using GCP Speech-To-Text, Twilio Voice Media Streams, and ASP.NET Core - image 1

Click the Create button to finish project creation. To switch between the projects, you can click on the project name next to Google Cloud logo and browse your projects.

Build a Soundboard using GCP Speech-To-Text, Twilio Voice Media Streams, and ASP.NET Core - image 2

The dialog also has a New Project button which you can use to create new projects.

Once you’ve created and selected your project, go to the Cloud Speech-to-Text API product page and click Enable.

Build a Soundboard using GCP Speech-To-Text, Twilio Voice Media Streams, and ASP.NET Core - image 3

You should see a notification advising you to create credentials. Click Create Credentials.

Build a Soundboard using GCP Speech-To-Text, Twilio Voice Media Streams, and ASP.NET Core - image 4

In the Which API you are using section, select Cloud Speech-to-Text API if it’s not already selected.

Build a Soundboard using GCP Speech-To-Text, Twilio Voice Media Streams, and ASP.NET Core - image 5

In the What data will you be accessing section, select Application data.

Select No, I’m not using them as the answer to the Are you planning to use this API with Compute Engine… question and click Next.

On the Service account details page, give your service account a name such as transcribe-twilio-call.

The Service Account ID should be automatically populated based on the name you chose.

Click Create and Continue.

The rest of the settings are optional, so you can click Done and complete the process.

To use this service account, you will need credentials. On the left menu, click Credentials.

While still on the Cloud Speech-to-Text API page, switch to the Credentials tab.

Build a Soundboard using GCP Speech-To-Text, Twilio Voice Media Streams, and ASP.NET Core - image 6

Scroll down to the Service Accounts and click your account.

Switch to the Keys section and click Add Key → Create new key.

Select JSON if not selected already, and click Create.

Build a Soundboard using GCP Speech-To-Text, Twilio Voice Media Streams, and ASP.NET Core - image 7

This should start a download of your private key in a JSON file.

Copy this file to a safe location and set the GOOGLE_APPLICATION_CREDENTIALS environment variable by running the command appropriate to your system.

export GOOGLE_APPLICATION_CREDENTIALS={ PATH TO YOUR JSON FILE }

$Env:GOOGLE_APPLICATION_CREDENTIALS={ PATH TO YOUR JSON FILE }

set GOOGLE_APPLICATION_CREDENTIALS={ PATH TO YOUR JSON FILE }

Twilio Media Streams

In a Twilio voice application, you can use the Stream verb to receive raw audio streams from a live phone call over WebSockets in near real-time.

WebSockets

A WebSocket is a protocol for bidirectional communication between a client (such as a web browser) and a server over a single, long-lived connection. WebSockets allow for real-time, two-way communication between the client and server and can be used for a variety of applications such as online gaming, chat applications, and data streaming. Unlike traditional HTTP connections, which are request-response based, WebSockets provide a full-duplex communication channel for continuous, real-time data exchange.

Stream WebSocket Messages

In the Twilio Stream WebSocket, each message is sent in a JSON string. There are different message types, and to identify the message type, first, you need to parse the JSON and check the value of the event field.

The possible values for the WebSocket messages coming from Twilio are:

  • connected: The first message sent once a WebSocket connection is established.

  • start: This message contains important metadata about the stream and is sent immediately after the connected message. It is only sent once at the start of the Stream.

  • media: This message type encapsulates the raw audio data.

  • stop: This message will be sent when the Stream is stopped or the call has ended.

  • mark: The mark event is sent only during bidirectional streaming using the <Connect> verb. It is used to track or label when media has completed.

The possible values for the WebSocket messages coming from Twilio are:

  • media: To send media back to Twilio, you must provide a similarly formatted media message. The payload must be encoded audio/x-mulaw with a sample rate of 8000 and base64 encoded. The audio can be of any size.

  • mark: Send a mark event message after sending a media event message to be notified when the audio that you have sent has been completed.

  • clear: Send the clear event message if you would like to interrupt the audio that has been sent various media event messages.

In the demo project, you will learn more about the other fields that are used in these messages.

WAVE File Format Analysis

The telephony standard for audio is 8-bit PCM mono uLaw (MULAW) with a sampling rate of 8Khz. The payload of the media message should not contain the audio file type header bytes. So it’s essential to understand the WAV file header fields so that you can strip them off before sending the audio data to the user.

A standard WAV file header comprises the following fields:

Positions

Sample Value

Description

1 - 4

“RIFF”

Marks the file as a riff file. Characters are each 1 byte long.

5 - 8

File size (integer)

Size of the overall file - 8 bytes, in bytes (32-bit integer). Typically, you’d fill this in after creation.

9 -12

“WAVE”

File Type Header. For our purposes, it always equals “WAVE”.

13-16

“fmt “

Format chunk marker. Includes trailing null

17-20

16

Length of format data as listed above

21-22

1

Type of format (1 is PCM) - 2 byte integer

23-24

2

Number of Channels - 2 byte integer

25-28

44100

Sample Rate - 32 byte integer. Common values are 44100 (CD), 48000 (DAT). Sample Rate = Number of Samples per second, or Hertz.

29-32

176400

(Sample Rate * BitsPerSample * Channels) / 8.

33-34

4

(BitsPerSample * Channels) / 8.1 - 8 bit mono2 - 8 bit stereo/16 bit mono4 - 16 bit stereo

35-36

16

Bits per sample

37-40

“data”

“data” chunk header. Marks the beginning of the data section.

41-44

File size (data)

Size of the data section.

(Source: https://docs.fileformat.com/audio/wav/)

A WAVE file is a collection of a number of different types of chunks. The fmt chunk is required, and it contains parameters describing the waveform.

Now, open the bird.wav in a hex editor and review the file. Note that the file length is 54,084 bytes.

Build a Soundboard using GCP Speech-To-Text, Twilio Voice Media Streams, and ASP.NET Core - image 8

Here you can see the fields:

Positions

Bytes

Value

Explanation

1 - 4

52 49 46 46

“RIFF”

As expected

5 - 8

00 00 D3 3C

54,076 (Little-endian) (File length -8)

As expected

9 - 12

57 41 56 45

“WAVE”

As expected

13 - 16

66 6D 74 20

“fmt” with trailing space

As expected

17- 20

12 00 00 00

Length of fmt chunk data: 18

As expected. Can be 16, 18 or 40

21 - 22

00 07

Type of format: Mulaw (7)

As expected

23 - 24

00 01

Number of channels: 1

As expected

25 - 28

00 00 1F 40

Sample rate: 8000

As expected

29 - 32

00 00 1F 40

(Sample Rate * Bit per sample * Channels) / 8

(8000 * 8 * 1) / 8 = 8000

As expected

33 - 34

00 01

(BitsPerSample * Channels) / 8

(8 * 1) / 8 = 1

As expected

35 - 36

00 08

8 Bits per sample

As expected

37 - 38

00 00

Size of the extension: 0

Expected: Start of data. Microsoft Windows Media Player will not play non-PCM data (e.g. µ-law data) if the fmt chunk does not have the extension size field (cbSize) or a fact chunk is not present.

39 - 42

66 61 63 74

“fact”

Optional fact chunk

43 - 46

00 00 00 04

4 = Size of the fact chunk data

47 - 50

00 00 D3 0A

54,026 = chunk data. Equal to file length.

Fact chunk explanation

51 - 54

64 61 74 61

“data”

As expected, except it starts at 51 because of the fact chunk

55 - 58

00 00 D3 0A

Size of the data: 54,026

As expected

As you can see, the actual file header diverges slightly from the standard header description.

The takeaways from this analysis are:

  • The audio data starts after the first 58 bytes. You will skip those bytes in the demo and only send the audio data to the caller.

  • You may encounter different header lengths and subsequently may need to adjust the number of bytes to skip; otherwise, you may hear distorted audio on the phone.

Now that you understand the WAV format better, proceed to the next section to implement the project to play audio files to a phone call.

Sample Project: Animal Soundboard

The project requires to have some audio files to function properly. The easiest way to set up the starter project is by cloning the sample GitHub repository.

Open a terminal, change to the directory you want to download the project, and run the following command:

git clone https://github.com/Dev-Power/play-audio-to-a-phone-call-using-media-streams.git --branch starter-project

The project can be found in the src\PlayAudioUsingMediaStreams subfolder. Open the project in your IDE.

The starter project comes with 2 controllers: IncomingCallController and AnimalSoundboardController. IncomingCallController currently only plays back a simple message to test your setup. You will implement AnimalSoundboardController as you go along.

It also comes with 4 WAV files that will be used in the project.

Open another terminal and run ngrok like this:

ngrok http http://localhost:5214

For Twilio to know where to send webhook requests, you need to update the webhook settings on your Twilio phone number.

Go to the Twilio Console. Select your account, and then click Phone Numbers → Manage → Active Numbers on the left pane. (If Phone Numbers isn’t on the left pane, click on Explore Products and then on Phone Numbers.)

Click on the phone number you want to use for your project and scroll down to the Voice section.

Under the A Call Comes In label, set the dropdown to Webhook, the text field next to it to the ngrok Forwarding URL suffixed with the /IncomingCall path, the next dropdown to HTTP POST, and click Save. It should look like this:

Build a Soundboard using GCP Speech-To-Text, Twilio Voice Media Streams, and ASP.NET Core - image 9

Note that you have to use HTTPS as the protocol when setting the webhook URL.

In the terminal, run the following command:

dotnet run

Call your Twilio number, and you should hear the message “If you can hear this, your setup works!” played back to you.

After you’ve confirmed you can receive calls in your application, update the code in the Index method of the IncomingCallController with the code below:

var response = new VoiceResponse();
response.Say("Say animal names to hear their sounds.");
var connect = new Connect();
connect.Stream(
    name: "Animal Soundboard", 
    url: Url.Action(
        action: "Get", 
        controller: "AnimalSoundboard",
        values: null,
        protocol: "wss"
    )
);
response.Append(connect);
Console.WriteLine(response.ToString());
return TwiML(response);

This update replaces the message and adds Stream verb to the output. It prints the response before sending it back, so you can see the TwiML you created, which looks like this:

<?xml version="1.0" encoding="utf-8"?>
<Response>
  <Say>Say animal names to hear their sounds.</Say>
  <Connect>
    <Stream name="Animal Soundboard" url="wss://{YOUR NGROK URL}/animalsoundboard"></Stream>
  </Connect>
</Response>

In the demo, you will receive raw user audio and play animal sounds back depending on the commands you receive, so you have to maintain a synchronous bi-directional connection. This is why you use the Connect verb instead of the Start verb, which is asynchronous and immediately continues with the next TwiML instruction. You can read more about TwiML stream verbs here.

Now, it’s time to implement the web socket. The first version will just echo the user’s voice back. Update the AnimalSoundboardController with the code below:

using System.Net.WebSockets;
using Microsoft.AspNetCore.Mvc;
using Twilio.AspNet.Core;
namespace PlayAudioUsingMediaStreams.WebApi.Controllers;
[ApiController]
[Route("[controller]")]
public class AnimalSoundboardController : Controller
{
    public async Task Get()
    {
        if (HttpContext.WebSockets.IsWebSocketRequest)
        {
            using var webSocket = await HttpContext.WebSockets.AcceptWebSocketAsync();
            await Soundboard(webSocket);
        }
        else
        {
            HttpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
        }
    }
    private async Task Soundboard(WebSocket webSocket)
    {
        var buffer = new byte[1024 * 4];
        var receiveResult = await webSocket.ReceiveAsync(
            new ArraySegment<byte>(buffer), CancellationToken.None);
        while (!receiveResult.CloseStatus.HasValue)
        {
            await webSocket.SendAsync(
                new ArraySegment<byte>(buffer, 0, receiveResult.Count),
                receiveResult.MessageType,
                receiveResult.EndOfMessage,
                CancellationToken.None);
            receiveResult = await webSocket.ReceiveAsync(
                new ArraySegment<byte>(buffer), CancellationToken.None);
        }
        await webSocket.CloseAsync(
            receiveResult.CloseStatus.Value,
            receiveResult.CloseStatusDescription,
            CancellationToken.None);
    }
}

Before you run the application, you have to modify the Program.cs and add WebSocket support as shown below:

```csharp hl_lines=”3” app.MapControllers(); app.UseWebSockets(); app.Run();


Re-run the application and call your Twilio phone number again. You should hear yourself on the phone as you speak.

This version of the code reads the streaming data from the web socket, and as long as the connection is open, it sends the same data back to the user.

This is how you can access the raw audio of a phone call. This primitive version does not look inside the messages. What you receive over the web socket is a JSON message. 

In the next version, you will parse the messages as well. Before that, you'll need some supporting services. 

To model the sounds, create a new file called Sound.cs and update its contents like this:

```csharp
namespace PlayAudioUsingMediaStreams.WebApi;
public class Sound
{
    public string Name { get; set; }
    public List<string> Keywords { get; set; }
    public string AudioDataAsBase64 { get; set; }
}

Every sound has a name, a list of keywords, and the audio data. In this project, you will use animal names as keywords, but the application can be used for any group of sounds.

Create a new folder called Services and a new file under it called SoundService.cs. Update the code as below:

namespace PlayAudioUsingMediaStreams.WebApi.Services;
public class SoundService
{
    private const string AudioRoot = "../../audio";
    private const int WavHeaderBytesToSkip = 58;
    private List<Sound> _sounds = new()
    {
        new() { Name = "dog", Keywords = new List<string> { "dog", "canine", "pooch", "hound" } },
        new() { Name = "cat", Keywords = new List<string> { "cat", "kitty", "kitten" } },
        new() { Name = "bird", Keywords = new List<string> { "bird" } },
        new() { Name = "elephant", Keywords = new List<string> { "elephant" } },
    };
    public SoundService()
    {
        // Load all files into memory once to avoid constant disk access
        foreach (var sound in _sounds)
        {
            var audioFilePath = $"{AudioRoot}/{sound.Name}.wav";
            var rawAudioData = File.ReadAllBytes(audioFilePath);
            // Skip the header bytes while copying
            var tempAudioData = new byte[rawAudioData.Length - WavHeaderBytesToSkip];
            Array.Copy(rawAudioData, WavHeaderBytesToSkip, tempAudioData, 0, tempAudioData.Length);
            sound.AudioDataAsBase64 = Convert.ToBase64String(tempAudioData);
        }
    }
    public bool TryFindSoundByKeyword(string keyword, out Sound sound)
    {
        sound = _sounds.FirstOrDefault(s => s.Keywords.Contains(keyword));
        return sound != null;
    }
}

At construction, the service initializes all the sound objects. It loads the audio data into memory, so they can be played in rapid succession without having to access the files from disk repeatedly.

Also, it handles skipping the wav header bytes, as discussed in the previous section.

You also need to identify the keywords that the user is uttering. To achieve this, you’ll need to use Google Speech-to-Text service. Install the SDK by running the following command:

dotnet add package Google.Cloud.Speech.V1

Under the Services folder, create a new file called SpeechRecognitionService.cs with the following contents:

using Google.Api.Gax.Grpc;
using Google.Cloud.Speech.V1;
using Google.Protobuf;
namespace PlayAudioUsingMediaStreams.WebApi.Services;
public class SpeechRecognitionService
{
    private StreamingRecognitionConfig _streamingConfig = new()
    {
        Config = new RecognitionConfig
        {
            Encoding = RecognitionConfig.Types.AudioEncoding.Mulaw,
            SampleRateHertz = 8000,
            LanguageCode = "en-US",
            EnableWordConfidence = true,
            UseEnhanced = true
        },
        InterimResults = true
    };
    private SpeechClient _speechClient;
    private SpeechClient.StreamingRecognizeStream _streamingRecognizeStream;
    public SpeechRecognitionService(SpeechClient speechClient)
    {
        _speechClient = speechClient;
    }
    public async Task<AsyncResponseStream<StreamingRecognizeResponse>> InitStream()
    {
        _streamingRecognizeStream = _speechClient.StreamingRecognize();
        await _streamingRecognizeStream.WriteAsync(new StreamingRecognizeRequest
        {
            StreamingConfig = _streamingConfig,
        });
        return _streamingRecognizeStream.GetResponseStream();
    }
    public async Task SendAudio(string payload)
    {
        await _streamingRecognizeStream.WriteAsync(new StreamingRecognizeRequest
        {
            AudioContent = ByteString.FromBase64(payload)
        });
    }
}

This service is responsible for initializing the Google speech client. When you first create the stream, you write the recognition configuration as shown in the InitStream method. This returns the response stream; from that point on, you only write the audio data to the stream via the SendAudio method.

To be able to use these services with dependency injection, add them to the IoC container:

```csharp hl_lines=”3 4 5” builder.Services.AddSwaggerGen(); builder.Services.AddSpeechClient(); builder.Services.AddTransient(); builder.Services.AddTransient(); var app = builder.Build();


Make sure to add the using statement to the top of the file as well:

```csharp
using PlayAudioUsingMediaStreams.WebApi.Services;

Finally, update the AnimalSoundboardController as shown below:

using System.Net.WebSockets;
using System.Text;
using System.Text.Json;
using Google.Api.Gax.Grpc;
using Google.Cloud.Speech.V1;
using Microsoft.AspNetCore.Mvc;
using PlayAudioUsingMediaStreams.WebApi.Services;
namespace PlayAudioUsingMediaStreams.WebApi.Controllers;
[ApiController]
[Route("[controller]")]
public class AnimalSoundboardController : Controller
{
    private readonly SoundService _soundService;
    private readonly SpeechRecognitionService _speechRecognitionService;
    private readonly IHostApplicationLifetime _applicationLifetime;
    public AnimalSoundboardController(
        SoundService soundService,
        SpeechRecognitionService speechRecognitionService,
        IHostApplicationLifetime applicationLifetime
    )
    {
        _soundService = soundService;
        _speechRecognitionService = speechRecognitionService;
        _applicationLifetime = applicationLifetime;
    }
    [HttpGet]
    public async Task Get()
    {
        if (HttpContext.WebSockets.IsWebSocketRequest)
        {
            using var webSocket = await HttpContext.WebSockets.AcceptWebSocketAsync();
            await Soundboard(webSocket);
        }
        else
        {
            HttpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
        }
    }
    private async Task Soundboard(WebSocket webSocket)
    {
        string streamSid = null;
        var buffer = new byte[1024 * 4];
        var receiveResult = await webSocket.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
        await using var speechRecognitionStream = await _speechRecognitionService.InitStream();
        while (!receiveResult.CloseStatus.HasValue &&
               !_applicationLifetime.ApplicationStopping.IsCancellationRequested)
        {
            using var jsonDocument = JsonDocument.Parse(Encoding.UTF8.GetString(buffer, 0, receiveResult.Count));
            var eventMessage = jsonDocument.RootElement.GetProperty("event").GetString();
            switch (eventMessage)
            {
                case "connected":
                    Console.WriteLine("Event: connected");
                    break;
                case "start":
                    Console.WriteLine("Event: start");
                    streamSid = jsonDocument.RootElement.GetProperty("streamSid").GetString();
                    Console.WriteLine($"StreamId: {streamSid}");
                    // Do not await task, leave this task running in the background for the duration of the websocket connection
                    var _ = ListenForSpeechRecognition(webSocket, streamSid, speechRecognitionStream)
                        .ConfigureAwait(false);
                    break;
                case "media":
                    var payload = jsonDocument.RootElement.GetProperty("media").GetProperty("payload").GetString();
                    await _speechRecognitionService.SendAudio(payload);
                    break;
                case "stop":
                    Console.WriteLine("Event: stop");
                    break;
            }
            receiveResult = await webSocket.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
        }
        if (receiveResult.CloseStatus.HasValue)
        {
            await webSocket.CloseAsync(
                receiveResult.CloseStatus.Value,
                receiveResult.CloseStatusDescription,
                CancellationToken.None);
        }
        else if (_applicationLifetime.ApplicationStopping.IsCancellationRequested)
        {
            await webSocket.CloseAsync(
                WebSocketCloseStatus.EndpointUnavailable,
                "Server shutting down",
                CancellationToken.None);
        }
    }
    private async Task ListenForSpeechRecognition(
        WebSocket webSocket,
        string streamSid,
        AsyncResponseStream<StreamingRecognizeResponse> speechRecognitionStream
    )
    {
        while (await speechRecognitionStream.MoveNextAsync())
        {
            var word = speechRecognitionStream.Current?.Results.FirstOrDefault()
                ?.Alternatives.FirstOrDefault()
                ?.Words.FirstOrDefault();
            if (word == null) continue;
            Console.WriteLine($"Word: [{word.Word}]. Confidence: {word.Confidence:N2}");
            if (word.Confidence < 0.5)
            {
                Console.WriteLine($"Low confidence. Skipping the word [{word.Word}]");
                continue;
            }
            var utterance = word.Word.Trim().ToLower();
            if (!_soundService.TryFindSoundByKeyword(utterance, out var soundToPlay))
            {
                continue;
            }
            Console.WriteLine($"Animal detected: {soundToPlay.Name}");
            var mediaMessage = new
            {
                streamSid,
                @event = "media",
                media = new
                {
                    payload = soundToPlay.AudioDataAsBase64
                }
            };
            var rawJson = JsonSerializer.Serialize(mediaMessage);
            var responseBuffer = Encoding.UTF8.GetBytes(rawJson);
            await webSocket.SendAsync(
                new ArraySegment<byte>(responseBuffer, 0, responseBuffer.Length),
                WebSocketMessageType.Text,
                true,
                CancellationToken.None);
        }
    }
}

As mentioned before, now you’re parsing the JSON message:

var jsonDocument = JsonDocument.Parse(Encoding.UTF8.GetString(buffer, 0, receiveResult.Count))

First action is to determine the message type. You achieve this by parsing the event property:

string eventMessage = jsonDocument.RootElement.GetProperty("event").GetString();

As you saw at the beginning of the article, there are different types of events. In the application, you’re interested in 3 of them:

  • connected: This is where you initialize your Google speech client and the stream.

  • start: You receive the unique stream identifier in this message. This id must be stored to be able to send audio back to the caller.

  • media: Whenever you receive a media message, you parse the payload and send it to Google for speech recognition.

The final important update is to use both sound and speech recognition services to identify if a keyword was uttered by the user. If this happens, you prepare a new media message, convert it to JSON and send it to the user.

var mediaMessage = new
{
    streamSid, 
    @event = "media", 
    media = new
    {
        payload = soundToPlay.AudioDataAsBase64
    }
};

To test the final version, rerun your application and call your phone.

Speak some of the keywords, and you should hear the corresponding animals’ sounds:

Build a Soundboard using GCP Speech-To-Text, Twilio Voice Media Streams, and ASP.NET Core - image 10

How to Add More Audio

If you enjoyed this little project and would like to add more sounds, here’s how I created the stock sounds:

Go to BBC Sound Effects website.

Search for the animal you’re looking for, click the download button, and select wav as the file format.

Build a Soundboard using GCP Speech-To-Text, Twilio Voice Media Streams, and ASP.NET Core - image 11

Once you’ve downloaded the file, go to G711 File Converter.

Locate your file by clicking Browse.

Select u-Law WAV as the output format and click Submit.

Click on the link of the converted file to download it.

Most audio files are too long to be able to play one after another quickly. I use Audacity to open the files and copy the part I’m interested in.

Build a Soundboard using GCP Speech-To-Text, Twilio Voice Media Streams, and ASP.NET Core - image 12

Once you’ve selected the portion you want, click File → Export → Export Selected Audio to save it as a separate file.

Conclusion

In this tutorial, you learned how WebSockets work and how to use them in a voice application to establish a 2-way audio connection to the caller. You also learned more about media streams and the audio format standard for telephony. You used all this knowledge to implement a project to play audio files to the user based on their commands. This project shows you have the ability to access raw audio and partial transcriptions. Now you can use this to implement your own projects.

If you’d like to keep learning, I recommend taking a look at these articles:

]]> <![CDATA[Send Emails with C#, Handlebars Templating, and Dynamic Email Templates]]> 2026-08-05T12:00:00+00:00 https://volkanpaksoy.com/archive/2026/08/05/Send-Emails-with-CSharp-Handlebars-Templating-and-Dynamic-Email-Templates

This article was originally published on the Twilio Blog.

Email communication is an essential aspect of most businesses. In this post, you will look into the basics of sending emails with the Twilio SendGrid Email API and sending templated emails with the Handlebars templating language. Finally, you will finish by putting it together in a sample project that sends emails based on a template.

Prerequisites

You’ll need the following things for this tutorial:

Set Up SendGrid

API Key

First things first: To use the SendGrid API, you need an API key. Create one by heading over to the SendGrid dashboard and clicking on Settings → API Keys on the left menu and clicking the “Create API Key” button in the top-right corner:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 1

Next, give your key a name and select the permissions. You can choose Restricted Access to pick individual permissions.

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 2

For brevity, in this tutorial, select Full Access. After selecting Full Access, click “Create & View” to finish the key creation process.

The final step is crucial: The key will be displayed one time and one time only.

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 3

When the key is displayed, click on the key, which copies it to the clipboard. Then, keep it in a safe place, such as a password manager, and click Done.

Sender Email

Every email you send must be sent from a verified email address or domain. To create a sender, click Sender Authentication in the left menu.

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 4

Here you can verify a single address or an entire domain. Verifying the entire domain requires access to DNS settings, so to keep things simple, you will use single address verification.

To achieve this, click Verify a Single Sender on the Sender Authentication page (or Get Started if you don’t have any previously verified email addresses).

You should land on Create a Sender form:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 5

Fill in the details and click Create. The next step is to wait for the verification email:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 6

It should momentarily appear in your mailbox. Find the email and click on the Verify Single Sender button in the email:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 7

This takes you to the confirmation page:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 8

Now that you have an API key and a valid sender address, you can move on to sending emails.

Send Emails with SendGrid

Now that you have an API key, you’ll create a simple .NET application to test sending emails. (You can find the complete source code on this GitHub repository)

First, open a terminal and run the following commands to create a blank Console application and add the SendGrid NuGet package:

dotnet new console -o ConsoleMailer
cd ConsoleMailer
dotnet add package SendGrid

API keys are sensitive information that you should keep secret, so you should avoid hard coding them or committing them to source control. That’s why you should store the API key in an environment variable or a secure vault service. To keep things simple, you will store the API key in an environment variable.

For macOS and Linux, set the environment variable like this:

export SENDGRID_API_KEY={your key}

If you’re using PowerShell on Windows or another OS, use this command:

$Env:SENDGRID_API_KEY = "{your key}"

If you’re using CMD on Windows, use this command:

set "SENDGRID_API_KEY={your key}"

Replace {your key} with the API key secret you copied earlier.

Open the project in your preferred editor and find the Program.cs file. Update the Program.cs file with the following code:

using SendGrid;
using SendGrid.Helpers.Mail;
var apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY");
var client = new SendGridClient(apiKey);
var from = new EmailAddress("{ Your verified email address }", "{ Sender display name }");
var to = new EmailAddress("{ Recipient email address }", "{ Recipient display name }");

The code block above is going to be shared among the examples used in this article. You’ll need to replace { Your verified email address } with the SendGrid Single Sender email address you created earlier, and { Sender display name } with any name you prefer. The name will be displayed to the recipients. Then replace { Recipient email address} and { Recipient display name} with your desired recipient email address and name.

Then, append the following code block:

var subject = "Testing the API key";
var plainTextContent = "Testing a simple email";
var htmlContent = "<strong>Testing simple email in HTML</strong>";
var msg = MailHelper.CreateSingleEmail(from, to, subject, plainTextContent, htmlContent);
var response = await client.SendEmailAsync(msg);
if (response.IsSuccessStatusCode)
{
    Console.WriteLine("Email has been sent successfully");
}

The received email looks like this:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 9

!!!info

The methods from the MailHelper class like CreateSingleEmail all create a SendGridMessage object. You can also create a SendGridMessage object yourself, but the MailHelper class provides some convenient methods to do this for you for common scenario’s.

!!!

Dynamic Email Templates

Even though the data inside the email changes from email to email (such as the recipient name), most emails are based on some template. SendGrid has a powerful template designer that you can use to create dynamic templates, but you can also write the templates using code yourself.

To create your templates, navigate to the SendGrid Dashboard, click Email API and then Dynamic templates on the left menu. In the Dynamic Templates screen, click the “Create a Dynamic” template button.

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 10

Give the template a name and click Create:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 11

One nice feature about templates is that they are versioned. So you can create a new version without losing the previous version of the template. This way you can easily roll back to an earlier version.

Create your first version by clicking Add Version:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 12

SendGrid has a lot of built-in email templates:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 13

In this example, you’ll create a template from scratch. So, click on Your Email Designs and click Blank Template:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 14

Now you have to select the editor. Here you have two options: Design Editor and Code Editor. If you already have the HTML of an email template, you can simply switch to the code editor and start using that as a starting point.

In this example, you will use the designer, which simplifies designing email templates quite a bit. You can drag and drop the modules into the designer area. You can even test your emails directly in the designer.

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 15

You can also use test data to ensure it looks good while still designing.

For example, to test this design that uses the recipientName variable as a placeholder, you can click Preview and Show Test Data. Then you can enter your variable value as JSON and see the output.

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 16

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 17

At this point, you can design the email template to your liking by using basic modules such as text, image, HTML code, divider, etc.

The “dynamic” part comes from the ability to use placeholders, which then can be replaced with actual values. To understand how that works, you’ll need to understand how the templating support works with SendGrid. SendGrid emails support the Handlebar templating language (both in transactional templates and marketing campaign designs). Next, you will look into the basics of Handlebars to understand how you can leverage it to create dynamic data-driven templates.

Handlebars Templating Language

Handlebars is a commonly used templating language. It’s simple and quite powerful for creating dynamic templates.

Variable Substitution

Simple variable replacement is widely used in dynamic templates. As shown in the previous section, you can place a variable in your template by using it between opening and closing double-curly braces, such as:

Hello, {{recipientName}}

When you use a template such as this, you’ll need to provide data that includes the value; otherwise, it’s left blank. The nice thing is at least the placeholder is still replaced with an empty string so that it doesn’t appear in the final email, which would look very ugly and amateurish.

In C#, you can leverage normal .NET objects, including anonymous types, to provide dynamic data. For example, to provide data to the template above, you can use an anonymous object like this:

var dynamicEmailData = new
{
    recipientName = "Demo User",
};

To avoid leaving the variables blank, you can also provide default values by using the insert keyword. For example,

Hello,{{ insert recipientName "default=Valued User" }}

If you don’t provide recipientName in the data, the output looks like this:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 18

Variable Replacement in the Subject Field

In the designer, you can manually set a subject for your emails, but you can make this field dynamic as well. Variable substitution works for the subject field too. You can set the subject value as a variable using Handlebar notation:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 19

You are not obligated to replace the entire subject line. You can use a variable inside a longer hard-coded string in your template such as:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 20

To replace the placeholder with the actual value, in your code, you can just pass the actual value through template data:

var dynamicTemplateData = new
{
    subject = $"To-Do List for {DateTime.UtcNow:MMMM}"
};

HTML Replacement

You can also provide HTML to be injected into the template as well. The key point is that those values need to be marked with three curly braces. For example, if you want to replace the recipient name with HTML, you would use:

Hello, {{{recipientName}}}

And the object we provide would look like this:

var dynamicEmailData = new
{
    recipientName = "<b><i>Demo User</i></b>",
};

The output now looks like this:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 21

!!!warning Keep in mind that whenever you are using three curly braces, the variable will not be encoded and susceptible to HTML injection. If this variable holds user input, this can be risky! Make sure to use the HtmlEncoder in .NET to encode user input before passing it into the three curly braces. !!!

Iterations

Working with arrays happens quite often when creating templated emails. Handlebars has support for handling lists and iterating over them using the each keyword. For example, in the upcoming sample, you will list a number of to-do list items. This can be achieved by the code snippet below:

<table>
  <tr>
    <th>Title</th>
    <th>Due Date</th>
    <th>Status</th>
  </tr>
  {{#each todoItemList}}
    <tr>
      <td>{{this.Title}}</td>
      <td>{{this.DueDate}}</td>
      <td>{{this.Status}}</td>
    </tr>
  {{/each}}  
</table>

The items in the array can be addressed by using this keyword, as shown above.

Conditionals

Handlebars Templating Language also has the ability to apply some basic logic using and/or operators, if/else statements, comparison (less than/greater than/equals) and length operator to get the number of characters in a string or the number of items in an array.

Empty strings and zero numbers evaluate to false. For example, the code snippet below shows the username if the variable is a non-empty string:

{{#if this.username}}
  <h1>Hello {{username}}</h1>
{{/if}}

You can also check against the number of array lengths. In the example below, the “You have unread messages in your mailbox!” message will only be shown if the unreadMessages array has elements in it.

{{#greaterThan (length unreadMessages) 0}}
  <p>You have unread messages in your mailbox!</p>
{{else}}
    <p>No unread messages.</p>
{{/greaterThan}}

With the following data, it displays the message:

{
  "unreadMessages": [ "Message 1", "Message 2" ]
}

But in the case of an empty array, it shows “No unread messages.”.

More Handlebars

In addition to the features covered above, you can use conditionals and some basic logic to implement more complicated templates. You can find out more about using Handlebars with Twilio SendGrid here.

Send Email Using Dynamic Email Templates

Set Up Dynamic Email Template

First, go to SendGrid Email templates page.

Then, expand your dynamic template and click on the active version:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 22

Update the subject field with {{subject}} as you’re going to replace it with dynamic data.

Remove all the elements in the design area. Your design should look like this:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 23

On the left pane, click Build. Drag and drop a Text object into the design area. Replace the placeholder text with

Hello, {{recipientName}}
Here's your to-do list:

In this example, I set the line height to 40. You can play around with text properties to your liking.

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 24

Click on anywhere in the design area outside the Text element to see the available elements on the left pane again.

Click Code and drag it under the text element. This automatically opens the HTML editor. Paste the following code in the editor:

<table>
  <tr>
    <th>Title</th>
    <th>Due Date</th>
    <th>Status</th>
  </tr>
  {{#each todoItemList}}
    <tr>
      <td>{{this.title}}</td>
      <td>{{this.dueDate}}</td>
      <td>{{this.status}}</td>
    </tr>
  {{/each}}  
</table>

Click Update. Your final version of the template should look like this:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 25

Set Up C# Application

Open the Program.cs file in the ConsoleMailer project you created previously, and replace the previous email sending code with the highlighted Dynamic Email Template code:

csharp hl_lines="9 10 11 12 13 14 15 16 17 18 19 20 21 22" using SendGrid; using SendGrid.Helpers.Mail; var apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY"); var client = new SendGridClient(apiKey); var from = new EmailAddress("{ Your verified email address }", "{ Sender display name }"); var to = new EmailAddress("{ Recipient email address }", "{ Recipient display name }"); var templateId = "{ Your dynamic template id }"; var dynamicTemplateData = new { subject = $"To-Do List for {DateTime.UtcNow:MMMM}", recipientName = "Demo User", todoItemList = new[] { new { title = "Organize invoices", dueDate = "11 June 2022", status = "Completed" }, new { title = "Prepare taxes", dueDate = "12 June 2022", status = "In progress" }, new { title = "Submit taxes", dueDate = "25 June 2022", status = "Pending" }, } }; var msg = MailHelper.CreateSingleTemplateEmail(from, to, templateId, dynamicTemplateData); var response = await client.SendEmailAsync(msg); if (response.IsSuccessStatusCode) { Console.WriteLine("Email has been sent successfully"); }

!!!info

Make sure the name and casing of the variables in your template match the dynamic template data you’re passing in. For example, if your subject variable is {{subject}} and your C# data has a property named Subject, the subject of your email will be empty.

!!!

This code is similar to the previous code with a few differences:

  • You call the CreateSingleTemplateEmail method instead of the CreateSingleEmail method

  • You provide the data displayed in the final email output, but you don’t render the HTML yourself.

Also, you must provide the unique template ID. You can obtain the ID from the Dynamic Templates page. Expand the details of your template and the Template ID should appear at the top:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 26

Once you’ve obtained the template ID, replace { Your dynamic template id } with it in your code.

The template ID is shared among all versions, so you don’t have to change your configuration when you create a new version. However, you have to ensure to choose the correct version as active. To make a version active, click on the vertical three dots on the right and click Make Active.

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 27

The final email looks like this:

Send Emails with C#, Handlebars Templating, and Dynamic Email Templates - image 28

You can see how the todoItemList array is used to render the to-do item list table in a dynamic fashion.

Conclusion

In this post, you looked into the basics of setting up your SendGrid account and the SendGrid .NET library. Then you learned how to use Dynamic Email Templates and how you can use Handlebar templating to create dynamic emails. You can find the source code for the applications in this tutorial on GitHub.

Twilio SendGrid offers a lot more than covered in this article. I’d recommend visiting the official documentation and discovering more features based on your use cases. Here are a couple of articles about sending emails and templating that could help you get the most out of SendGrid and .NET:

]]> <![CDATA[How to create an RSS Podcast Feed from local files with C#]]> 2025-10-12T11:30:00+00:00 https://volkanpaksoy.com/archive/2025/10/12/How-to-create-an-RSS-Podcast-Feed-from-local-files-with-C# I have a few old podcast series that are not available online anymore. Every now and then, I enjoy listening to an old episode. I keep them in a hard drive connected to a Raspberry Pi, which serves them over the local network. Then I connect to this share on my mobile device and consume the content. It works fine most of the time. The problem is it’s hard to remember the last episode I listened to since everything is treated as files with no history. I thought I could leverage my podcast app on my phone if I served these files via an RSS feed. This tutorial will show how to generate the RSS feed using C# and serve the content over your local network. If this sounds like a problem you would like to solve, let’s get started.

Prerequisites

To follow this tutorial, you need the following software installed:

Set up the Web Server

Since you will host only static files (RSS feed which is an XML file and some audio files), an Nginx instance running in a Docker container is sufficient.

First, designate a local directory on your computer to put the files. In the tutorial, I will use the following path: ~/Temp/webroot. Modify this to match your environment.

Run the following command to start your podcast server:

docker run --name podcast-server -p 9876:80 -v ~/Temp/webroot:/usr/share/nginx/html:ro -d nginx

The command above;

  • Maps port 9876 on your machine to the internal port 80 in the container. (-p 9876:80)

  • Runs the container in the background as a daemon (-d)

  • Mounts the ~/Temp/webroot directory on your machine to the /usr/share/nginx/html directory on the container. This means when Nginx serves content in its HTML directory, it looks into the ~/Temp/webroot directory. This way, you can manage the content without going into the container’s file system.

If you open a browser tab and go to http://localhost:9876, you should get a 403 Forbidden response from the web server. This is expected because you haven’t put any files to serve yet.

Set up Content

To test the application, let’s start with a small amount of content. Go to file-examples.com and download 2 MP3 files and rename them as “episode1.mp3” and “episode2.mp3”. So the root of your web server should look like this:

Contents of the root directory showing webroot directory, content directory under it and two files named episode1.mp3 and episode2.mp3

Now, if you request one of these files in your browser (e.g. http://localhost:9876/content/episode1.mp3), you should be able to hear the MP3 playing. In the next section, you will implement the application that creates the RSS feed so that you can consume the feed via your podcatcher too.

Implement the RSS Generator

An RSS feed is simply an XML file. It includes the name and description of the show, as well as the titles and URLs of the individual episodes. If this feed were meant to be published publicly, you would add more details such as icons, categories, iTunes-specific tags etc., but for personal consumption, the following format is sufficient:

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0">
  <channel>
    <title>{Show Title}</title>
    <description>{Show Description}</description>
    <category>{Category}</category>
    <item>
      <title>{Episode Title}</title>
      <description>{Episode Description}</description>
      <enclosure url="{Episode URL}" type="audio/mpeg"/>
    </item>
  </channel>
</rss>

Create a new dotnet console application:

dotnet new console --name RssFeedGenerator --output .

Open the project with your IDE.

To serialize to the XML above, you will need a data structure. There are tools that can generate C# classes from a sample XML, so you don’t have to manually create the classes yourself. I generated the following at Xml2Charp. The result looks like this (after a bit of formatting):

/* 
 Licensed under the Apache License, Version 2.0
 
 http://www.apache.org/licenses/LICENSE-2.0
 */

using System.Xml.Serialization;

namespace RssFeedGenerator
{
    [XmlRoot(ElementName="enclosure")]
    public class Enclosure
    {
        [XmlAttribute(AttributeName="url")]
        public string Url { get; set; }
        [XmlAttribute(AttributeName="type")]
        public string Type { get; set; }
    }

    [XmlRoot(ElementName="item")]
    public class Item
    {
        [XmlElement(ElementName="title")]
        public string Title { get; set; }
        [XmlElement(ElementName="description")]
        public string Description { get; set; }
        [XmlElement(ElementName="enclosure")]
        public Enclosure Enclosure { get; set; }
    }

    [XmlRoot(ElementName="channel")]
    public class Channel
    {
        [XmlElement(ElementName="title")]
        public string Title { get; set; }
        [XmlElement(ElementName="description")]
        public string Description { get; set; }
        [XmlElement(ElementName="category")]
        public string Category { get; set; }
        [XmlElement(ElementName="item")]
        public List<Item> Item { get; set; }
    }

    [XmlRoot(ElementName="rss")]
    public class Rss
    {
        [XmlElement(ElementName="channel")]
        public Channel Channel { get; set; }
        [XmlAttribute(AttributeName="version")]
        public string Version { get; set; }
    }
}

Create a file called Rss.cs in your project and paste the above code. The biggest change I made to the auto-generated version is to replace the single Item property in the Channel class with a **List**, as you will need multiple entries per podcast.

Now, update Program.cs with the code below:

using System.Xml.Serialization;
using RssFeedGenerator;

string serverIPAddress = "192.168.1.20";
int serverPort = 9876;
var contentFullPath = "/Temp/webroot/content";
var feedFullPath = "/Temp/webroot/feed.rss";
var audioRootUrl = $"http://{serverIPAddress}:{serverPort}";

var rss = new Rss
{
    Version = "2.0",
    Channel = new Channel
    {
        Title = "[Local] Test Podcast",
        Description = "Testing generating RSS feed from local MP3 files",
        Category = "test",
        Item = new List<Item>()
    }
};

var allMp3s = new DirectoryInfo(contentFullPath)
    .GetFiles("*.mp3", SearchOption.AllDirectories)
    .OrderBy(x => x.Name);

foreach (var mp3 in allMp3s)
{
    rss.Channel.Item.Add(new Item
    {
        Description = mp3.Name,
        Title = mp3.Name,
        Enclosure = new Enclosure
        {
            Url = $"{audioRootUrl}/{mp3.Directory.Name}/{mp3.Name}",
            Type = "audio/mpeg"
        }
    });
}

var serializer = new XmlSerializer(typeof(Rss));
using (var writer = new StreamWriter(feedFullPath))
{
    serializer.Serialize(writer, rss);
}

Make sure to update the settings at the top of the file before you run the application.

Run the application by running the following command in the terminal:

dotnet run

Under your web server’s root directory, you should see the feed.rss file that looks like this:

<?xml version="1.0" encoding="utf-8"?>
<rss xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" version="2.0">
  <channel>
    <title>[Local] Test Podcast</title>
    <description>Testing generating RSS feed from local MP3 files</description>
    <category>test</category>
    <item>
      <title>episode1.mp3</title>
      <description>episode1.mp3</description>
      <enclosure url="http://192.168.1.20:9876/content/episode1.mp3" type="audio/mpeg" />
    </item>
    <item>
      <title>episode2.mp3</title>
      <description>episode2.mp3</description>
      <enclosure url="http://192.168.1.20:9876/content/episode2.mp3" type="audio/mpeg" />
    </item>
  </channel>
</rss>

At this point, you have your RSS feed and all your content under your web server. The final step is to consume this content using your podcast app.

Add Your Podcast to your Podcast App

My podcast app of choice is Overcast. I’m very happy with it and have been using it for many years. The following might be a limitation of Overcast, but apparently, it cannot access feeds over the local network. So to tackle this issue, I used NGrok to tunnel web traffic to my local web server.

If you are having the same issue, install ngrok and run the following command:

ngrok http 9876

This should generate a public URL and route traffic to your local server. In my case, it looks like this:

ngrok output showing the traffic is routed to localhost:9876

Now you can access your feed via the {public URL}/feed.rss.

In Overcast, I add the URL by clicking the + button on the top right and then clicking Add URL link.

After it fetches and parses the RSS feed, it should appear in your podcast list.

The only thing that’s left is to open the podcast and play the episodes:

Even though Overcast cannot fetch the RSS feed over the local network, it can still play the episodes locally. You can stop ngrok and continue to play the episodes. The downside of this approach is if this podcast is an active one and you want to refresh the feed, you will need to delete and re-add the feed because the ngrok address will have changed the next time you try to get the updates.

Conclusion

I love hosting my own content in my own network. Even though having some offline podcasts stored locally is not a common use case, I had to implement my solution to solve the issue and decided to make it public and share it in case anyone else would like to use the same approach or build on it and make it better. The final source code can be found in my GitHub repository.

]]> <![CDATA[How to manage Google Sheets with C#]]> 2025-10-11T09:00:00+00:00 https://volkanpaksoy.com/archive/2025/10/11/How-to-manage-Google-Sheets-with-C# Spreadsheets are quite powerful tools. They can also act as a simple database with an intuitive UI. You can use the spreadsheet as a temporary database and GSheets API as a CRUD API while you prototype your own application. This article will teach you how to manage Google Sheets using your C# application.

Prepare your spreadsheet

The sample application will be a simple shopping list manager console application. It will insert/update/delete items in the shopping list and keep a log of each event in another sheet.

You will need a Google Account to follow along. You can sign up for free here if you don’t have one.

While logged in to your Google account, open your Google Drive.

Click the New button on the top left, then click Google Sheets in the menu.

New menu shows available google services such as Google Docs, Google Sheets, Google Slides, Google Forms and a more link at the end

Name your spreadsheet Shopping List.

At the bottom of the screen, right-click on the sheet name (Sheet1) and rename it to Cart.

Set the value of A1 to Item and B1 to Quantity. You can style the cells the way you like.

Spreadsheet showing the title Shopping List, the value of A1 cell as "Item" and the value of B1 cell as "Quantity"

Now that the “database” is ready, move on to the next section to set up the permissions.

Generate Credentials

Go to Google API Console.

Click APIs & Services and Library

Search sheets and click Google Sheets API in the search results.

In the API settings, click the Enable button.

Click the Create Credentials button.

In the credential type, select Application Data.

It will ask if you’re planning to use it with Kubernetes etc. Select “No, I’m not using them”.

Click Next.

In the service account settings, enter shopping-list-service-account as the service account name and click Create and Continue.

Click Continue to proceed.

Click Done to finish the account creation.

Click Credentials and the new service account.

Click Keys and Add Key.

Click Create new key, keep JSON as the selected option and click Create.

A download should automatically start with your credentials. You will need this file later on.

Finally, you need to share your spreadsheet with the new service account. Go to your sheet and click the Share button.

Copy the email address generated for your service account and paste it into the Add people and groups textbox.

Click the Share button and close the dialog.

Now you can proceed to create the application.

Implement the sample application

In a terminal, navigate to the root directory that you want to create the project in and run:

dotnet new console --name ShoppingList --output .

Add the necessary Google Sheets SDK, via NuGet:

dotnet add package Google.Apis.Sheets.v4

Copy the downloaded credentials to the project folder and open the project with your IDE.

To access your spreadsheet fro myour program, you will need the id of the sheet which you can find in the URL:

First things first: Confirm your access to your spreadsheet. To achieve that, replace the code in Program.cs with the following code:

using Google.Apis.Auth.OAuth2;
using Google.Apis.Services;
using Google.Apis.Sheets.v4;

var spreadsheetId = "{ YOUR SPREADSHEET'S ID }";
var range = "Cart!A1:B";

GoogleCredential credential;
using (var stream = new FileStream("credentials.json", FileMode.Open, FileAccess.Read))
{
    credential = GoogleCredential.FromStream(stream).CreateScoped(new string[] { SheetsService.Scope.Spreadsheets });
}

var sheetsService = new SheetsService(new BaseClientService.Initializer()
{
    HttpClientInitializer = credential,
    ApplicationName = "ShoppingList"
});

SpreadsheetsResource.ValuesResource.GetRequest getRequest = sheetsService.Spreadsheets.Values.Get(spreadsheetId, range);
       
var getResponse = await getRequest.ExecuteAsync();
IList<IList<Object>> values = getResponse.Values;
if (values != null && values.Count > 0)
{
    foreach (var row in values)
    {
        Console.WriteLine(row[0]);
        Console.WriteLine(row[1]);
    }
}

Replace { YOUR SPREADSHEET'S ID } with the actual value and run the application. The column titles (Item and Quantity) should be displayed in your terminal.

You can add some items to your shopping list and test again.

Before going further, refactor the code. You will encapsulate all GSheets-related functions in a called GSheetsHelper.cs. Create the file and update the code as below:

using Google.Apis.Auth.OAuth2;
using Google.Apis.Services;
using Google.Apis.Sheets.v4;

namespace ShoppingList;

public class GSheetsHelper
{
    private SheetsService _sheetsService;
    private string _spreadsheetId = "{ YOUR SPREADSHEET'S ID }";
    private string _range = "Cart!A2:B";
    
    public GSheetsHelper()
    {
        GoogleCredential credential;
        using (var stream = new FileStream("credentials.json", FileMode.Open, FileAccess.Read))
        {
            credential = GoogleCredential.FromStream(stream).CreateScoped(SheetsService.Scope.Spreadsheets);
        }

        _sheetsService = new SheetsService(new BaseClientService.Initializer()
        {
            HttpClientInitializer = credential,
            ApplicationName = "ShoppingList"
        });        
    }

    public async Task PrintCartItems()
    {
        SpreadsheetsResource.ValuesResource.GetRequest getRequest = _sheetsService.Spreadsheets.Values.Get(_spreadsheetId, _range);
       
        var getResponse = await getRequest.ExecuteAsync();
        IList<IList<Object>> values = getResponse.Values;
        if (values != null && values.Count > 0)
        {
            Console.WriteLine("Item\t\t\tQuantity");
            
            foreach (var row in values)
            {
                Console.WriteLine($"{row[0]}\t\t\t{row[1]}");
            }
        }
    }
}

Run the application now and you should see your items in your cart printed in your terminal:

Convert the application to a CLI

You now have the functionality to get your cart, but it will do the same thing every time. To add more commands, convert your application into a CLI. First, add the System.CommandLine package to your project:

dotnet add package System.CommandLine --version 2.0.0-beta4.22272.1

If you are interested in developing your own CLIs with C#, make sure to check out these articles as well: Develop your own CLI with C# and How to Develop an Interactive CLI with C# and dotnet 6.0

Create your first command, the same functionality as above, to print the cart items. Replace Program.cs with the following code:

using System.CommandLine;
using ShoppingList;

var rootCommand = new RootCommand("Manage your shopping cart");

var printCartCommand = new Command("print", "Print the items in the cart");
printCartCommand.SetHandler(async () =>
{
    var gsheetsHelper = new GSheetsHelper();
    try
    {
        await gsheetsHelper.PrintCartItems();
    }
    catch (Exception e)
    {
        Console.Error.WriteLine(e.Message);
    }
});
rootCommand.AddCommand(printCartCommand);

return rootCommand.InvokeAsync(args).Result;

Run the application with dotnet run command and you should now see an info message explaining the supported commands:

You now have to specify the command name to print the items. Run it as dotnet run print to pass the command name and you should see the contents of your cart again.

Add Items yo your Cart

The program can now be enhanced simply by adding more commands.

Add the following function to GSheetsHelper.cs:

public async Task AddItem(string itemName, decimal quantity)
{
    var valuesToInsert = new List<object>
    {
        itemName,
        quantity
    };

    SpreadsheetsResource.ValuesResource.AppendRequest.ValueInputOptionEnum valueInputOption = SpreadsheetsResource.ValuesResource.AppendRequest.ValueInputOptionEnum.RAW;
    SpreadsheetsResource.ValuesResource.AppendRequest.InsertDataOptionEnum insertDataOption = SpreadsheetsResource.ValuesResource.AppendRequest.InsertDataOptionEnum.INSERTROWS;

    var requestBody = new ValueRange();
    requestBody.Values = new List<IList<object>>();
    requestBody.Values.Add(valuesToInsert);

    SpreadsheetsResource.ValuesResource.AppendRequest appendRequest = _sheetsService.Spreadsheets.Values.Append(requestBody, _spreadsheetId, _range);
    appendRequest.ValueInputOption = valueInputOption;
    appendRequest.InsertDataOption = insertDataOption;
    
    await appendRequest.ExecuteAsync();
}

To invoke this method, add the command to Program.cs:

var itemNameOption = new Option<string>(
    new[] {"--item-name", "-n"},
    description: "The name of the item"
);
itemNameOption.IsRequired = true;

var quantityOption = new Option<decimal>(
    new[] {"--quantity", "-q"},
    description: "The quantity of the item"
);
quantityOption.IsRequired = true;

var addItemCommand = new Command("add", "Add an item to the cart")
{
    itemNameOption,
    quantityOption
};
addItemCommand.SetHandler(async (itemName, quantity) =>
{
    var gsheetsHelper = new GSheetsHelper();
    try
    {
        await gsheetsHelper.AddItem(itemName, quantity);
    }
    catch (Exception e)
    {
        Console.Error.WriteLine(e.Message);
    }
}, itemNameOption, quantityOption);
rootCommand.AddCommand(addItemCommand);

Run the command with some item like this:

dotnet run add --item-name Steaks --quantity 2

You should see the new item in your cart:

Remove Items From Your Cart

To have remove functionality, add the following method to GSheetsHelper:

public async Task RemoveItem(string itemName)
{
    SpreadsheetsResource.ValuesResource.GetRequest getRequest = _sheetsService.Spreadsheets.Values.Get(_spreadsheetId, _range);
    
    var getResponse = await getRequest.ExecuteAsync();
    IList<IList<Object>> values = getResponse.Values;
    if (values != null && values.Count > 0)
    {
        for (int i = 0; i < values.Count; i++)
        {
            if (values[i][0].ToString() == itemName)
            {
                var request = new Request
                {
                    DeleteDimension = new DeleteDimensionRequest
                    {
                        Range = new DimensionRange
                        {
                            SheetId = 0,
                            Dimension = "ROWS",
                            StartIndex = i + 1,
                            EndIndex = i + 2
                        }
                    }
                };
                
                var deleteRequest = new BatchUpdateSpreadsheetRequest {Requests = new List<Request> {request}};
                var batchUpdateRequest = new SpreadsheetsResource.BatchUpdateRequest(_sheetsService, deleteRequest, _spreadsheetId);
                await batchUpdateRequest.ExecuteAsync();
            }
        }
    }
}

Similar to add command, define it in Program.cs by adding the following code block:

var removeItemCommand = new Command("remove", "Remove an item from the cart")
{
    itemNameOption
};
removeItemCommand.SetHandler(async (itemName) =>
{
    var gsheetsHelper = new GSheetsHelper();
    try
    {
        await gsheetsHelper.RemoveItem(itemName);
    }
    catch (Exception e)
    {
        Console.Error.WriteLine(e.Message);
    }
}, itemNameOption);
rootCommand.AddCommand(removeItemCommand);

Run the application as dotnet run remove -n Milk, and you should see the item removed from your cart.

Conclusion

This article covered the basics of setting up a new Google Sheets spreadsheet, creating API credentials and granting access to the sheet. It also showed how to develop a basic CLI to list, add and remove items from the spreadsheet. You can get the final version of the application from my GitHub repo.

Even though it’s a simple project, I hope it helped you learn the basics of managing a Google Sheets spreadsheet.

]]> <![CDATA[Scheduled MagPi Magazine Tracker with C#]]> 2025-10-10T10:00:00+00:00 https://volkanpaksoy.com/archive/2025/10/10/Scheduled-MagPi-Magazine-Tracker-with-C# There is a slightly different version of this article published recently on Twilio Blog: Get notified of new magazine issues using web scraping and SMS with C# .NET. That version uses a worker service rather than a scheduled console application and uses SMS as the notification channel. The article you’re about to read has the extra step of importing the PDFs into Calibre. If you’re interested in the topic, I recommend checking out both versions.

As a Raspberry PI fan, I like to read The MagPi Magazine, which is freely available as PDFs. The problem is I tend to forget to download it manually every month, so I decided to automate the process. I use Calibre as my ebook management software (I blogged about my setup here).

The MagPi Magazine Tracker Architecture and Workflow

I wanted this project to periodically check the latest issue, download it when it’s available and import it into Calibre and send me a notification email so that I can connect to my ebook library and check out the issue. So here’s the architecture to achieve this goal:

The MagPi Magazine Tracker Architecture and Workflow diagram

Here’s the workflow:

  1. The application is triggered based on a schedule. Since MagPi is a monthly magazine, it should be fine to run it every week.
  2. The application fetches the MagPi page and parses the HTML to find out the latest issue.
  3. It then checks its database (a flat file or a JSON would suffice for this project).
  4. If it’s a new issue, it then downloads the PDF to the local file system.
  5. It imports the PDF into Calibre using Calibre’s CLI.
  6. It sends a notification telling the user that a new issue is available.
  7. The user (which is me!) connects to calibre-web (the web frontend I used to view my Calibre libraries) and reads the magazine.

Prerequisites

The full source code is freely available on my GitHub repo if you’re just interested in getting a copy of the application and playing around with it. If you’re new to GitHub, you might want to have a look at this article: How to clone a GitHub repository.

To follow along and implement the project, you will need the following:

  • Calibre
  • A Twilio SendGrid account (with an API key and sender address set up. The beginning of this article may be useful to set up your account)

Implementation

For a scheduled task, you generally have two options:

  • External scheduler: This is generally part of the operating system (such as Task Scheduler for Windows and Crontab for macOS/Linux)
  • Internal scheduler: Run the main application in an infinite loop with sleeping the amount of time you want to wait for the next run.

I think an internal scheduler works better if your application needs to run quite often, like every hour or so. Using an external scheduler makes more sense to me for longer cycles, like running an application once a week, such as this project. Therefore, I’m going to implement it using a Console Application and schedule it using Crontab. If you are on Windows, you can take a look at this article or search for scheduling tasks on Windows.

To create a Console Application, run the following commands at the root level of your project:

mkdir MagPiTracker
cd MagPiTracker
dotnet new console

Persistence

Let’s start with the persistence layer. All you need to read/write is the latest issue you saved in your Calibre library, so create a folder called Persistence and add an interface named IMagPiRepository.cs that looks like this:

namespace MagPiTracker.Persistence;

public interface IMagPiRepository
{
    Task<int> GetLastSavedIssueNumber();
    Task SaveLastSavedIssueNumber(int newIssueNumber);
}

The actual implementation is going to be a simple JSON reader/writer for this project. You can choose to implement a SQLite database or a simple txt file. For JSON, add the Newtonsoft.Json package to your project by running:

dotnet add package NewtonSoft.Json

Then, create a file called db.json and set the initial value to 0:

{
  "lastSavedIssueNumber": 0
}

Also, make sure that it is going to be copied to the output directory. Right-click on properties and set Copy to output directory to Copy always. I prefer Copy always to Copy if newer because it’s more straightforward and predictable.

Create a new file named JsonMagPiRepository.cs under the Persistence folder. Update the code as below:

using Newtonsoft.Json.Linq;

namespace MagPiTracker.Persistence;

public class JsonMagPiRepository : IMagPiRepository
{
    private const string DB_PATH = "./persistence/db.json";

    public async Task<int> GetLastSavedIssueNumber()
    {
        var rawContents = await File.ReadAllTextAsync(DB_PATH);
        return JObject.Parse(rawContents).GetValue("lastSavedIssueNumber").Value<int>();
    }

    public async Task SaveLastSavedIssueNumber(int newIssueNumber)
    {
        var newValue = new { lastSavedIssueNumber = newIssueNumber };
        await File.WriteAllTextAsync(DB_PATH, Newtonsoft.Json.JsonConvert.SerializeObject(newValue));
    }
}

To test the data layer, update Program.cs with the following code:

using MagPiTracker.Persistence;

Console.WriteLine("Running The MagPi Tracker...");

var repository = new JsonMagPiRepository();
var lastSavedIssueNumber = await repository.GetLastSavedIssueNumber();
Console.WriteLine($"Last Saved Issue Number: {lastSavedIssueNumber}");

// Test write and read back
await repository.SaveLastSavedIssueNumber(120);
Console.WriteLine($"[Test] Last Saved Issue Number: {await repository.GetLastSavedIssueNumber()}");

The output should look like this:

Running The MagPi Tracker...
Last Saved Issue Number: 0
Test Last Saved Issue Number: 120

Issue Checker

The next task is to implement the service to check the latest available issue on The MagPi Magazine page. What we need to get out of this service is:

  • The latest issue number
  • The link to the PDF
  • The link to the cover image (to make the notification email prettier)

So create an interface called IMagPiService.cs that looks like this:

namespace MagPiTracker.MagPi;

public interface IMagPiService
{
    Task<int> GetLatestIssueNumber();
    Task<string> GetIssuePdfUrl(int issueNumber);
    Task<string> GetLatestIssueCoverUrl();
}

Create a class called MagPiService that implements the interface, and that looks like this initially:

namespace MagPiTracker.MagPi;

public class MagPiService : IMagPiService
{
    public async Task<int> GetLatestIssueNumber()
    {
        throw new NotImplementedException();
    }

    public async Task<string> GetIssuePdfUrl(int issueNumber)
    {
        throw new NotImplementedException();
    }

    public async Task<string> GetLatestIssueCoverUrl()
    {
        throw new NotImplementedException();
    }
}

Now, let’s focus on getting the latest issue number. The easiest way to find the latest issue number is by going to the issues page, which looks like this at the time of this writing:

The MagPI Magazine issues page showing the latest issue

We’re going to utilize some web scraping to get the job done. In this project, I used a library called AngleSharp to achieve this. Run the following command to add it to your project:

dotnet add package AngleSharp

Then, update your GetLatestIssueNumber implementation as shown below:

using AngleSharp;

namespace MagPiTracker.MagPi;

public class MagPiService : IMagPiService
{
    private const string MAGPI_ROOT_URL = "https://magpi.raspberrypi.com";
    
    public async Task<int> GetLatestIssueNumber()
    {
        var config = AngleSharp.Configuration.Default.WithDefaultLoader();
        var context = BrowsingContext.New(config);
        var document = await context.OpenAsync($"{MAGPI_ROOT_URL}/issues/");
        var latestCoverLinkSelector = ".c-latest-issue > .c-latest-issue__cover > a";
        var latestCoverLink = document.QuerySelector(latestCoverLinkSelector);
        var rawLink = latestCoverLink.Attributes.GetNamedItem("href").Value;
        return int.Parse(rawLink.Substring(rawLink.LastIndexOf('/') + 1));
    }

    public async Task<string> GetIssuePdfUrl(int issueNumber)
    {
        throw new NotImplementedException();
    }

    public async Task<string> GetLatestIssueCoverUrl()
    {
        throw new NotImplementedException();
    }
}

To put this to the test, update your Program.cs as below and run the application:

using MagPiTracker.MagPi;
using MagPiTracker.Persistence;

Console.WriteLine("Running The MagPi Tracker...");

var repository = new JsonMagPiRepository();
var magpiService = new MagPiService();

var lastSavedIssueNumber = await repository.GetLastSavedIssueNumber();
Console.WriteLine($"Last Saved Issue Number: {lastSavedIssueNumber}");

var latestIssueNumber = await magpiService.GetLatestIssueNumber();
Console.WriteLine($"Latest Issue Number: {latestIssueNumber}");

You should see an output similar to this:

Running The MagPi Tracker...
Last Saved Issue Number: 120
Latest Issue Number: 121

Your latest issue will probably be different depending on when you are running it.

Download the PDF

The next challenge is to find the direct link to the PDF. If you click the Download Free PDF link, the page does not start the download automatically. Instead, you land on a donation page that looks like this:

The MagPi Magazine donation page

I’d strongly recommend everybody to consider donating. This is a great magazine with professional quality, and it’s full of valuable knowledge about everything Raspberry Pi.

Since they are allowing free downloads and Raspberry Pi is mostly a favourite among maker-community, I’m hoping they wouldn’t mind this little project.

If you click on the “No thanks, take me to the free PDF” link, the PDF download starts automatically. This is actually done by a redirect that contains an iframe with the src property set to the URL of the PDF. So to download the PDF, you need to parse the URL.

Create a new project directory called Downloader and add a new interface named IDownloadService.cs that looks like this:

namespace MagPiTracker.Downloader;

public interface IDownloadService
{
    Task DownloadFile(string url, string localPath);
}

As you can tell from the method name and its arguments, this service is going to download the file at the given URL and save it to the local file system.

For the actual implementation, create a class called DownloadService implementing the interface and update the code with this:

namespace MagPiTracker.Downloader;

public class DownloadService : IDownloadService
{
    public async Task DownloadFile(string url, string localPath)
    {
        using HttpClient client = new HttpClient(); // use HttpClient factory in production
        using HttpResponseMessage response = await client.GetAsync(url);
        using Stream downloadedFileStream = await response.Content.ReadAsStreamAsync();
        
        using (var localFileStream = new FileStream(localPath, FileMode.Create, FileAccess.Write))
        {
            await downloadedFileStream.CopyToAsync(localFileStream);
        }
    }
}

To test these changes, update the Program.cs file with the following code:

using MagPiTracker.Downloader;
using MagPiTracker.MagPi;
using MagPiTracker.Persistence;

Console.WriteLine("Running The MagPi Tracker...");

var repository = new JsonMagPiRepository();
var magpiService = new MagPiService();
var downloadService = new DownloadService();

var lastSavedIssueNumber = await repository.GetLastSavedIssueNumber();
Console.WriteLine($"Last Saved Issue Number: {lastSavedIssueNumber}");

var latestIssueNumber = await magpiService.GetLatestIssueNumber();
Console.WriteLine($"Latest Issue Number: {latestIssueNumber}");

if (latestIssueNumber > lastSavedIssueNumber)
{
    var pdfUrl = await magpiService.GetIssuePdfUrl(latestIssueNumber);
    var localPath = $"TheMagPiMagazine_{latestIssueNumber.ToString().PadLeft(3, '0')}.pdf";
    await downloadService.DownloadFile(pdfUrl, localPath);
    Console.WriteLine($"Latest Issue PDF has been saved to {localPath}");
}
else
{
    Console.WriteLine($"No new issue found. Exiting.");
}

The final version of the application checks its database and compares it to the latest issue. If the latest one is newer, then it downloads the PDF. Run the application, and you should see the new PDF downloaded to your local machine. Your output should look like this:

Running The MagPi Tracker...
Last Saved Issue Number: 120
Latest Issue Number: 121
Latest Issue PDF has been saved to TheMagPiMagazine_121.pdf

Importing to Calibre

The next step is to import this file into Calibre. An easy way to wrap external CLIs is the CliWrap library. Add it to your project via NuGet by running the command below:

dotnet add package CliWrap

Create a new folder called Calibre and a new interface called ICalibreService.cs under it.

Update the interface with this code:

namespace MagPiTracker.Calibre;

public interface ICalibreService
{
    Task ImportMagPiMagazine(int issueNumber, string pdfPath);
}

This method is going to be tailored for The MagPi Magazine. The MagPi-related information can be stripped out of the method and put somewhere else, like a config file, but since I’m not aiming to make this a generic downloader, for the time being, it should do the job.

Create the implementation class named CalibreService and implement the interface like this:

using System.Text;
using CliWrap;

namespace MagPiTracker.Calibre;

public class CalibreService : ICalibreService
{
    private const string LIBRARY_PATH = "{PATH TO YOUR CALIBRE LIBRARY}";
    
    public async Task ImportMagPiMagazine(int issueNumber, string pdfPath)
    {
        var issueTitle = $"The MagPi Issue {issueNumber.ToString().PadLeft(3, '0')}";
        var authors = "Raspberry Pi Press";
        var series = "The MagPi Magazine";
        
        var stdOutBuffer = new StringBuilder();
        var stdErrBuffer = new StringBuilder();
        
        await Cli.Wrap("/Applications/calibre.app/Contents/MacOS/calibredb")
            .WithArguments($"add --title \"{issueTitle}\" --with-library \"{LIBRARY_PATH}\" --authors \"{authors}\" --series \"{series}\" \"{pdfPath}\"")
            .WithStandardOutputPipe(PipeTarget.ToStringBuilder(stdOutBuffer))
            .WithStandardErrorPipe(PipeTarget.ToStringBuilder(stdErrBuffer))
            .ExecuteAsync();
        
        var stdOut = stdOutBuffer.ToString();
        var stdErr = stdErrBuffer.ToString();
        
        Console.WriteLine(stdOut);
        Console.WriteLine(stdErr);
    }
}

Make sure to update LIBRARY_PATH. Also, update the application path depending on your operating system.

Then, update the Program.cs like this:

using MagPiTracker.Calibre;
using MagPiTracker.Downloader;
using MagPiTracker.MagPi;
using MagPiTracker.Notifications;
using MagPiTracker.Persistence;

Console.WriteLine("Running The MagPi Tracker...");

var repository = new JsonMagPiRepository();
var magpiService = new MagPiService();

var lastSavedIssueNumber = await repository.GetLastSavedIssueNumber();
Console.WriteLine($"Last Saved Issue Number: {lastSavedIssueNumber}");

var latestIssueNumber = await magpiService.GetLatestIssueNumber();
Console.WriteLine($"Latest Issue Number: {latestIssueNumber}");

if (latestIssueNumber > lastSavedIssueNumber)
{
    var pdfUrl = await magpiService.GetIssuePdfUrl(latestIssueNumber);
    var localPath = $"TheMagPiMagazine_{latestIssueNumber.ToString().PadLeft(3, '0')}.pdf";
 
    var downloadService = new DownloadService();
    await downloadService.DownloadFile(pdfUrl, localPath);
    Console.WriteLine($"Latest Issue PDF has been saved to {localPath}");
    
    var calibreService = new CalibreService();
    await calibreService.ImportMagPiMagazine(latestIssueNumber, new FileInfo(localPath).FullName);
    Console.WriteLine($"Latest Issue has been imported into Calibre");
}
else
{
    Console.WriteLine($"No new issue found. Exiting.");
}

Run the application, and you should see an output like this:

Running The MagPi Tracker...
Last Saved Issue Number: 120
Latest Issue Number: 121
Latest Issue PDF has been saved to TheMagPiMagazine_121.pdf
    /Users/.../scheduled-magpi-magazine-tracker/src/TheMagPiMagazine_121.pdf

The following books were not added as they already exist in the database (see --duplicates option or --automerge option):
  The MagPi Issue 121

Latest Issue has been imported into Calibre

You can go ahead and open your Calibre application, and you should see the newly imported issue in your library:

The latest MagPi issue shown in Calibre

Cover Image URL

In the previous section, we left out implementing the third method. This is not strictly necessary, but having the cover image would make your notification email look nicer. Also, from a practical point of view, if you’re not interested in the topics covered in that issue, you may delay looking at that issue.

To get the cover URL, revisit MagPiService class and update the GetLatestIssueCoverUrl method’s implementation as below:

public async Task<string> GetLatestIssueCoverUrl()
{
    var config = AngleSharp.Configuration.Default.WithDefaultLoader();
    var context = BrowsingContext.New(config);
    var document = await context.OpenAsync($"{MAGPI_ROOT_URL}/issues/");
    var latestCoverImageSelector = ".c-latest-issue > .c-latest-issue__cover > a > img";
    var latestCoverImage = document.QuerySelector(latestCoverImageSelector);
    var latestCoverImageUrl = latestCoverImage.Attributes.GetNamedItem("src").Value;
    
    return latestCoverImageUrl;
}

This will come in handy in the next section.

Notifications

It would be nice to know when a new issue is imported into your library, so the next step is to add a notification mechanism to the application. In this example, I will use email notifications as that’s the cheapest and simplest method. I will use SendGrid as my SMTP provider.

To store the API key, initialize dotnet user-secrets and create a new secret by running the following commands:

dotnet user-secrets init
dotnet user-secrets set SendGrid:ApiKey {YOUR API KEY}

In the project, create a new project directory called Notifications and a new interface called INewIssueNotificationService.cs with the following code:

namespace MagPiTracker.Notifications;

public interface INewIssueNotificationService
{
    Task SendNewIssueNotification(int issueNumber, string coverUrl);
}

Before implementing the class, add SendGrid SDK by running:

dotnet add package SendGrid

Now add a new class called EmailNotificationService.cs and update its code with this:

using System.Reflection;
using Microsoft.Extensions.Configuration;
using SendGrid;
using SendGrid.Helpers.Mail;

namespace MagPiTracker.Notifications;

public class EmailNotificationService : INewIssueNotificationService
{
    public async Task SendNewIssueNotification(int issueNumber, string coverUrl)
    {
        IConfiguration config = new ConfigurationBuilder()
            .AddUserSecrets(Assembly.GetExecutingAssembly(), optional: true, reloadOnChange: false)
            .Build();
        
        var sendGridClient = new SendGridClient(apiKey: config["SendGrid:ApiKey"]);

        var from = new EmailAddress("{YOUR VERIFIED SENDER EMAIL ADDRESS}", "The MagPi Magazine Issue Checker");
        var to = new EmailAddress("{YOUR RECIPIENT EMAIL ADDRESS}", "{YOUR DISPLAY NAME}");

        var htmlContent = await File.ReadAllTextAsync("./notifications/email-template.html");
        var htmlWithData = htmlContent.Replace("%{COVER_URL}", coverUrl);
        
        var msg = MailHelper.CreateSingleEmail(from, to, "The MagPi Magazine New Issue", htmlWithData, htmlWithData);
        await sendGridClient.SendEmailAsync(msg);
    }
}

This code reads the API key from user secrets so that it’s never accidentally pushed to source control. Also, it reads the email template from an HTML file. Create a new file named email-template.html, and set it to be copied to the output always (as you did with db.json) and update its contents as shown below:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
</head>
<body>
<h1>New MagPi Magazine is out!</h1>
<p>
    <img src="%{COVER_URL}" />
</p>
</body>
</html>

There are better ways for variable replacement (using a templating engine such as Handlebars, Razor etc.), but to keep things simple, I just put a placeholder and replaced the string. Update the Program.cs to reflect the latest changes and test:

using MagPiTracker.Calibre;
using MagPiTracker.Downloader;
using MagPiTracker.MagPi;
using MagPiTracker.Notifications;
using MagPiTracker.Persistence;

Console.WriteLine("Running The MagPi Tracker...");

var repository = new JsonMagPiRepository();
var magpiService = new MagPiService();

var lastSavedIssueNumber = await repository.GetLastSavedIssueNumber();
Console.WriteLine($"Last Saved Issue Number: {lastSavedIssueNumber}");

var latestIssueNumber = await magpiService.GetLatestIssueNumber();
Console.WriteLine($"Latest Issue Number: {latestIssueNumber}");

if (latestIssueNumber > lastSavedIssueNumber)
{
    var pdfUrl = await magpiService.GetIssuePdfUrl(latestIssueNumber);
    var localPath = $"TheMagPiMagazine_{latestIssueNumber.ToString().PadLeft(3, '0')}.pdf";
 
    var downloadService = new DownloadService();
    await downloadService.DownloadFile(pdfUrl, localPath);
    Console.WriteLine($"Latest Issue PDF has been saved to {localPath}");
    
    var calibreService = new CalibreService();
    await calibreService.ImportMagPiMagazine(latestIssueNumber, new FileInfo(localPath).FullName);
    Console.WriteLine($"Latest Issue has been imported into Calibre");

    var latestIssueCoverUrl = await magpiService.GetLatestIssueCoverUrl();
    var notificationService = new EmailNotificationService();
    await notificationService.SendNewIssueNotification(latestIssueNumber, latestIssueCoverUrl);

    await repository.SaveLastSavedIssueNumber(latestIssueNumber);
    File.Delete(localPath);
}
else
{
    Console.WriteLine($"No new issue found. Exiting.");
}

In addition to the previous tasks, you are now sending the notification email. Once everything is done successfully, the code updates the local JSON file with the latest issue number so that it doesn’t download the same issue over and over again. Also, it deletes the local PDF to keep things nice and tidy.

Run the application, and you should receive a notification that looks like this:

Screenshot of the final notification email showing MagPi cover

You can add more stuff like the link to the PDF, issue number etc., but just to ping myself this much information is enough for me.

Scheduling

Let’s bring this home by scheduling the application so that it does its thing in an automated fashion.

As mentioned before, on Windows, I’d recommend using the built-in Task Scheduler. On macOS/Linux systems, crontab does the job.

Firstly, build your application and place the deployment package wherever you want to run the application. To edit cron jobs, run

crontab -e

I will run the application every Friday at 5 AM and will use this cron expression: 0 5 * * 5

To find where the dotnet executable is located, you can use the which command:

which dotnet

Also, the cron job will be run in a different working directory. To avoid path issues, it’s best to change to our application directory before running it. So the cron job looks like this:

0 5 * * 5 cd /Users/.../Deployment/MagPiTracker && /usr/local/share/dotnet/dotnet MagPiTracker.dll

Crontab uses the following syntax, and you can customize your schedule based on this:

* * * * * command
* - minute (0-59)
* - hour (0-23)
* - day of the month (1-31)
* - month (1-12)
* - day of the week (0-6, 0 is Sunday)

Why No Docker?

Normally I try to run everything in Docker containers. In this project, I chose to run the application on bare metal. The reason for this is to be able to import the PDFs into my Calibre library, which is also running on bare metal. If I were to run this application in Docker, I wouldn’t be able to run Calibre CLI on the host computer. If I didn’t have this constraint, I would have definitely Dockerized the application.

Conclusion

I hope you enjoyed this little project. As a reminder, please consider donating to the Raspberry Pi Press and use their own mechanism, but if you cannot afford it and since the PDFs are already available out there, you can go ahead and use this project and hopefully learn some new technologies along the way.

]]>