SignalWire’s RELAY Realtime SDK has been out for a couple of months now, and we haven’t been shy about encouraging all of our customers to try it! In our May Fresh off the Wire blog, we announced that integration that now handles Voice, Messaging, Video, Tasks, and Chat. At that time, we suggested that users using our deprecated version of the RELAY SDK (v2) should upgrade to the latest version. Because Voice and Messaging were integrated into the existing Video and Chat version, only those two have syntax changes we should discuss.
Introduction
In both the old and new versions of the RELAY SDK, we do not pass our SignalWire phone number in the code for inbound calls and messages. Instead, we set a matching context in the Dashboard on the number we would like to use. This is done in the Phone Numbers tab by selecting “Edit Settings” on that number’s details page.
The RELAY Realtime SDK uses the same Dashboard settings that v2 used. The phone number of your choice will still be set to accept incoming calls and/or messages with Relay using the same context unless you choose to change the context name when you are refactoring.
The biggest changes from v2 to the Realtime SDK are no longer using a Consumer and only having asynchronous methods. If you haven’t already explored the documentation, here are some use case examples to get you started with refactoring. For our v2 examples, you will see Consumers and a mix of sync and async methods. For the Realtime SDK examples, you will see event listeners to detect ending events and top-level async wrappers. Comparing the two implementations will help us demystify the upgrade process.
Voice
SignalWire's Voice namespace has many available methods to help you build powerful and full-featured voice applications like Interactive Voice Response (IVR) call centers and automated appointment reminders. We will utilize several of these methods as we demonstrate how to make, receive, and record calls. We will even look at more complex methods like playing text-to-speech messages over an audio track. Then you can mix-and-match any of these methods to best suit your needs.
Making a Call
With the deprecated (v2) RELAY SDK, API calls were made through a Client, or often, a Consumer which was responsible for orchestrating calling and messaging events in real-time. This v2 example shows how you may have made a call with a Consumer.
The RELAY Realtime SDK does not use Consumers, but still uses a Client on the specific namespace you would like to access. You can visit our Voice Client SDK reference to see all of the available methods and events. Realtime client methods need to be awaited, so we will wrap our logic in an async top-level function. To initialize a call with this version:
Receiving a Call
When receiving a call with the deprecated (v2) RELAY SDK, we could use our Consumer to set up an event listener to listen for incoming calls. In this example, we would prompt the caller for a 3-digit pin and then, after successfully gathering the pin, hang up.
As we saw with outbound calling, inbound calls with this version do not require a Consumer but put a call.received listener directly on the namespace Client. You can also see the difference in the implementation of call.prompt with these two examples. It is no longer necessary to pass type: “digits” because promptTTS requires either config for digits or config for speech. You can see the full prompt documentation on our portal.
Recording a Call
For a slightly more advanced use case, let’s look at how we could update a Call Recording method. RELAY v2 SDK provided synchronous and asynchronous calling methods. For this example, we used the synchronous call.record method.
The Realtime SDK implementation does not have a synchronous method, so, we will listen for the end of the recording before moving on to the farewell message.
Playing TTS Over Audio
For our final Voice example, let’s look at how you might play a text-to-speech message while audio is playing in the background. In the old version of the SDK, playAudio was available as an asynchronous or synchronous function. To play TTS over music as we will in this example, we needed to use playAudioAsync which also allowed us to stop the audio at the appropriate time.
The new Realtime SDK can easily provide the same functionality with a simpler syntax. Because all of the methods are asynchronous, we will use waitForEnded when using the playTTS method. Playing the audio works just like it did in the deprecated SDK.
Messaging
Messaging is much less complex than Voice because the only interactive methods available are sending and receiving. So, let’s look at the differences in examples of outbound messages, inbound messages, and forwarding messages.
Sending a Message
In our v2 example, we used a RelayClient to send the SMS and, if successful, logged the message id.
Our latest version creates a messaging Client, sends a message using the same syntax, and returns a promise with a message result string rather than a success boolean.
Receiving a Message
With the old v2 version of the SDK, you would listen for incoming messages with a Consumer. If we wanted to send an automatic SMS response, we'd have to access the send method within onIncomingMessage with consumer.client.messaging.send.
The new Realtime SDK provides the same functionality with a simpler syntax.
Forwarding SMS
Finally, forwarding a message using the old SDK worked almost exactly like the incoming message handling above, but we stored more data from the incoming message and used it for the outbound forwarded message.
And with the Realtime SDK:
Conclusion
As you can see from all of the examples above, the new RELAY Realtime SDK introduces just a few minor changes from the old RELAY SDK v2. Some small syntax changes to an existing v2 application can make it easier to take advantage of all the namespaces and products SignalWire offers if you want to improve or expand your application in the future. A chat feature can trigger Voice calls, an IVR could allow a customer to call into a video call.
Here are a few resources for more technical references and examples:
We hope you can easily take advantage of new features as they are released, but if you need help, you can always reach out to Support with the help button on your Dashboard.