Skip to main content

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.

You can find your Project ID, Space URL, and API Token from the API tab in your SignalWire Space. Make sure your token has the necessary scopes enabled.

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.

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

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.

Ensuring message delivery

If you are sending messages to the US from a 10DLC number, you must register your traffic with the Campaign Registry. Otherwise, the carriers will not deliver your messages. Please see Campaign Registry - Everything You Need To Know for more information.

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'

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

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"

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"
}'

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.