Skip to main content

Making and Receiving Phone Calls

In this guide we are going to show how to make and receive phone calls using the following products:

  • SWML
    • SWML Script
  • Compatibility API
    • REST APIs
    • XML Bins

Prerequisites

To be able to make calls, you will need:

  • a SignalWire phone number
  • your API credentials (Space URL, Project ID, and API token)

To acquire a phone number, Log in to your SignalWire Space. From the Phone Numbers section, you can buy a new phone number. You will need at least one number to make and receive calls.

For what concerns your API credentials, find these in the API section of your Space, as shown in the following figure. You may need to create a new token if you never used one. Make sure that your token has the "Voice" scope enabled.

A screenshot of the API page of a SignalWire Space. Active API Tokens are listed in table format.

You can find your Project ID and Token from the API tab in your SignalWire Space. Make sure your token has the "Voice" scope enabled.

Trial Mode

If your account is in trial mode, you need to upgrade it in order to call numbers other than your own verified numbers. See How to exit Trial Mode.

SWML

Receiving incoming calls

To handle incoming calls we need to configure the phone number in our SignalWire Space to answer calls using a SWML Script.

To create a SWML Script, go to the "Relay/SWML" section in your SignalWire Space, then click on the "SWML Scripts" tab. Click on "Create a SWML Script", and then give it a name and pass it some instructions. You can use the following as a starting point:

version: 1.0.0
sections:
main:
- play: say:Hello from SignalWire!
In this animated GIF, the user navigates to the Relay/SWML page of a SignalWire Space. In the SWML Scripts tab, they select 'Create a New SWML Script', title it, and add YAML code.

Creating your first SWML Script.

Take note of the Request URL for the SWML Script that we created. You can even create a new script if you want to define a different behavior for incoming calls.

To configure your number to handle incoming calls with an SWML Script, click the "Phone Numbers" section within your SignalWire Space, and edit the settings of the specific number you would like to use to answer calls. Set "Handle calls using" to "a SWML Script", then select your SWML Script from the dropdown:

In this animated GIF, the user navigates to the Phone Numbers page of a SignalWire Space. In the Purchased tab, they select the ellipsis menu icon on a phone number and select the Edit option. They elect to handle calls using a SWML Script and select the relevant script using a drop-down menu before saving.

Connecting your Phone Number to your SWML Script.

That's it! Inbound calls to this SignalWire number will execute the specified SWML Script.

Compatibility API

Making your first call

You now have all you need to make your first call, for example to your personal phone number.

We want to call a number and play an audio message which says "Welcome to SignalWire. This is my first call". We are going to define this behavior in an XML bin, which is used to declare what should happen during a call.

To create an XML bin, go to the "LaML" section in your SignalWire Space, then click on "Bins".

In the LaML page of a SignalWire Space, the Bins tab is circled in red.

To create a new XML bin, click the blue button in the LaML section of your SignalWire Space.

Create a new bin, and paste the following XML in it:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say>Welcome to SignalWire. This is my first call.</Say>
</Response>

The XML above uses the <Say> verb to play a text-to-speech message. Save the bin and take note of its Request URL.

You are now ready to start the call using cURL:

curl -L -X POST 'https://{SpaceName}.signalwire.com/api/laml/2010-04-01/Accounts/{ProjectID}/Calls' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json' \
-u '{ProjectID}:{APIToken}' \
--data-urlencode 'Url=https://{BinRequestURL}' \
--data-urlencode 'From={+XXXXXXXXXX}' \
--data-urlencode 'To={+YYYYYYYYYY}'

Make sure to replace all occurrences of {SpaceName}, {ProjectID}, {APIToken}, {BinRequestURL}, {+XXXXXXXXXX}, and {+YYYYYYYYYY} with your actual values.

note

Instead of your own bin, feel free to try one of ours: <https://<spacename>.signalwire.com/laml-bins/f85376be-7fe1-439b-a24f-3113ff980804>.

Congratulations! Once the cURL request is executed, your personal phone number ({+YYYYYYYYYY}) will start ringing.

Receiving incoming calls

To handle incoming calls we need to configure the phone number in our SignalWire Space to answer calls using an XML bin.

Take note of the Request URL for the bin that we created in the previous section. You can even create a new bin if you want to define a different behavior for incoming calls.

Click the "Phone Numbers" section within your SignalWire Space, and select the specific number you would like to use to answer calls. The same number we used before can work.

In the Phone Numbers page of a SignalWire Space, a phone number edit pane is shown. 'Accept Incoming Calls' is set to 'Voice Calls'. 'Handle Calls Using' is set to 'LaML Webhooks'. 'When a Call Comes In' is set to the desired XML Bin URL.

To configure your number to handle incoming calls with an XML bin, set "Handle calls using" to "LaML Webhooks", then specify the URL of the XML bin.

Make sure that "Accept Calls As" is set to "Voice Calls", "Handle Calls Using" is set to "LaML Webhooks", and paste your Bin URL in as the value for "When a Call Comes In". Click "Save", and you're done! Inbound calls to this SignalWire number will execute the specified bin.

Wrapping up

XML bins allow you to program the behavior of phone calls, and REST APIs make it easy to trigger calls to any phone number. Find the documentation for our Compatibility API (XML and REST) here.

As we have seen, REST APIs are easy to get started with. In case you need more flexibility and real-time control on your calls, you may be interested in our guide about how to make and receive calls in Node.js.