Your First API Calls

In Getting Started without Code we have seen how to use the SignalWire platform without coding knowledge. Make sure you are familiar with the concepts explored in that guide before reading this one.

To take full advantage of all our services, you may want to use additional features that are only available via coding. This is what we will explore in this guide.

Your API Credentials​

To send messages, make phone calls, and programmatically control video rooms, you need API credentials. Find these in your SignalWire Space, within the "API" tab on the left sidebar. If this is the first time you are using API credentials, you will need to create an API token.

In the "API" section you will find all the information you'll need. In particular:

• Your Project ID (e.g., 7b981d06-fa9e-XXXX-XXXX-XXXXXXXXXXXX)
• Your Space URL (e.g., yourname.signalwire.com)
• Your API Token (e.g., PTda745ebXXXXXXXXXXXXXXXXXXXXXX)

The API Token is confidential: keep it private.

First API Calls​

We'll show an API call for Messaging, Voice, Video, and Chat.

• Jump to Messaging
• Jump to Voice
• Jump to Video
• Jump to Chat

Messaging​

Let's see how to send your first message. You have a few different options: you can trigger an HTTP request yourself (using cURL or the dedicated functions in your preferred programming language), or you can use one of our SDKs.

If you use cURL, you don't have any special set up to do. However, if you are going to use one of the SDKs, you'll first need to install them.

Installation​

npm install @signalwire/compatibility-api

pip install signalwire

composer require signalwire-community/signalwire

Once your environment is set up, you can proceed with your first API call.

Sending a message​

To send a message, you can use the Create a Message endpoint from our Compatibility APIs.

Let's see how to send a message with a REST API call:

curl "https://$SPACE_URL/api/laml/2010-04-01/Accounts/$PROJECT_ID/Messages" \
  -X POST \
  -u "$PROJECT_ID:$API_TOKEN" \
  --data-urlencode "From=$FROM_NUMBER" \
  --data-urlencode "To=$TO_NUMBER" \
  --data-urlencode 'Body=Hello'

const { RestClient } = require("@signalwire/compatibility-api");
const client = RestClient(PROJECT_ID, API_TOKEN, { signalwireSpaceUrl: SPACE_URL });

client.messages
  .create({ from: FROM_NUMBER, to: TO_NUMBER, body: "Hello" })
  .then((message) => console.log(message.sid))
  .done();

from signalwire.rest import Client as signalwire_client

client = signalwire_client(PROJECT_ID, API_TOKEN, signalwire_space_url = SPACE_URL)

message = client.messages.create(
                              from_=FROM_NUMBER,
                              to=TO_NUMBER,
                              body='Hello'
                          )

print(message.sid)

<?php
  use SignalWire\Rest\Client;

  $client = new Client($PROJECT_ID, $API_TOKEN, array("signalwireSpaceUrl" => $SPACE_URL));

  $message = $client->messages
                    ->create($TO_NUMBER, // to
                             array("from" => $FROM_NUMBER, "body" => "Hello")
                    );

  print($message->sid);
?>

Make sure to replace all placeholders with your own values.

This example used the Compatibility API. For more advanced, real-time applications, you'll want to check out our Realtime SDK. Find more details in the Messaging section of the developer portal.

Voice​

Let's see how to make your first PSTN call. You have a few different options: you can trigger an HTTP request yourself (using cURL or the dedicated functions in your preferred programming language), or you can use one of our SDKs.

If you use cURL, you don't have any special set up to do. However, if you are going to use one of the SDKs, you'll first need to install them.

Installation​

npm install @signalwire/compatibility-api

pip install signalwire

composer require signalwire-community/signalwire

Once your environment is set up, you can proceed with your first API call.

Starting a PSTN call​

To send a message, you can use the Create a Message endpoint from our Compatibility APIs.

Let's see how to start a PSTN call with the REST API:

curl "https://$SPACE_URL/api/laml/2010-04-01/Accounts/$PROJECT_ID/Calls.json" \
  -X POST \
  --data-urlencode "Url=http://your-application.com/docs/voice.xml" \
  --data-urlencode "From=$FROM_NUMBER" \
  --data-urlencode "To=$TO_NUMBER" \
  -u "$PROJECT_ID:$API_TOKEN"

const { RestClient } = require("@signalwire/compatibility-api");
const client = RestClient(PROJECT_ID, API_TOKEN, { signalwireSpaceUrl: SPACE_URL });

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

from signalwire.rest import Client as signalwire_client

client = signalwire_client(PROJECT_ID, API_TOKEN, signalwire_space_url = SPACE_URL)

call = client.calls.create(
                        url='http://your-application.com/docs/voice.xml',
                        from_=FROM_NUMBER,
                        to=TO_NUMBER
                    )

print(call.sid)

<?php
  use SignalWire\Rest\Client;

  $client = new Client($PROJECT_ID, $API_TOKEN, array("signalwireSpaceUrl" => $SPACE_URL));

  $call = $client->calls
                 ->create($TO_NUMBER, // to
                          $FROM_NUMBER, // from
                          array("url" => "http://your-application.com/docs/voice.xml")
                 );

  print($call->sid);
?>

Make sure to replace all placeholders with your own values. In particular, the URL to an XML file determines the behavior of the call. We first explored XML Bins in Getting Started without Code: refer to that guide for more information. You can even reuse the same XML bin!

This example used the Compatibility API. For more advanced, real-time applications, you'll want to check out our Realtime SDK. Find more details in the Voice section of the developer portal.

Video​

If you followed "Getting Started without Code", then you know how to create video rooms using the Space UI. In this section we will show how to do the same using API calls, so that you can automate the creation of video rooms.

We are going to create a room with UI included using the Create a Video Conference endpoint from our REST APIs:

curl "https://$SPACE_URL/api/video/conferences" \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "$PROJECT_ID:$API_TOKEN" \
  --data-raw '{
    "name": "my_room",
    "display_name": "My New Conference"
  }'

const axios = require("axios");

const response = await axios.post(
  `https://${SPACE_URL}/api/video/conferences`,
  {
    name: "my_room",
    display_name: "My New Conference",
  },
  {
    headers: {
      "Content-Type": "application/json",
    },
    auth: {
      username: PROJECT_ID,
      password: API_TOKEN,
    },
  }
);

import requests

json_data = {
    'name': 'my_room',
    'display_name': 'My New Conference',
}

response = requests.post('https://' + SPACE_URL + '/api/video/conferences', json=json_data, auth=(PROJECT_ID, API_TOKEN))

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://' . $SPACE_URL . '/api/video/conferences');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, $PROJECT_ID . ':' . $API_TOKEN);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(array(
  'name' => 'my_room',
  'display_name' => 'My New Conference'
)));
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));

$response = curl_exec($ch);

curl_close($ch);
?>

Chat​

SignalWire Chat APIs allows you to build modern and scalable chat applications. The best way to get started with chat is to follow our guide: Simple Chat Demo.

The guide will walk you through the creation of a basic chat application, but if you prefer to play directly with the end result, you can try our Live Demo on CodeSandbox.

Auto-topping up your account​

Auto Top-Up is a billing feature that allows you to add a card on file and specify a minimum balance. When your account balance reaches the minimum, your designated card will be automatically charged the amount you set.

For new accounts, Auto Top-Up will be enabled automatically with a $10 minimum top-up amount. For more information, check out Auto Top Up & Card Rejection Errors.