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
    • cXML 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)

Also, note that if your account is in trial mode, you'll need to upgrade it in order to call numbers other than your own verified numbers. See How to exit Trial Mode.

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.

The API page.

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.

Identify your Dashboard and select between Legacy and New UIs using the tabs below.

The main sidebar menu of the new SignalWire Space Dashboard UI.

The redesigned main menu.

The selection menu when a new Resource is created.

The new SignalWire Dashboard features a streamlined sidebar menu. Many items are now located in the unified My Resources menu.

Resources that were previously accessible in the sidebar of the legacy UI are now located in the unified My Resources menu.

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 in the new UI, go to the "Resources" section from the sidebar, and create a new Resource. In the new resource picker, select "Script" and create a "SWML Application".

Attach Phone Number
version: 1.0.0
sections:
  main:
    - play: say:Hello from SignalWire!

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:

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

Making your first call​

Outbound calls can be made via The SignalWire REST API's Create a Call endpoint. This is accomplished by sending a POST request with SWML in the body to handle the call. The SWML can be served via URL or passed inline directly.

curl -L -g 'https://Your_Space_Name.signalwire.com/api/calling/calls' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic YOUR-PROJECT-ID:YOUR-API-TOKEN' \
--data-raw '{
  "command": "dial",
  "params": {
    "from": "sip:from-sip@example-112233445566.sip.signalwire.com",
    "to": "+1xxxxxxxxxx",
    "caller_id": "+1234567890",
    "fallback_url": "https://example.com/fallback",
    "status_url": "https://example.com/status_callback",
    "status_events": [
      "answered",
      "ended"
    ],
    "url": "https://example.com/swml"
  }
}'

Compatibility API​

Receiving incoming calls​

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

If you're on the new UI, go to the "Resources" section from the sidebar, and create a new Resource. In the new resource picker, select "Script" and create a "cXML script".

Attach Phone Number

Utilize the following cXML which uses the <Say> verb to play a text-to-speech message:

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

Go to the "Phone Numbers" section from the sidebar, and edit the phone number you want to answer calls with. From there, click on the "Assign Resource" button for incoming calls, and select the newly created cXML script to connect.

Attach Resource

Making your first call​

To call a number via cXML you can make a POST request to the Compatibility REST API's Create a Call endpoint.

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.

In order to locate the {BinRequestURL}, navigate to your cXML script and copy the Request URL that is present.

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.

Wrapping up

cXML 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.