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 IoT projects or when you need a 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!

Forward calls to a context

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

To run the example a SignalWire Project ID and API Token are required.

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 only need to power your Pi 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 with 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 https://deb.nodesource.com/setup_16.x | 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="https://github.com/signalwire/signalwire-relay-examples.git" rel="noopener ugc nofollow" target="_blank">https://github.com/signalwire/signalwire-relay-examples.git</a>
cd signalwire-relay-examples/node/remote-announcements

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

SIGNALWIRE_PROJECT_KEY=<Your project id>
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.

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!

If you have any questions while you're working with SignalWire, be sure to join our Community Slack and Forum.