Getting Started with SignalWire Compatibility APIs

What are SignalWire Compatibility APIs?

The Compatibility REST APIs are comprehensive REST APIs that enable easy management of all aspects of the SignalWire Compatibility API functionality including calls, conferences, messaging, and account maintenance.

SignalWire's REST APIs allow you to manage and modify calls and messages made to or from your SignalWire phone numbers. You also have the ability to retrieve and update your account information, retrieve your entire history of calls, messages, transcriptions, media, and more.

An application such as a PBX has the ability to search for and purchase phone numbers then set their destinations.

This can all be achieved by sending HTTP requests to the SignalWire REST API.

📘

LaML terminology

You will see some sections within your SignalWire space referred to as LaML. This is our antiquated terminology for our Compatible API. Please note that they refer to the same API!

Getting started with Ruby

Our SDKs support many languages, and you can find information on each on the documentation website.

For the sake of this post, we will be using the Ruby library available via Rubygems.

The instructions to get started with Ruby are here, but all you need for this tutorial is to install the gem with gem install signalwire.

You will also need your space URL, project ID, and API token from your SignalWire dashboard.

Space URL, project ID and the API token in SignalWire DashboardSpace URL, project ID and the API token in SignalWire Dashboard

Initializing the client is then very simple:

require 'signalwire/sdk'
@client = Signalwire::REST::Client.new 'your-project', 'your-token', signalwire_space_url: "example.signalwire.com"

# You can then use @client to make calls, send messages, and more.
const { RestClient } = require('@signalwire/node')
const client = new RestClient('YourProjectID', 'YourAuthToken', { signalwireSpaceUrl: 'example.signalwire.com' })

// You can then use `client` to make calls, send messages, and more.

As a reminder, when you are doing outbound calling or messaging, you will need to verify your target number first if your account is in trial. The verification form can be found in the dashboard, under Phone Numbers > Verified.

Making a phone call

The first idea we can experiment with is making a phone call to your own number. This could be an example of a reminder call coming from an automated system, or some kind of alert.

We will need three pieces. The first is a LaML bin containing the message we would like to play back. In a complete application, instead of the LaML bin, you would be using your own HTTP endpoint to provide the document.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Hello! This is a reminder for your appointment at ten o' clock AM tomorrow.</Say>
</Response>

Second, you need to have at least one phone number in your SignalWire account, to be used as the caller ID.

The third and final piece is a Ruby file containing the necessary code. I will be repeating the client instantiation code in each block throughout the article so they can be run stand-alone.

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:   '+1555001122333', # This needs to be your destination number, verified if in trial
  from: '+15559988777' # This is one phone number from your SignalWire account
)

puts call.sid
const { RestClient } = require('@signalwire/node')
const client = new RestClient('YourProjectID', 'YourAuthToken', { signalwireSpaceUrl: 'example.signalwire.com' })

client.calls
      .create({
         url: 'http://your-application.com/docs/voice.xml',
         to: '+13105678901',
         from: '+13103384645'
       })
      .then(call => console.log(call.sid))
      .done();

Run your Ruby code with ruby call.rb and listen to the reminder!

Sending a text message or MMS

In much the same fashion, it is very easy to send out a text message or an MMS to a phone number.

require 'signalwire/sdk'
client = Signalwire::REST::Client.new 'your-project', 'your-token', signalwire_space_url: "example.signalwire.com"

message = client.messages.create(
  to:   '+1555001122333', # This needs to be your destination number, verified if in trial
  from: '+15559988777' # This is one phone number from your SignalWire account
  body: 'Hello from SignalWire'
)

puts message.inspect # not necessary, just taking a peek
const { RestClient } = require('@signalwire/node')
const client = new RestClient('YourProjectID', 'YourAuthToken', { signalwireSpaceUrl: 'example.signalwire.com' })

client.messages
      .create({from: '+15551234567', body: 'Hello World!', to: '+15557654321'})
      .then(message => console.log(message.sid))
      .done();

To attach a media file to a message, simply specify a media_url parameter, pointing at a file available via HTTP. The size limit is currently 0.5Mb and the list of accepted MIME types can be found here.

require 'signalwire/sdk'
client = Signalwire::REST::Client.new 'your-project', 'your-token', signalwire_space_url: "example.signalwire.com"

mms = client.messages.create(
  to:   '+15550011222',
  from: '+15559988777'
  body: 'Here is a photo from my holidays',
  media_url: 'https://SOME-EXAMPLE-URL'
)

puts mms.inspect
const { RestClient } = require('@signalwire/node')
const client = new RestClient('YourProjectID', 'YourAuthToken', { signalwireSpaceUrl: 'example.signalwire.com' })

client.messages
      .create({from: '+15551234567', body: 'Hello World!', to: '+15557654321', 
                media_url: 'https://SOME-EXAMPLE-URL'
              })
      .then(message => console.log(message.sid))
      .done();

Sending a fax

To send a fax, just use the client in a very similar way to an MMS. In this case, we will include a status_callback URL to introduce the concept of using webhooks for action updates.

require 'signalwire/sdk'
client = Signalwire::REST::Client.new 'your-project', 'your-token', signalwire_space_url: "example.signalwire.com"

fax = client.fax.faxes.create( # syntax is a little tricky here due to namespacing
  to:   '+1555001122333',
  from: '+15559988777'
  media_url: 'https://SOME-EXAMPLE-URL/document.pdf',
  status_callback: 'https://YOUR-APPLICATION-URL/CALLBACK-PATH'
)

puts fax.inspect
const { RestClient } = require('@signalwire/node')
const client = new RestClient('YourProjectID', 'YourAuthToken', { signalwireSpaceUrl: 'example.signalwire.com' })

client.fax.faxes
  .create({
     from: '+13103383454',
     to: '+13104456789',
     mediaUrl: 'https://example.com/fax.pdf'
   })
  .then(fax => console.log(fax.sid))
  .done();

Using status callbacks

All of the above requests can specify a status_callback URL as part of the parameters. If provided, SignalWire will send a POST request to that URL every time the status of the action being performed changes.

For example, when sending a fax, the endpoint will receive form encoded parameters with how many pages have been sent so far, a status code such as sending and any errors that present themselves. It would be then easy to update a UI with information on the fax processing.

Listing usage

The last example we are going to look at is how to list the calls that have been made on your project. This could be useful for billing or just for your internal reference.

require 'signalwire/sdk'
client = Signalwire::REST::Client.new 'your-project', 'your-token', signalwire_space_url: "example.signalwire.com"

calls = client.calls.list

calls.each do |record|
  puts record.inspect # prints information about each call
end
const { RestClient } = require('@signalwire/node')
const client = new RestClient('YourProjectID', 'YourAuthToken', { signalwireSpaceUrl: 'example.signalwire.com' })

client.calls.each(call => console.log(call));

Conclusions

There are many more things you can achieve using the SignalWire Compatibility REST API, such as listing and buying phone numbers, but we will leave those for our PBX functionality series of posts.

SignalWire in Seconds

If you want to see a live explanation of how SignalWire works with our carriers to send a message, call, or fax, feel free to watch this SignalWire in Seconds video. If you want to learn more concepts about SignalWire in just a few short minutes each, check out our YouTube Channel!


Did this page help you?