Navbar
Logo icon Name
  • Relay SDK for C#/.Net
  • API Reference
  • Relay SDK for C#/.Net

    Getting Started

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

    The Relay SDK for C#/.Net is easy to use and only takes a few minute to setup and get running.

    Latest Version:

    Source Code: signalwire/signalwire-dotnet

    Support: SignalWire Community Slack Channel

    Note: Most examples throughout this documentation do not include all of the application boilerplate required for a functional application, the examples serve as a reference and reminder to copy what is required.

    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.

    In order to use the .Net client, you must get your host, project, and token from your SignalWire dashboard.

    For more information on finding your access token, visit Relay Access Keys & Tokens

    using SignalWire.Relay;
    
    Client client = new Client("example.signalwire.com",
                               "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
                               "PTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
    

    You can then use the client to assign callbacks before connecting it:

    client.OnReady += (client) => { };
    
    client.Connect();
    

    Once the client is ready you may use it to make requests.

    Configuration Options

    Additional configuration for the client is available through optional named parameters to the constructor. All such parameters have practical defaults and can generally be ignored. See SignalWire.Relay.Client.Constructor for more information.

    Logging

    The dotnet client uses the standardized Microsoft.Extensions.Logging library with dependancy injection to provide flexible logging providers. The library comes with a simple colorized console implementation which can be enabled like this:

    using Blade;
    using Microsoft.Extensions.Logging;
    using SignalWire;
    
    SignalWireLogging.LoggerFactory.AddSimpleConsole(LogLevel.Information);
    

    It is important to note that you must include the using Blade; namespace for the AddSimpleConsole extension method to be available.

    You may inject any logging provider you may want to use, search NUGET for many options.

    There is an additional layer of logging based on the underlying transport system, this can also be controlled with the following:

    using Blade;
    using Microsoft.Extensions.Logging;
    
    BladeLogging.LoggerFactory.AddSimpleConsole(LogLevel.Information);
    

    It is important to note that logging at this level is primarily for internal debugging, and is heavy on output. Use with caution.

    All logging and levels are subject to change and should only be used for human review.

    Using the SDK

    The C#/.Net SDK can be used to get up and running quickly. Below is an example of setting up a connection to Relay and making an outbound call.

    Quick Start Example

    using Blade;
    using Microsoft.Extensions.Logging;
    using SignalWire.Relay;
    using SignalWire.Relay.Calling;
    using System;
    using System.Threading.Tasks;
    
    namespace Example
    {
        internal class Program
        {
            private static ILogger Logger = null;
    
            public static void Main()
            {
                // Add a logging provider
                SignalWireLogging.LoggerFactory.AddSimpleConsole(LogLevel.Information);
    
                // Create a logger for our own use tied to the existing providers
                Logger = SignalWireLogging.CreateLogger<Program>();
    
                // Create and configure the client with the host, project, and token
                using (Client client = new Client("example.signalwire.com",
                                                  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
                                                  "PTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"))
                {
                    // Assign the ready event with a callback
                    client.OnReady += OnReady;
    
                    // Assign the disconnected event with a callback
                    client.OnDisconnected += OnDisconnected;
    
                    // Start the client
                    client.Connect();
    
                    // Prevent exit until a key is pressed
                    Console.ReadKey(true);
                }
            }
    
            private static void OnReady(Client client)
            {
                Logger.LogInformation("Your client is ready!");
    
                // Event callbacks such as OnReady must not block waiting for messages like Begin so we must
                // operate in a new thread, so here we create a new task that executes from the task thread pool
                Task.Run(() => {
                    // Create a new phone call object, this does not begin the call yet
                    PhoneCall call = client.Calling.NewPhoneCall("+15551234567", "+15551237654");
    
                    // Here is the opportunity to assign event callbacks to the new call before anything happens,
                    // so we'll assign a some simple lambdas that log some state change events that are expected
                    call.OnRinging += (a, c, o, p) => Logger.LogInformation("Call is ringing!");
                    call.OnAnswered += (a, c, o, p) => Logger.LogInformation("Call was answered!");
                    call.OnEnded += (a, c, o, p) => Logger.LogInformation("Call has ended!");
    
                    // Begin the call, which will block until a server responds that it has accepted the request
                    // or throw an exception if there is any errors
                    try { call.Begin(); }
                    catch (Exception exc)
                    {
                        Logger.LogError(exc, "Exception from call.Begin()");
                    }
                });
            }
    
            private static void OnDisconnected(Client client)
            {
                // The client has disconnected either due to a shutdown from disposing the client, or some failure
                // at runtime in which case it will attempt to reconnect itself
                Logger.LogInformation("Your client has disconnected!");
            }
        }
    }
    

    API Reference

    SignalWire.Relay.Client

    This is the main client object used to communicate with SignalWire Relay Services.
    Note: This object implements the IDisposable interface and should follow the appropriate considerations.

    Constructor

    There is only one constructor for this object, it uses a combination of fixed required parameters and optional named parameters to configure the client. The client does not begin connecting during construction, which gives the opportunity to assign callbacks for events before connecting the client.

    Parameters

    host string required The host obtained from your SignalWire Dashboard.
    project string required The project obtained from your SignalWire Dashboard.
    token string required The token obtained from your SignalWire Dashboard.
    connectDelay TimeSpan optional How long to wait before trying to reconnect after being disconnected.
    Default: 5 seconds
    connectTimeout TimeSpan optional How long to wait for a connection to establish.
    Default: 5 seconds
    closeTimeout TimeSpan optional How long to wait for a graceful close exchange to occur when disconnecting.
    Default: 5 seconds

    Examples

    Basic Example

    Client client = new Client("example.signalwire.com",
                               "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
                               "PTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
    

    Properties

    Calling SignalWire.Relay.CallingAPI Lazily created instance of a Relay Calling API.

    Methods

    Connect()

    Starts the client allowing event callbacks to be assigned first. This only needs to be called once, the client will automatically attempt to connect if the connection is lost during normal operations.

    Available In:

    Parameters

    None

    Returns

    • void

    Examples

    Basic Example

    client.Connect();
    

    Disconnect()

    Initiates a disconnect of the client temporarily, the client will attempt to connect again after the configured timeout. To stop the client permanently you must dispose of it to shut down the internal thread.

    Available In:

    Parameters

    None

    Returns

    • void

    Examples

    Basic Example

    client.Disconnect();
    

    Events

    OnReady Called when the client has fully connected and authenticated with SignalWire.
    OnDisconnected Called when the client has been disconnected or lost connection for any reason.

    SignalWire.Relay.CallingAPI

    This represents the API interface for the Calling Relay Service. This object is used to make requests related to managing end to end calls.

    Constructor

    The API has only one constructor which takes a SignalWire.Relay.Client which it uses for the transport.

    Parameters

    client SignalWire.Relay.Client required The client to use for transporting requests for this API.

    Examples

    Basic Example

    CallingAPI calling = new CallingAPI(client);
    

    Properties

    Client SignalWire.Relay.Client The relay client used for transporting requests for this API.
    Protocol string The name of the protocol assigned to this relay API.

    Methods

    NewPhoneCall(to, from, timeout)

    Creates a new call using the PSTN phone approach. The call is created, but it is not started allowing for event callbacks to be assigned first.

    Available In:

    Parameters

    to string required The to number in E164 format.
    from string required The from number in E164 format.
    Note: Must be a number owned under the project.
    timeout int optional Timeout in seconds before the call fails after it is started.
    Default: 30 seconds

    Returns

    Examples

    Basic Example

    PhoneCall call = client.Calling.NewPhoneCall("+15551234567", "+15551237654");
    // Assign event callbacks
    call.Begin();
    

    Receive(context)

    Setup the service to receive inbound calls related to a configured context on the SignalWire Dashboard.
    Note: This method is synchronous and depends on receiving messages, as such it must not be called from the same thread as any event callback from the client.

    Available In:

    Parameters

    context string required The context defining which calls will be captured, see the SignalWire Dashboard to configure a context.

    Returns

    • void

    Examples

    Basic Example

    client.Calling.Receive("test");
    

    Basic Example from Event Callback

    using System.Threading.Tasks;
    
    private static void OnReady(Client client)
    {
        // Start a new task in a new thread on the thread pool allowing this callback to return without synchronous blocking,
        // note that tracking your tasks for cancellation or timeout is recommended if they are potentially long running but
        // is beyond the scope of this example
        Task.Run(() =>
        {
            // This would normally synchronously block waiting for the response that could not be received if it was blocking
            // the event callback from returning, however since it is executed inside a new thread the event callback is
            // able to return to processing new messages
            client.Calling.Receive("test");
        });
    }
    

    Events

    OnCallCreated Called any time a call object is created, allows only opportunity for assigning event callbacks in some cases.
    OnCallReceived Called when any requested context informs of a new inbound call.

    SignalWire.Relay.Calling.Call

    This is the abstract base type for managing different types of calls in the calling service.
    Call Types:

    Constructor

    The constructors for this object are protected and available only to the types that inherit it. There are no public details provided for the constructors as they are only used internally.

    Parameters

    Not Available

    Examples

    Not Available

    Properties

    CallID string The real call ID of this call, may be null until assigned.
    State SignalWire.Relay.Calling.CallState The current state of this call.
    Peer SignalWire.Relay.Calling.Call The peer call connected to this call, this is assigned when a Connect succeeds.
    UserData object This object may be assigned by the user to anything they want, it is not used by the client in any way.

    Methods

    Begin()

    This will start a call that was created with one of the call type specific methods available on the calling API object.
    Note: This method is synchronous and depends on receiving messages, as such it must not be called from the same thread as any event callback from the client.

    Available In:

    Parameters

    None

    Returns

    • void

    Examples

    Basic Example

    PhoneCall call = client.Calling.NewPhoneCall("+15551234567", "+15551237654");
    // Assign event callbacks
    call.Begin();
    

    Answer()

    This will answer a call that was received due to requested contexts, typically called from OnCallReceived.
    Note: This method is synchronous and depends on receiving messages, as such it must not be called from the same thread as any event callback from the client.

    Available In:

    Parameters

    None

    Returns

    • void

    Examples

    Basic Example from OnCallReceived

    private static void OnCallReceived(CallingAPI api, Call call, CallEventParams.ReceiveParams receiveParams)
    {
        // Answer is synchronous blocking with a response message so it must be run from another thread
        Task.Run(() =>
        {
            // Assign event callbacks
            call.Answer();
        });
    }
    

    Hangup()

    This will hang up any call that is active.
    Note: This method is synchronous and depends on receiving messages, as such it must not be called from the same thread as any event callback from the client.

    Available In:

    Parameters

    None

    Returns

    • void

    Examples

    Basic Example from OnCallReceived

    private static void OnCallReceived(CallingAPI api, Call call, CallEventParams.ReceiveParams receiveParams)
    {
        // Answer and Hangup are synchronous blocking with a response message so they must be run from another thread
        Task.Run(() =>
        {
            // Assign event callbacks
            call.Answer();
            call.Hangup();
        });
    }
    

    Connect(devices)

    Attempt to connect an existing call to a new outbound call. This method involves complex nested parameters, follow the types for more information.
    You can connect to multiple devices in series, parallel, or any combination of both with creative use of the parameters. Series implies one device at a time, while parallel implies multiple devices at the same time.
    All devices attempted will create new calls that will provide some events, but only the call related to the first device to answer is returned. It is possible that nothing will answer, this is not a failure condition and will return a null value for the connected call.
    Note: This method is synchronous and depends on receiving messages, as such it must not be called from the same thread as any event callback from the client.

    Available In:

    Parameters

    devices List<List<SignalWire.Relay.Calling.CallDevice>> required This is a nested list of lists of devices to be called.
    Note: The outter list represents devices in series, the inner list represents devices in parallel

    Returns

    Examples

    Basic Example

    Call callB = callA.Connect(new List<List<CallDevice>>
    {
        new List<CallDevice>
        {
            new CallDevice
            {
                Type = CallDevice.DeviceType.phone,
                Parameters = new CallDevice.PhoneParams
                {
                    ToNumber = "+15555551111",
                    FromNumber = "+15555550000",
                }
            }
        }
    });
    

    Basic Example in Series

    Call callB = callA.Connect(new List<List<CallDevice>>
    {
        new List<CallDevice>
        {
            new CallDevice
            {
                Type = CallDevice.DeviceType.phone,
                Parameters = new CallDevice.PhoneParams
                {
                    ToNumber = "+15555551111",
                    FromNumber = "+15555550000",
                }
            }
        },
        new List<CallDevice>
        {
            new CallDevice
            {
                Type = CallDevice.DeviceType.phone,
                Parameters = new CallDevice.PhoneParams
                {
                    ToNumber = "+15555552222",
                    FromNumber = "+15555550000",
                }
            }
        }
    });
    

    Basic Example in Parallel

    Call callB = callA.Connect(new List<List<CallDevice>>
    {
        new List<CallDevice>
        {
            new CallDevice
            {
                Type = CallDevice.DeviceType.phone,
                Parameters = new CallDevice.PhoneParams
                {
                    ToNumber = "+15555551111",
                    FromNumber = "+15555550000",
                }
            },
            new CallDevice
            {
                Type = CallDevice.DeviceType.phone,
                Parameters = new CallDevice.PhoneParams
                {
                    ToNumber = "+15555552222",
                    FromNumber = "+15555550000",
                }
            }
        }
    });
    

    Complex Example in Series and Parallel

    Call callB = callA.Connect(new List<List<CallDevice>>
    {
        new List<CallDevice>
        {
            new CallDevice
            {
                Type = CallDevice.DeviceType.phone,
                Parameters = new CallDevice.PhoneParams
                {
                    ToNumber = "+15555551111",
                    FromNumber = "+15555550000",
                }
            },
            new CallDevice
            {
                Type = CallDevice.DeviceType.phone,
                Parameters = new CallDevice.PhoneParams
                {
                    ToNumber = "+15555552222",
                    FromNumber = "+15555550000",
                }
            }
        },
        new List<CallDevice>
        {
            new CallDevice
            {
                Type = CallDevice.DeviceType.phone,
                Parameters = new CallDevice.PhoneParams
                {
                    ToNumber = "+15555553333",
                    FromNumber = "+15555550000",
                }
            }
        }
    });
    

    PlayMedia(media)

    This allows playing of various types of media, and allows playing multiple at once allowing TTS to play ontop of audio for example.
    Note: This method is synchronous and depends on receiving messages, as such it must not be called from the same thread as any event callback from the client.

    Available In:

    Parameters

    media List<SignalWire.Relay.Calling.CallMedia> required This is a list of media to be played.

    Returns

    Examples

    Basic Audio Example

    PlayMediaAction action = call.PlayMedia(new List<CallMedia>
    {
        new CallMedia
        {
            Type = CallMedia.MediaType.audio,
            Parameters = new CallMedia.AudioParams
            {
                URL = "http://example.somewhere.com/test.wav"
            }
        }
    });
    

    Basic TTS Example

    PlayMediaAction action = call.PlayMedia(new List<CallMedia>
    {
        new CallMedia
        {
            Type = CallMedia.MediaType.tts,
            Parameters = new CallMedia.TTSParams
            {
                Text = "I'm a little teapot"
            }
        }
    });
    

    Basic Silence Example

    PlayMediaAction action = call.PlayMedia(new List<CallMedia>
    {
        new CallMedia
        {
            Type = CallMedia.MediaType.silence,
            Parameters = new CallMedia.SilenceParams
            {
                Duration = 1.0
            }
        }
    });
    

    PlayAudio(audio)

    This is a helper function that refines the use of PlayMedia. This simplifies playing a single audio media.
    Note: This method is synchronous and depends on receiving messages, as such it must not be called from the same thread as any event callback from the client.

    Available In:

    Parameters

    audio SignalWire.Relay.Calling.CallMedia.AudioParams required This is a single audio media to be played.

    Returns

    Examples

    Basic Example

    PlayAudioAction action = call.PlayAudio(new CallMedia.AudioParams
    {
        URL = "http://example.somewhere.com/test.wav"
    });
    

    PlayTTS(tts)

    This is a helper function that refines the use of PlayMedia. This simplifies playing a single tts media.
    Note: This method is synchronous and depends on receiving messages, as such it must not be called from the same thread as any event callback from the client.

    Available In:

    Parameters

    tts SignalWire.Relay.Calling.CallMedia.TTSParams required This is a single tts media to be played.

    Returns

    Examples

    Basic Example

    PlayTTSAction action = call.PlayTTS(new CallMedia.TTSParams
    {
        Test = "I'm a little tea pot"
    });
    

    PlaySilence(silence)

    This is a helper function that refines the use of PlayMedia. This simplifies playing a single silence media.
    Note: This method is synchronous and depends on receiving messages, as such it must not be called from the same thread as any event callback from the client.

    Available In:

    Parameters

    silence SignalWire.Relay.Calling.CallMedia.SilenceParams required This is a single silence media to be played.

    Returns

    Examples

    Basic Example

    PlaySilenceAction media = call.PlaySilence(new CallMedia.SilenceParams
    {
        Duration = 1.0
    });
    

    PlayMediaAndCollect(media, collect)

    This allows playing of various types of media, and allows playing multiple at once allowing TTS to play ontop of audio for example. This also allows collecting input from the call at the same time, such as digits and speech.
    Note: This method is synchronous and depends on receiving messages, as such it must not be called from the same thread as any event callback from the client.

    Available In:

    Parameters

    media List<SignalWire.Relay.Calling.CallMedia> required This is a list of media to be played.
    collect SignalWire.Relay.Calling.CallCollect required This contains the type and configuration of input to monitor.

    Returns

    Examples

    Basic Example

    call.OnCollect += OnCollect;
    PlayMediaAndCollectAction action = call.PlayMediaAndCollect(new List<CallMedia>
    {
        new CallMedia
        {
            Type = CallMedia.MediaType.tts,
            Parameters = new CallMedia.TTSParams
            {
                Text = "I'm a little teapot"
            }
        }
    },
    new CallCollect
    {
        Digits = new CallCollect.DigitsParams
        {
            Max = 1
        }
    });
    
    private static void OnCollect(CallingAPI api, Call call, CallEventParams.CollectParams collectParams)
    {
        Task.Run(() =>
        {
            if (collectParams.Result.Type == CallEventParams.CollectParams.ResultParams.ResultType.digit)
            {
                PlayMediaAction action = call.PlayMedia(new List<CallMedia>
                {
                    new CallMedia
                    {
                        Type = CallMedia.MediaType.tts,
                        Parameters = new CallMedia.TTSParams
                        {
                            Text = "Short and stout"
                        }
                    }
                });
            }
        });
    }
    

    PlayAudioAndCollect(audio, collect)

    This is a helper function that refines the use of PlayMediaAndCollect. This simplifies playing a single audio media and collecting input from the call at the same time, such as digits and speech.
    Note: This method is synchronous and depends on receiving messages, as such it must not be called from the same thread as any event callback from the client.

    Available In:

    Parameters

    audio SignalWire.Relay.Calling.CallMedia.AudioParams required This is a single audio media to be played.
    collect SignalWire.Relay.Calling.CallCollect required This contains the type and configuration of input to monitor.

    Returns

    Examples

    Basic Example

    call.OnCollect += OnCollect;
    PlayAudioAndCollectAction action = call.PlayAudioAndCollect(new CallMedia.AudioParams
    {
        URL = "http://example.somewhere.com/test.wav"
    },
    new CallCollect
    {
        Digits = new CallCollect.DigitsParams
        {
            Max = 1
        }
    });
    
    private static void OnCollect(CallingAPI api, Call call, CallEventParams.CollectParams collectParams)
    {
        Task.Run(() =>
        {
            if (collectParams.Result.Type == CallEventParams.CollectParams.ResultParams.ResultType.digit)
            {
                PlayAudioAction action = call.PlayAudio(new CallMedia.AudioParams
                {
                    URL = "http://example.somewhere.com/test.wav"
                });
            }
        });
    }
    

    PlayTTSAndCollect(tts, collect)

    This is a helper function that refines the use of PlayMediaAndCollect. This simplifies playing a single tts media and collecting input from the call at the same time, such as digits and speech.
    Note: This method is synchronous and depends on receiving messages, as such it must not be called from the same thread as any event callback from the client.

    Available In:

    Parameters

    tts SignalWire.Relay.Calling.CallMedia.TTSParams required This is a single tts media to be played.
    collect SignalWire.Relay.Calling.CallCollect required This contains the type and configuration of input to monitor.

    Returns

    Examples

    Basic Example

    call.OnCollect += OnCollect;
    PlayTTSAndCollectAction action = call.PlayTTSAndCollect(new CallMedia.TTSParams
    {
        Text = "I'm a little teapot"
    },
    new CallCollect
    {
        Digits = new CallCollect.DigitsParams
        {
            Max = 1
        }
    });
    
    private static void OnCollect(CallingAPI api, Call call, CallEventParams.CollectParams collectParams)
    {
        Task.Run(() =>
        {
            if (collectParams.Result.Type == CallEventParams.CollectParams.ResultParams.ResultType.digit)
            {
                PlayTTSAction action = call.PlayTTS(new CallMedia.TTSParams
                {
                    Text = "Short and stout"
                });
            }
        });
    }
    

    PlaySilenceAndCollect(silence, collect)

    This is a helper function that refines the use of PlayMediaAndCollect. This simplifies playing a single silence media and collecting input from the call at the same time, such as digits and speech.
    Note: This method is synchronous and depends on receiving messages, as such it must not be called from the same thread as any event callback from the client.

    Available In:

    Parameters

    silence SignalWire.Relay.Calling.CallMedia.SilenceParams required This is a single silence media to be played.
    collect SignalWire.Relay.Calling.CallCollect required This contains the type and configuration of input to monitor.

    Returns

    Examples

    Basic Example

    call.OnCollect += OnCollect;
    PlaySilenceAndCollectAction action = call.PlaySilenceAndCollect(new CallMedia.SilenceParams
    {
        Duration = 1.0
    },
    new CallCollect
    {
        Digits = new CallCollect.DigitsParams
        {
            Max = 1
        }
    });
    
    private static void OnCollect(CallingAPI api, Call call, CallEventParams.CollectParams collectParams)
    {
        Task.Run(() =>
        {
            if (collectParams.Result.Type == CallEventParams.CollectParams.ResultParams.ResultType.digit)
            {
                PlayTTSAction action = call.PlayTTS(new CallMedia.TTSParams
                {
                    Text = "Silence is boring"
                });
            }
        });
    }
    

    Record(record)

    Start recording something from the call.
    Note: This method is synchronous and depends on receiving messages, as such it must not be called from the same thread as any event callback from the client.

    Available In:

    Parameters

    record SignalWire.Relay.Calling.CallRecord required This is the recording configuration.

    Returns

    SignalWire.Relay.Calling.RecordAction - This is the same recording configuration passed in, with a control ID assigned.

    Examples

    Basic Example

    RecordAction action = client.Record(Guid.NewGuid().ToString(), CallRecordType.audio, new CallRecordAudio
    {
        // Using default audio parameters
    });
    

    Events

    OnStateChange Called any time the state of the call changes.
    OnRinging Called when the state of the call changes to ringing.
    OnAnswered Called when the state of the call changes to answered.
    OnEnding Called when the state of the call changes to ending.
    OnEnded Called when the state of the call changes to ended.
    OnConnectStateChange Called any time the state of a connect operation changes.
    OnConnectFailed Called when the state of a connect operation changes to failed.
    OnConnectConnecting Called when the state of a connect operation changes to connecting.
    OnConnectConnected Called when the state of a connect operation changes to connected.
    OnConnectDisconnected Called when the state of a connect operation changes to disconnected.
    OnPlayStateChange Called any time the state of a play operation changes.
    OnPlayPlaying Called when the state of a play operation changes to playing.
    OnPlayError Called when the state of a play operation changes to error.
    OnPlayPaused Called when the state of a play operation changes to paused.
    OnPlayFinished Called when the state of a play operation changes to finished.
    OnCollect Called when a collect operation completes or times out with no input.
    OnRecordStateChange Called any time the state of a record operation changes.
    OnRecordRecording Called when the state of a record operation changes to recording.
    OnRecordPaused Called when the state of a record operation changes to paused.
    OnRecordFinished Called when the state of a record operation changes to finished.
    OnRecordNoInput Called when the state of a record operation changes to no input.

    SignalWire.Relay.Calling.PhoneCall

    This object represents an active PSTN phone call, and inherits from SignalWire.Relay.Calling.Call.

    Constructor

    The constructors for this object are internal and available only to the library. There are no public details provided for the constructors as they are only used internally.

    Parameters

    Not Available

    Examples

    Not Available

    Properties

    To string The to number in E164 format.
    From string The from number in E164 format.
    Timeout int Timeout in seconds before the call fails after it is started.

    See SignalWire.Relay.Calling.Call for additional inherited properties.

    Methods

    Begin()

    This will start a call that was created with the phone call type using the method available on the calling API object.
    Note: This method is synchronous and depends on receiving messages, as such it must not be called from the same thread as any event callback from the client.

    Available In:

    Parameters

    None

    Returns

    • void

    Examples

    Basic Example

    PhoneCall call = client.Calling.NewPhoneCall("+15551234567", "+15551237654");
    // Assign event callbacks
    call.Begin();
    

    See SignalWire.Relay.Calling.Call for additional inherited methods.

    Events

    None

    See SignalWire.Relay.Calling.Call for additional inherited events.

    SignalWire.Relay.Calling.CallState

    This is an enumeration that represents the different possible call states any call may have.

    Values

    failed The call has failed.
    created The call has been created.
    ringing The call is ringing.
    connecting The call is connecting.
    connected The call has connected.
    answered The call has been answered.
    disconnecting The call is disconnecting.
    disconnected The call has disconnected.
    ending The call is ending.
    ended The call has ended.

    SignalWire.Relay.Calling.CallDevice

    This object represents the device by which a call was created.

    Constructor

    The only constructor is the default constructor, properties should all be assigned by initializer or after construction.

    Parameters

    None

    Examples

    Basic Example

    CallDevice device = new CallDevice
    {
        Type = CallDevice.DeviceType.phone,
        Parameters = new CallDevice.PhoneParams
        {
            ToNumber = "+15555551234",
        FromNumber = "+15555554321",
        Timeout = 30
        }
    }
    

    Properties

    Type SignalWire.Relay.Calling.CallDevice.DeviceType This is the type of the device.
    Parameters object This is the object that represents the parameters specific to the type, see SignalWire.Relay.Calling.CallDevice.DeviceType for more information.

    Methods

    ParametersAs<T>()

    This is a helper method to convert the Parameters to the real type.

    Available In:

    Parameters

    T Type required This is the data type for the conversion, see SignalWire.Relay.Calling.CallDevice.DeviceType for more information.

    Returns

    Examples

    CallDevice.PhoneParams phoneParams = device.ParametersAs<CallDevice.PhoneParams>();
    

    Events

    None

    SignalWire.Relay.Calling.CallDevice.DeviceType

    This is an enumeration that represents the possible types of devices and by proxy the call types any call may be.

    Values

    phone The call type is a SignalWire.Relay.Calling.PhoneCall.
    The device parameters are SignalWire.Relay.Calling.CallDevice.PhoneParams.

    SignalWire.Relay.Calling.CallDevice.PhoneParams

    This object represents the parameters specific to a phone device.

    Constructor

    The only constructor is the default constructor, properties should all be assigned by initializer or after construction.

    Parameters

    None

    Examples

    Basic Example

    CallDevice device = new CallDevice
    {
        Type = CallDevice.DeviceType.phone,
        Parameters = new CallDevice.PhoneParams
        {
            ToNumber = "+15555551234",
            FromNumber = "+15555554321",
            Timeout = 30
        }
    }
    

    Properties

    ToNumber string The to number in E164 format.
    FromNumber string The from number in E164 format.
    Timeout int Timeout in seconds before the call fails after it is started.

    Methods

    None

    Events

    None

    SignalWire.Relay.Calling.CallMedia

    This object represents a call media that is being played.

    Constructor

    The only constructor is the default constructor, properties should all be assigned by initializer or after construction.

    Parameters

    None

    Examples

    Basic Example

    CallMedia media = new CallMedia
    {
        Type = CallMedia.MediaType.tts,
        Parameters = new CallDevice.TTSParams
        {
            Text = "I'm a little teapot"
        }
    }
    

    Properties

    Type SignalWire.Relay.Calling.CallMedia.MediaType This is the type of the media.
    Parameters object This is the object that represents the parameters specific to the type, see SignalWire.Relay.Calling.CallMedia.MediaType for more information.

    Methods

    ParametersAs<T>()

    This is a helper method to convert the Parameters to the real type.

    Available In:

    Parameters

    T Type required This is the data type for the conversion, see SignalWire.Relay.Calling.CallMedia.MediaType for more information.

    Returns

    Examples

    CallDevice.AudioParams audioParams = device.ParametersAs<CallDevice.AudioParams>();
    CallDevice.TTSParams ttsParams = device.ParametersAs<CallDevice.TTSParams>();
    CallDevice.SilenceParams silenceParams = device.ParametersAs<CallDevice.SilenceParams>();
    

    Events

    None

    SignalWire.Relay.Calling.CallMedia.MediaType

    This is an enumeration that represents the possible types of media.

    Values

    audio The media parameters are SignalWire.Relay.Calling.CallMedia.AudioParams.
    tts The media parameters are SignalWire.Relay.Calling.CallMedia.TTSParams.
    silence The media parameters are SignalWire.Relay.Calling.CallMedia.SilenceParams.

    SignalWire.Relay.Calling.CallMedia.AudioParams

    This object represents the parameters specific to audio media.

    Constructor

    The only constructor is the default constructor, properties should all be assigned by initializer or after construction.

    Parameters

    None

    Examples

    Basic Example

    CallMedia media = new CallMedia
    {
        Type = CallMedia.MediaType.audio,
        Parameters = new CallMedia.AudioParams
        {
            URL = "http://example.somewhere.com/test.wav"
        }
    }
    

    Properties

    URL string The url of the audio file to play.

    Methods

    None

    Events

    None

    SignalWire.Relay.Calling.CallMedia.TTSParams

    This object represents the parameters specific to tts media.

    Constructor

    The only constructor is the default constructor, properties should all be assigned by initializer or after construction.

    Parameters

    None

    Examples

    Basic Example

    CallMedia media = new CallMedia
    {
        Type = CallMedia.MediaType.tts,
        Parameters = new CallMedia.TTSParams
        {
            Text = "I'm a little teapot"
        }
    }
    

    Properties

    Text string The text to process into speech.

    Methods

    None

    Events

    None

    SignalWire.Relay.Calling.CallMedia.SilenceParams

    This object represents the parameters specific to silence media.

    Constructor

    The only constructor is the default constructor, properties should all be assigned by initializer or after construction.

    Parameters

    None

    Examples

    Basic Example

    CallMedia media = new CallMedia
    {
        Type = CallMedia.MediaType.silence,
        Parameters = new CallMedia.SilenceParams
        {
            Duration = 1.0
        }
    }
    

    Properties

    Duration double The duration in seconds the silence is played.

    Methods

    None

    Events

    None

    SignalWire.Relay.Calling.PlayMediaAction

    This object represents a call media action that is active.

    Constructor

    This object is constructed internally only.

    Parameters

    None

    Examples

    None

    Properties

    Call SignalWire.Relay.Calling.Call This is the call the action is occurring on.
    ControlID string The control ID that is assigned to manage the action.
    Media List<SignalWire.Relay.Calling.CallMedia> This is the media being played.

    Methods

    Stop()

    Stop the action immediately.

    Available In:

    Parameters

    None

    Returns

    • void

    Examples

    PlayMediaAction action = call.PlayMedia(new List<CallMedia>
    {
        new CallMedia
        {
            Type = CallMedia.MediaType.tts,
            Parameters = new CallMedia.TTSParams
            {
                Text = "I'm a little teapot"
            }
        }
    });
    Thread.Sleep(1000);
    action.Stop();
    

    Events

    None

    SignalWire.Relay.Calling.PlayAudioAction

    This object represents a call audio media action that is active.

    Constructor

    This object is constructed internally only.

    Parameters

    None

    Examples

    None

    Properties

    Call SignalWire.Relay.Calling.Call This is the call the action is occurring on.
    ControlID string The control ID that is assigned to manage the action.
    Media SignalWire.Relay.Calling.CallMedia This is the media being played.

    Methods

    Stop()

    Stop the action immediately.

    Available In:

    Parameters

    None

    Returns

    • void

    Examples

    PlayAudioAction action = call.PlayAudio(new CallMedia.AudioParams
    {
        URL = "http://example.somewhere.com/test.wav"
    });
    Thread.Sleep(1000);
    action.Stop();
    

    Events

    None

    SignalWire.Relay.Calling.PlayTTSAction

    This object represents a call tts media action that is active.

    Constructor

    This object is constructed internally only.

    Parameters

    None

    Examples

    None

    Properties

    Call SignalWire.Relay.Calling.Call This is the call the action is occurring on.
    ControlID string The control ID that is assigned to manage the action.
    Media SignalWire.Relay.Calling.CallMedia This is the media being played.

    Methods

    Stop()

    Stop the action immediately.

    Available In:

    Parameters

    None

    Returns

    • void

    Examples

    PlayTTSAction action = call.PlayTTS(new CallMedia.TTSParams
    {
        Test = "I'm a little tea pot"
    });
    Thread.Sleep(1000);
    action.Stop();
    

    Events

    None

    SignalWire.Relay.Calling.PlaySilenceAction

    This object represents a call silence media action that is active.

    Constructor

    This object is constructed internally only.

    Parameters

    None

    Examples

    None

    Properties

    Call SignalWire.Relay.Calling.Call This is the call the action is occurring on.
    ControlID string The control ID that is assigned to manage the action.
    Media SignalWire.Relay.Calling.CallMedia This is the media being played.

    Methods

    Stop()

    Stop the action immediately.

    Available In:

    Parameters

    None

    Returns

    • void

    Examples

    PlaySilenceAction action = call.PlayAudio(new CallMedia.SilenceParams
    {
        Duration = 5.0
    });
    Thread.Sleep(1000);
    action.Stop();
    

    Events

    None

    SignalWire.Relay.Calling.CallCollect

    This object represents call input that is being collected, multiple things may be collected at the same time such as digits and speech.

    Constructor

    The only constructor is the default constructor, properties should all be assigned by initializer or after construction.

    Parameters

    None

    Examples

    Basic Example

    CallCollect collect = new CallCollect
    {
        Digits = new CallCollect.DigitsParams
        {
            Max = 1
        }
    }
    

    Properties

    InitialTimeout double? This is the initial timeout in seconds if no input is received.
    Default: 5 seconds
    Digits SignalWire.Relay.Calling.CallCollect.DigitsParams This object contains configuration for collecting digits.
    Speech SignalWire.Relay.Calling.CallCollect.SpeechParams This object contains configuration for collecting speech.

    Methods

    None

    Events

    None

    SignalWire.Relay.Calling.CallCollect.DigitsParams

    This object represents the parameters specific to digits collecting.

    Constructor

    The only constructor is the default constructor, properties should all be assigned by initializer or after construction.

    Parameters

    None

    Examples

    Basic Example

    CallCollect collect = new CallCollect
    {
        Digits = new CallCollect.DigitsParams
        {
            Max = 1
        }
    }
    

    Properties

    Max int The maximum number of digits to collect, must be greater than zero.
    Terminators string A string of individual characters that can be used to terminate prematurely.
    DigitTimeout double? The timeout before terminating prematurely if at least one digit was collected.
    Default: 1 second

    Methods

    None

    Events

    None

    SignalWire.Relay.Calling.CallCollect.SpeechParams

    This object represents the parameters specific to speech collecting.

    Constructor

    The only constructor is the default constructor, properties should all be assigned by initializer or after construction.

    Parameters

    None

    Examples

    Basic Example

    CallCollect collect = new CallCollect
    {
        Speech = new CallCollect.SpeechParams
        {
            // No required parameters
        }
    }
    

    Properties

    SpeechTimeout double? The timeout before terminating prematurely if no speech was detected.
    Default: 5 seconds
    EndSilenceTimeout double? The timeout before terminating prematurely if speech was detected and then stops.
    Default: 1 second

    Methods

    None

    Events

    None

    SignalWire.Relay.Calling.PlayMediaAndCollectAction

    This object represents a call media and collect action that is active.

    Constructor

    This object is constructed internally only.

    Parameters

    None

    Examples

    None

    Properties

    Call SignalWire.Relay.Calling.Call This is the call the action is occurring on.
    ControlID string The control ID that is assigned to manage the action.
    Media List<SignalWire.Relay.Calling.CallMedia> This is the media being played.
    Collect SignalWire.Relay.Calling.CallCollect This is the collecting information.

    Methods

    Stop()

    Stop the action immediately.

    Available In:

    Parameters

    None

    Returns

    • void

    Examples

    call.OnCollect += OnCollect;
    PlayMediaAndCollectAction action = call.PlayMediaAndCollect(new List<CallMedia>
    {
        new CallMedia
        {
            Type = CallMedia.MediaType.tts,
            Parameters = new CallMedia.TTSParams
            {
                Text = "I'm a little teapot"
            }
        }
    },
    new CallCollect
    {
        Digits = new CallCollect.DigitsParams
        {
            Max = 1
        }
    });
    
    Thread.Sleep(1000);
    action.Stop();
    
    private static void OnCollect(CallingAPI api, Call call, CallEventParams.CollectParams collectParams)
    {
        Task.Run(() =>
        {
            if (collectParams.Result.Type == CallEventParams.CollectParams.ResultParams.ResultType.digit)
            {
                PlayMediaAction action = call.PlayMedia(new List<CallMedia>
                {
                    new CallMedia
                    {
                        Type = CallMedia.MediaType.tts,
                        Parameters = new CallMedia.TTSParams
                        {
                            Text = "Short and stout"
                        }
                    }
                });
            }
        });
    }
    

    Events

    None

    SignalWire.Relay.Calling.PlayAudioAndCollectAction

    This object represents a call audio media and collect action that is active.

    Constructor

    This object is constructed internally only.

    Parameters

    None

    Examples

    None

    Properties

    Call SignalWire.Relay.Calling.Call This is the call the action is occurring on.
    ControlID string The control ID that is assigned to manage the action.
    Media SignalWire.Relay.Calling.CallMedia This is the media being played.
    Collect SignalWire.Relay.Calling.CallCollect This is the collecting information.

    Methods

    Stop()

    Stop the action immediately.

    Available In:

    Parameters

    None

    Returns

    • void

    Examples

    call.OnCollect += OnCollect;
    PlayAudioAndCollectAction action = call.PlayAudioAndCollect(new CallMedia.AudioParams
    {
        URL = "http://example.somewhere.com/test.wav"
    },
    new CallCollect
    {
        Digits = new CallCollect.DigitsParams
        {
            Max = 1
        }
    });
    
    Thread.Sleep(1000);
    action.Stop();
    
    private static void OnCollect(CallingAPI api, Call call, CallEventParams.CollectParams collectParams)
    {
        Task.Run(() =>
        {
            if (collectParams.Result.Type == CallEventParams.CollectParams.ResultParams.ResultType.digit)
            {
                PlayAudioAction action = call.PlayAudio(new CallMedia.AudioParams
                {
                    URL = "http://example.somewhere.com/test.wav"
                });
            }
        });
    }
    

    Events

    None

    SignalWire.Relay.Calling.PlayTTSAndCollectAction

    This object represents a call tts media and collect action that is active.

    Constructor

    This object is constructed internally only.

    Parameters

    None

    Examples

    None

    Properties

    Call SignalWire.Relay.Calling.Call This is the call the action is occurring on.
    ControlID string The control ID that is assigned to manage the action.
    Media SignalWire.Relay.Calling.CallMedia This is the media being played.
    Collect SignalWire.Relay.Calling.CallCollect This is the collecting information.

    Methods

    Stop()

    Stop the action immediately.

    Available In:

    Parameters

    None

    Returns

    • void

    Examples

    call.OnCollect += OnCollect;
    PlayTTSAndCollectAction action = call.PlayTTSAndCollect(new CallMedia.TTSParams
    {
        Text = "I'm a little teapot"
    },
    new CallCollect
    {
        Digits = new CallCollect.DigitsParams
        {
            Max = 1
        }
    });
    
    Thread.Sleep(1000);
    action.Stop();
    
    private static void OnCollect(CallingAPI api, Call call, CallEventParams.CollectParams collectParams)
    {
        Task.Run(() =>
        {
            if (collectParams.Result.Type == CallEventParams.CollectParams.ResultParams.ResultType.digit)
            {
                PlayTTSAction action = call.PlayTTS(new CallMedia.TTSParams
                {
                    Text = "Short and stout"
                });
            }
        });
    }
    

    Events

    None

    SignalWire.Relay.Calling.PlaySilenceAndCollectAction

    This object represents a call silence media and collect action that is active.

    Constructor

    This object is constructed internally only.

    Parameters

    None

    Examples

    None

    Properties

    Call SignalWire.Relay.Calling.Call This is the call the action is occurring on.
    ControlID string The control ID that is assigned to manage the action.
    Media SignalWire.Relay.Calling.CallMedia This is the media being played.
    Collect SignalWire.Relay.Calling.CallCollect This is the collecting information.

    Methods

    Stop()

    Stop the action immediately.

    Available In:

    Parameters

    None

    Returns

    • void

    Examples

    call.OnCollect += OnCollect;
    PlaySilenceAndCollectAction action = call.PlaySilenceAndCollect(new CallMedia.SilenceParams
    {
        Duration = 5.0
    },
    new CallCollect
    {
        Digits = new CallCollect.DigitsParams
        {
            Max = 1
        }
    });
    
    Thread.Sleep(1000);
    action.Stop();
    
    private static void OnCollect(CallingAPI api, Call call, CallEventParams.CollectParams collectParams)
    {
        Task.Run(() =>
        {
            if (collectParams.Result.Type == CallEventParams.CollectParams.ResultParams.ResultType.digit)
            {
                PlayTTSAction action = call.PlayTTS(new CallMedia.TTSParams
                {
                    Text = "Silence is boring"
                });
            }
        });
    }
    

    Events

    None

    SignalWire.Relay.Calling.CallRecord

    This object represents call recording that is being handled, multiple things may be recorded in the same recording in the future, but currently only audio is available. It is also possible to start multiple different recordings at the same time.

    Constructor

    The only constructor is the default constructor, properties should all be assigned by initializer or after construction.

    Parameters

    None

    Examples

    Basic Example

    CallRecord record = new CallRecord
    {
        Audio = new CallRecord.AudioParams
        {
            // Use default audio recording parameters
        }
    }
    

    Properties

    Audio SignalWire.Relay.Calling.CallRecord.AudioParams This object contains configuration for recording audio.

    Methods

    None

    Events

    None

    SignalWire.Relay.Calling.CallRecord.AudioParams

    This object represents the parameters specific to audio recording.

    Constructor

    The only constructor is the default constructor, properties should all be assigned by initializer or after construction.

    Parameters

    None

    Examples

    Basic Example

    CallRecord record = new CallRecord
    {
        Audio = new CallRecord.AudioParams
        {
            // Use default audio recording parameters
        }
    }
    

    Properties

    Beep bool? Whether or not to include a beep at the start of the recording.
    Default: false
    Format SignalWire.Relay.Calling.CallRecord.AudioParams.AudioFormat? The format of the audio recording.
    Default: mp3
    Stereo bool? Whether to include stereo or only mono tracks in the audio recording.
    Default: false
    Direction SignalWire.Relay.Calling.CallRecord.AudioParams.AudioDirection? The direction to include in the audio recording, speak (what the caller says), listen (what the caller hears), or both.
    Default: speak
    InitialTimeout double? How long to wait in seconds until audio is detected to begin recording.
    Default: 5 seconds
    Note: Disable with 0
    EndSilenceTimeout double? How long to wait in seconds after audio is no longer detected to terminate recording.
    Default: 1 second
    Note: Disable with 0
    Terminators string A string of individual DTMF characters that can be used to terminate recording.
    Default: #*

    Methods

    None

    Events

    None

    SignalWire.Relay.Calling.CallRecord.AudioParams.AudioFormat

    This is an enumeration that represents the possible formats for audio recordings.

    Values

    mp3 The recording is mp3 format.
    wav The recording is wav format.

    SignalWire.Relay.Calling.CallRecord.AudioParams.AudioDirection

    This is an enumeration that represents the possible directions for audio recordings.

    Values

    listen The recording includes what is heard by the owner.
    speak The recording includes what is said by the owner.
    both The recording includes what is heard and said by the owner.

    SignalWire.Relay.Calling.RecordAction

    This object represents a call record action that is active.

    Constructor

    This object is constructed internally only.

    Parameters

    None

    Examples

    None

    Properties

    Call SignalWire.Relay.Calling.Call This is the call the action is occurring on.
    ControlID string The control ID that is assigned to manage the action.
    Record SignalWire.Relay.Calling.CallRecord This is the recording configuration.

    Methods

    Stop()

    Stop the action immediately.

    Available In:

    Parameters

    None

    Returns

    void

    Examples

    RecordAction action = call.Record(new CallRecord
    {
        Audio = new CallRecord.AudioParams
        {
            // Use default audio recording parameters
        }
    });
    Thread.Sleep(1000);
    action.Stop();
    

    Events

    None