SIP on SignalWire
The basics of using SIP with your SignalWire account
In our previous posts, we have explored the many opportunities the LāML API provides for application developers.
SignalWire also supports the standard in VoIP telephony, the SIP protocol. This allows you to connect your devices and systems to the SignalWire Cloud, and to leverage the available features from existing SIP infrastructure.
Creating and registering a SIP endpoint
To register and use SIP endpoints to place calls, head to the
SIP page in your dashboard.
First of all, let's take a look at the
SIP Settings tab.
This is where the most important options for SIP are set. Your SIP registration URI has been filled in with a random string, and you can change that to something more legible if you so wish.
Setting a default number to use as caller ID is also possible, and you can manage your codec settings from here.
Create your endpoint by clicking on
Endpoints and then
Endpoints can also be created programmatically as discussed in this article. That would be useful for an application needing to create many endpoints for a set of clients.
Registering to SignalWire
Depending on your SIP client, you might have to enter settings in a different way. The generic setup would be:
Username: the username portion of the SIP address you set up Domain: the domain portion of the SIP address Password: the password you set
A SIP desktop client example is Bria, a very feature-complete and usable softphone. Setting that up for SignalWire SIP is very simple.
You could of course use the same credentials to connect your hardware phone or a PBX such as FusionPBX or FreePBX.
Making calls from your endpoint
After registering, just dial a PSTN number (try
+1-202-762-1401 for the Washington D.C. weather phone). You can also dial SIP addresses straight away.
Triggering outbound calls via LaML
If you are using LāML, you might want to dial out to a SIP target using the
<Dial> verb. In that case, the
<Sip> tag is what you would use.
Documented here, it allows you to dial out to SIP addresses with various options. You can set a
StatusCallback URL as with other
<Dial> targets, to get status updates during the process.
SignalWire supports authenticating to a SIP proxy via the
password attributes, and the standard SIP URI components can be added to drive specific application needs.
Here is a full example:
<?xml version="1.0" encoding="UTF-8"?> <Response> <Dial callerId="+18889090909"> <Sip username="youruser" password="yourpass"> sip:email@example.com;transport=udp?header1=foo&header2=bar </Sip> </Dial> </Response>
Caller IDs work differently when dialing out to SIP: you can use any ID, and it assumed to be validated by your SIP upstream. This applies both on LaML and outbound REST calls.
Making outbound calls via the LāML API
To trigger outbound calls using the LaML API, you can use the Calls LaML REST API documented here.
The method supports a long list of parameters, and the relevant ones for SIP are
Url would support the same structure and SIP options as the LaML version.
A full example in CURL and Ruby:
require 'signalwire/sdk' client = Signalwire::REST::Client.new 'your-project', 'your-token', signalwire_space_url: "example.signalwire.com" call = client.calls.create( url: 'http://YOURSPACE.signalwire.com/YOUR-LAML-BIN-ID', to: 'sip:firstname.lastname@example.org;transport=udp?header1=foo&header2=bar', from: '+15559988777', sip_auth_username: 'user', sip_auth_password: 'pass' ) puts call.sid
curl https://<YOURSPACE>.signalwire.com/api/laml/2010-04-01/Accounts/<YOURACCOUNTSID>/Calls.json \ -X POST \ --data-urlencode "Url=http://your-application.com/docs/voice.xml" \ --data-urlencode "To=sip:email@example.com;transport=udp?header1=foo&header2=bar" \ --data-urlencode "From=+15550011222" \ --data-urlencode "SipAuthUsername=user" \ --data-urlencode "SipAuthPassword=pass" \ -u "YourProjectID:YourAuthToken"
Inbound SIP: the Domain Application
To receive calls from a SIP source to your SignalWire account in a Bring Your Own Connectivty (BYOC) scenario, you would use the SIP Domain Application features.
It allows you to create a domain to which to point all of your SIP calls.
firstname.lastname@example.org will get the call into the LāML webhook you specify.
This allows you to use connectivity from any provider capable of sending a call to a SIP address to use SignalWire services.
Always use whitelisting of IPs if possible, as otherwise all requests to the domain will be processed.
Using SIP with your SignalWire accounts allows you to build complex and useful systems without having to run your own infrastructure.