Call a Raspberry Pi using SignalWire Relay

Using SignalWire RELAY you can call your WiFi connected Raspberry Pi over the phone and leave messages for it to play on a speaker.

Developer Advocate Moheeb Zara

Using SignalWire RELAY you can call your WiFi connected Raspberry Pi over the phone and leave messages for it to play on a speaker.

SignalWire RELAY is an advanced interactive communications API that lets you build powerful applications using voice and SMS. It can run in the browser or server side. To dive deeper into RELAY, check our in-depth getting started guide.

While this NodeJS example can run on any machine with a speaker, we’ve run it on a Raspberry Pi, a low cost single board Linux computer. Raspberry Pi is great for internet of things projects or when you need computer for a very specific purpose.

This example demonstrates running a SignalWire RELAY Consumer. A consumer is a class that encapsulates the main connection and call handling features of RELAY. It can register with an arbitrary context. This context can be used to direct phone numbers to the consumer application in the event of voice calls or messaging.

Since the consumer can run directly on the Raspberry Pi, you can run all your call or SMS automation right at the edge. Here we use it so the Pi has immediate access to the call recording. The alternative would be your consumer is running in the cloud and you would have to send the recording result to the Pi using some IoT messaging platform.

Skipping that extra step opens the door to doing things like running an interactive voice response (IVR) that can interact with physical peripherals available to the Pi. For example, you call a number and are given some dial pad options to turn on the lights, get sensor information, or initiate party mode. Try experimenting after following this guide to see what else you can build!


To run this example you will need to first create a SignalWire account and then configure a SignalWire Space with an inbound phone number.

Configure SignalWire Phone Number to Forward Calls to a context

Once your account and inbound phone number is created, you need to edit the inbound phone number to forward calls to the context used by the Relay Consumer in this example, speaker.

API Credentials

To run the example a SignalWire Project ID and API Token are required.
Follow these intructions to create a new API Token.

Setting up the Raspberry Pi (Optional)

If you prefer, you can follow the general getting started instructions for the Raspberry Pi from the official documentation.

The following instructions are the steps we took to install an operating system to an SD card, configure WiFi and SSH access, and install NodeJS. This process is headless, meaning you need only power your Pi on and won’t need a monitor or keyboard.

  1. Use the Raspberry Pi Imager to install the Raspberry Pi OS Lite image to an SD card. Be sure to follow the Advanced Options to add your WiFi credentials, set a hostname, enable SSH, and create a user. (The common default user/password is no longer included for security purposes)
  2. Plug in a speaker of your choice to the Pi’s 3.5mm audio jack.
  3. Insert the SD card into the Pi, connect it to 5V USB power to turn it on.
  4. Open a terminal application such as iTerm or PuTTY.
  5. Create an SSH connection to the Pi using the user credentials and hostname created during the first step. In iTerm this can be done with the following command:
    ssh user@some-hostname.local
  6. Run the following commands to install NodeJS on the Pi
curl -sSL | sudo bash - sudo apt install -y nodejs

Your Raspberry Pi should now be connected to WiFi, accessible through SSH, and have NodeJS installed before proceeding to the instructions to run the RELAY Consumer.

Running the consumer

Clone the repository and navigate to this folder.

git clone <a href="" rel="noopener ugc nofollow" target="_blank"></a>
cd signalwire-relay-examples/node/remote-announcements

Create a file .env with your credentials and the verified phone number.

SIGNALWIRE_TOKEN=<Your api token>

Install the node modules.

npm install

Run the example.

npm run start

Call the phone number configured to the context for this consumer. It will play a text to speech prompt to tell you to record a message after the beep and press the pound key. Once you press the pound key it downloads and plays the recording using the default audio device!

Understanding the Code

All the code for the RELAY Consumer is in the consumer.js file.

First, we import the SignalWire realtime-api and create a new RELAY voice client using the credentials from the environment file. We also set the context here.

Then we create an event handler for incoming calls and play the text to speech prompt and a beep sound from an external URL.

After playback has ended we initiate a call recording. We create another event handler for when the recording has ended, which can be triggered by the caller pressing the “#” pound key. When that occurs we download the file and then use a third party library to play the file.

Thats all there is to it! The possibilities are endless when you can run all your voice and messaging automation at the edge. We hope you take what you’ve learned from this example and build something exciting! Be sure to share it with us and consider submitting to our code bounty program!

Here at SignalWire, we love our community of developers! Find us on the SignalWire Twitter and be sure to join our SignalWire Community Slack. We’re always happy to help answer questions and we look forward to engaging with you!

Related Articles