Handle an incoming call with .NET and the Sinch SDK

Now that you know how to call yourself using the Voice API, learn how to handle incoming calls. Sinch has a Voice SDK for C# that makes using the Voice API with the .NET framework quick and clean.

What you need to know before you start

Before you can get started, you need the following already set up:

• Set all Voice API configuration settings.
• .NET 6.0 or later SDK and .NET Runtime and a familiarity with how to create an app.
• ngrok and a familiarity with how to start a network tunnel. You can use any method you want to make your server accessible over the internet, but we like ngrok and it's what we'll use in this guide.

Set up your .NET application

Create a new project folder and open a command prompt. Execute the following command to create a new .NET web API application:

dotnet new webapi

This creates a new web API application and project. Now add the Sinch Voice SDK. Run the following command:

dotnet add package Sinch.ServerSdk

The Voice SDK lets you use the Voice API with far fewer lines of code than you'd otherwise need.

Set up your file

In your project folder, open the Program.cs file and paste the provided "Program.cs" code into the file, replacing all the existing content.

using Sinch.ServerSdk;
using Sinch.ServerSdk.Calling.Models;
using Sinch.ServerSdk.Models;

var app = WebApplication.CreateBuilder(args).Build();

app.MapPost("/incoming-call", (CallbackEventModel model) =>
{
    var svamletBuilder = SinchFactory
        .CreateCallbackResponseFactory(Locale.EnUs)
        .CreateIceSvamletBuilder();
    svamletBuilder.Say("Hi, thank you for calling your Sinch number. Congratulations! You just responded to a phone call.").Hangup();
    return svamletBuilder.Build().Model;
});
app.Run("http://localhost:3000");

This code starts your webserver and also contains the logic to respond to incoming callbacks from the Sinch servers.

Start your server

You can start your webserver by running the following command:

dotnet run

Start your ngrok tunnel

At this point you need to start your ngrok tunnel so that the Sinch servers can access the webserver running on your local machine. Run the following command to start your tunnel:

ngrok http 3000

This starts a tunnel to your webserver, which is running on port 3000 of your localhost.

Copy the http ngrok URL and add "/incoming-call" to the end of it. Navigate to your app on your dashboard. Under the Settings section, you'll see a field labeled "Callback URL." Paste your ngrok URL into that field and click Save.

Now your server is listening and your callback URL is configured, so you're almost ready to test everything and make a phone call. But before we do, let's take a closer look at callbacks. If you already know about callbacks, skip right to calling your Sinch phone number.

Understanding callbacks

Callbacks (also known as "webhooks") are the method that the Voice API uses to figure out what you want to do with a call. Basically, a callback is a request that the Sinch servers send to your server whenever something happens (otherwise known as an "event") in the call that requires some input from you. There are a few different types of events, but the two we are concerned about for this guide are the Incoming Call Event and the Disconnected Call Event.

An Incoming Call Event (or ICE) happens whenever someone calls one of your Sinch numbers. In essence, someone dials your number and so Sinch servers reach out to you and say "how do you want me to handle this call?"

Most callback events expect a response, depending on the event. The Incoming Call Event expects to receive back a SVAML object in response. You can read more about SVAML here, but just know that SVAML is a markup language Sinch developed to control calls.

The below diagram demonstrates exactly what's happening:

1. Someone dials your Sinch number from a handset.
2. The Sinch servers create an ICE and send a POST request to your server.
3. Your server listens for the request and sends back a SVAML response to tell the Sinch server how to handle the call.

Because we're using the Voice SDK, the helper libraries do a lot of the heavy lifting for us and we don't have to bother writing out the full SVAML response.

Instead we can use the Sinch Factory and SvamletBuilder to create our response.

var svamletBuilder = SinchFactory
        .CreateCallbackResponseFactory(Locale.EnUs)
        .CreateIceSvamletBuilder();
    svamletBuilder.Say("Hello this is your Sinch number!").Hangup();

These four lines of code create a response specifically to answer Incoming Call Events, play a Say instruction to read out a string of text, and then hang up the call to end it.

And that's it! Now we can test.

Call your Sinch phone number

Look up the free Sinch number assigned to your app and call it using your phone. The call should be picked up by the Sinch servers and you should hear the text from the instruction. Now you know how to handle an incoming call.

Next steps

• API specification