Relay SDK for .NET

Getting Started

The Relay SDK for .NET enables .NET developers to connect and use SignalWire's Relay APIs within their own .NET code. Our Relay SDK allows developers to build or add robust and innovative communication services to their applications.

The Relay SDK for .NET is easy to use and only takes a few minute to setup and get running.

Installation

Install the package for a .NET Core project using NUGET:

dotnet add package signalwire-dotnet

Or you can install the package through Visual Studio's NUGET package manager, simply install the signalwire-dotnet package to your project.

Minimum Requirements

The .NET SDK may be used with .NET Framework 4.6.1 or greater or .NET Core 2.1 or greater.

Using the SDK

The .NET SDK can be used to get up and running with Relay quickly and easily. In order to use the .NET client, you must get your project and token from your SignalWire dashboard.

There are a few ways to get started, depending on your needs: SignalWire.Relay.Consumer, SignalWire.Relay.Task, and SignalWire.Relay.Client.

Relay Consumer

A SignalWire.Relay.Consumer creates a long running process, allowing you to respond to incoming requests and events in realtime. Relay Consumers abstract all the setup of connecting to Relay and automatically dispatches workers to handle requests; so you can concentrate on writing your code without having to worry about multi-threading or blocking, everything just works. Think of Relay Consumers like a background worker system for all your calling and messaging needs.

Relay Consumers can scale easily, simply by running multiple instances of your SignalWire.Relay.Consumer process. Each event will only be delivered to a single consumer, so as your volume increases, just scale up! This process works well whether you are using Docker Swarm, a Procfile on Heroku, your own webserver, and most other environments.

Setting up a new consumer is the easiest way to get up and running.

using SignalWire.Relay;
using SignalWire.Relay.Calling;
using System;
using System.Collections.Generic;

namespace Example
{
    class ExampleConsumer : Consumer
    {
        protected override void Setup()
        {
            Project = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";
            Token = "PTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
            Contexts = new List<string> { "test" };
        }

        protected override void OnIncomingCall(Call call)
        {
            AnswerResult resultAnswer = call.Answer();
            if (!resultAnswer.Successful) return;

            call.PlayTTS("Welcome to SignalWire!");

            call.Hangup();
        }
    }

    class Program
    {
        public static void Main()
        {
            new ExampleConsumer().Run();
        }
    }
}

Learn more about Relay Consumers

Relay Task

A SignalWire.Relay.RelayTask is simple way to send jobs to your SignalWire.Relay.Consumer from a short lived process, like a web framework. Relay Tasks allow you to pass commands down to your Consumers without blocking your short lived request. Think of a Relay Task as a way to queue a job for your background workers to processes asynchronously.

For example, if you wanted to make an outbound call and play a message when your user clicks a button on your web application, since Relay is a realtime protocol and relies on you to tell it what to do in realtime, if you did this within your web application, your web server would block until the call was finished... this may take a long time! Instead, simply create a new Relay Task. This task will be handled by a running Relay Consumer process and your web application can respond back to your user immediately.

RelayTask.Deliver(validHost, validProjectID, validToken, validContext, new JObject {
    ["number_to_call"] = "+1555XXXXXXX",
    ["message_to_play"] = "We have a message for you",
});

Learn more about Relay Tasks

Relay Client

SignalWire.Relay.Client is a lower level object, giving you a basic connection to Relay but that is all. It is best used when you are creating a script only concerned with sending outbound requests or you want complete control over the Relay connection yourself.

Setting up a new client and make an outbound call.

using SignalWire.Relay;
using SignalWire.Relay.Calling;
using System;
using System.Threading.Tasks;

namespace Example
{
    internal class Program
    {
        public static void Main()
        {
            using (Client client = new Client("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "PTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"))
            {
                // Assign callbacks
                client.OnReady += c =>
                {
                    // This callback cannot block, so create a threaded task
                    Task.Run(() =>
                    {
                        DialResult resultDial = client.Calling.DialPhone("+1XXXXXXXXXX", "+1YYYYYYYYYY");

                        if (resultDial.Successful)
                        {
                            // Your call has been answered, use resultDial.Call to access it
                        }
                    });
                };

                // Connect the client
                client.Connect();

                // Prevent exit until a key is pressed
                Console.Write("Press any key to exit...");
                Console.ReadKey(true);
            }
        }
    }
}

Learn more about Relay Clients

Contexts

Relay uses Contexts as a simple way to separate events to specific consumers, allowing you to write consumers for specific types of calls or messages or scale them independently. A Context is simply a named string, that allows you to categorize requests. When creating outbound requests, or configuring phone numbers for inbound requests, you can specify the context; Relay will then deliver that call or event to Consumers that are configured to listen for that context.

For example, you could have a customer support phone number configured to send to Relay with the support context, and a personal number configured with personal context. Relay would deliver these events to any Consumer listening for those contexts. This gives you a lot of control in how messages are delivered to your Consumers, allowing you to write Consumer classes specific to the context, scale them independently, or separate traffic based on your own business rules.