Forem: Julia Biro

Introducing the Vonage Voice API on Zapier

Julia Biro — Thu, 21 Jan 2021 17:01:56 +0000

Some of you might already be familiar with our SMS API integration in Zapier. It allows you to trigger a Zap when receiving an SMS, or send an SMS message as an action—for example, a reminder or notification of sorts.

In this article, we're exploring the Voice API integrations, the various events it offers, and we'll learn how to add more versatile ways of communication to your workflows.

The Vonage Voice API

The Vonage Voice API allows you to make and receive phone calls. It also comes with some nifty features like reading out a text-to-speech message, streaming an audio file into a call, forwarding, or placing a call leg into a conference.

Zapier 101

Zapier is an online automation tool that connects your favourite apps. It empowers users to build their workflows with just a few clicks, connecting two or more apps to automate repetitive tasks.
Find an overview of the key concepts and getting started guides in the Zapier Learning Center.

A Zap is a workflow created in Zapier. Each Zap consists of a trigger and one or more actions. Once turned on, it will run the action steps every time the trigger event occurs.

The Vonage Voice API integration has eight events: four triggers and four actions. The triggers will set your workflow off when someone rings your Vonage number, while the actions will initiate an outbound call.

An app is a web service or application, such as Airtable, Google Docs, or Vonage. There are over 2,000 apps you can connect to Zapier.

Vonage Voice API Triggers

A trigger is an event that starts a Zap. Once you've set up and turned on your Zap, Zapier will monitor for that specific event.

Based on the type of monitoring, there are two types of triggers:

polling: the majority of triggers are polling triggers. Zapier will check for new data from your trigger every 1 to 15 minutes, depending on your pricing plan.
instant: your trigger app will send Zapier an instant notification whenever there's new data.

All Vonage Voice triggers are instant triggers and will start your workflow when an inbound call reaches one of your virtual numbers.
These triggers will start your Zap and determine what happens to the incoming call before we move on to adding an action.

New TTS Call will read out a text-to-speech message to the caller.
As an example, you could use this trigger to greet the caller and let them know you'll get back to them during working hours, then add an action node to save their phone number into a spreadsheet.

New Stream Call works similarly, except it plays an audio file into the call instead of the text-to-speech message. Add a personal touch to the previous example and record a voice message to be played back to the caller.

New Forwarded Call will forward the incoming call to a predefined phone number of your choice.
For example, you might choose to forward calls to your cell phone only during working hours.

New Conference Call will place all callers into the same conference call.
You could use this trigger to set up a dial-in meeting.

Vonage Voice API Actions

All Vonage Voice API Actions create an outbound call.
While you wouldn't necessarily connect them after a Vonage Voice API trigger, they work quite well with a series of instant triggers.

Create Text to Speech Call will read a text-to-speech message to the recipient, which could be a good fit if you're looking to escalate your notifications. While one might easily dismiss an SMS message, a ringing handset commands immediate attention.
For example, connect it to a scheduler trigger to be reminded when to take your meds.

Create Stream Call conveys the same level of urgency, but gives your message a personal touch. Instead of the text-to-speech message, an audio file gets played into the outbound call.
An elderly relative might find comfort in a familiar voice, reminding them of their medication, while they might be less appreciative of your friendly neighbourhood robot.

Create Two-Way Call will take two phone numbers of your choice as input, then ring both of them and place them in the same call.

If you're looking to create a call with more participants, use the Create Conference Call action. It creates an outbound call to a number of your choice, then places that call leg into a conference call. Add an action for each call recipient and make sure you're joining them to the same conference.

Where Next?

Start building today and let us know how it goes!

If you have any questions, advice or ideas you'd like to share with the community, please feel free to jump on our Community Slack workspace. I'd love to hear back from you.

Using Variables and Chaining Requests in Postman

Julia Biro — Mon, 19 Oct 2020 13:29:31 +0000

At Vonage, we use OpenAPI to describe all our APIs, and we also make those specifications publicly available.

One of our favorite things to do with an OpenAPI file we haven’t seen before is to import it into Postman. Therefore, we’ve decided to pay it forward and create a Postman Collection for our APIs so that evaluating and exploring them is quicker and easier than ever.

In this article, we highlight how you can make exploring your APIs in Postman even more approachable. We’ll be using The Vonage APIs Postman Collection as an example, so make sure to go through the prerequisites list if you want to follow along.

Prerequisites

Variables are Your Friends

When you first import the Vonage APIs Collection into Postman, you’ll see a Vonage APIs folder appear under Collections on the left-hand side of your screen.

You might also notice the “36 requests” under the collection name. Depending on the auth type, that is more or less 36 times someone would have to add api_key and api_secret as request parameters.

Fortunately, Postman supports environment, global and collection-level variables, which will all make the experience a lot more smooth and less painful. Instead of performing repeated tasks, such as filling in the same parameter values for every request, these variables enable us to pull those values in dynamically.

Our collection comes with a Vonage Environment where you can provide your key and secret, and then all requests will use those values moving forward.

This way, making a simple request like checking your account balance with the Account API becomes a one-click job.

Some other requests may need additional parameters. For example, to Send an SMS, you’d need to fill in to, from and text in the request body, but api_key and api_secret would still be auto-populated.

You may also choose to add any of these parameters as variables, like the to number has been saved as a collection variable in the request featured below.

You can achieve this by either editing your collection or environment directly, or by selecting the hardcoded value you’d like to replace with a variable, and clicking Set as variable > Set as a new variable.

Chaining Requests

Variables in Postman are great, but they aren’t a universal tool for fixing every cumbersome thing.

For example, when using one of the Vonage APIs that authenticates using JWTs, you’ll need to generate that JWT before making your request. To generate the JWT, you’ll need an application ID and a private key, both of which you’ll get once you create a Vonage Application. That amounts to three separate requests one would have to make, which can confuse someone exploring the API for the first time.

Fortunately, there’s a workaround for multi-step prerequisites as well: chaining requests.

Postman offers two scripting areas, Pre-Request Script and Tests , where you can write any JavaScript code you’d like-yes, including making another HTTP request as well.

The Pre-Request Script

The Vonage Voice API authenticates using JSON Web Tokens (JWTs), so to send a Create an outbound call request, we’d first need to:

Create a Vonage Application using the Applications API
Grab the application_id and private_key values from the response object and use them to generate a JWT.

// Check if we already have a JSON Web Token, continue if not
if (!pm.environment.has("JWT")) {
    var btoa = require('btoa')
    let base64keyandsecret = btoa(`${pm.environment.get("api_key")}:${pm.environment.get("api_secret")}`)

// (1) Create a Voice Application by making a request to the Vonage Applications API
    pm.sendRequest({
        url: 'https://api.nexmo.com/v2/applications',
        method: 'POST',
        header: [`Authorization:Basic ${base64keyandsecret}`, "Content-Type: application/json"],
        body: JSON.stringify({
            "name": "Demo Postman Application",
            "capabilities": {
                "voice": {
                    "webhooks": {
                        "answer_url": {
                            "address": "https://example.com/webhooks/answer",
                            "http_method": "POST"
                        },
                        "event_url": {
                            "address": "https://example.com/webhooks/event",
                            "http_method": "POST"
                        }
                    }
                }
            }
        })
    }, (err, res) => {
// (2) Generate JWT using the application ID as a claim and sign it with the private key
        pm.sendRequest({
            url: 'https://jwtapi-dev.netlify.app/.netlify/functions/generate',
            method: 'POST',
            header: ["Content-Type: application/json"],
            body: JSON.stringify({
                algorithm: "RS256",
                private_key: res.json().keys.private_key,
                claims: {
                    application_id: res.json().id,
                    exp: parseInt((Date.now() / 1000) + 3600, 10)
                }
            })
        }, (err, res) => {
            pm.environment.set("JWT", res.json().signed_jwt)
        })
    })
}

Tests: Why Not Post-Request Script?

Postman allows you to add tests to individual requests, folders and collections. While these tests are immensely useful in ensuring that your API is behaving as expected and for debugging purposes, here’s a kicker: Tests are JavaScript scripts that get executed after a request has been made.

This means that the way we used the Pre-Request Script, we could make the most of the Test area too.

In our voice call example, on successful completion, I am saving the voice_call_uuid as a collection variable using the pm.collectionVariables.set() function. This variable will come in handy should I decide to make other requests involving the Voice API. Alternatively, on failure, I am clearing the JWT value using the pm.environment.unset("JWT") expression so that I can send my request again and generate a new JWT.

 if (pm.response.code == "201") {
    pm.collectionVariables.set("voice_call_uuid", pm.response.json().uuid);
} else {
    pm.environment.unset("JWT")
}

Read more about defining variables in scripts in the Postman docs.

The Request Body

Finally, let’s put this all together to make a text-to-speech voice call.

You may use the snippet below and provide the to and from as either variables or hardcoded values. Keep in mind that to is the destination number you’re about to call, and from is one of your Vonage numbers. Get one in your dashboard if you haven’t already.

The NCCO is our Call Control Object, which lists all actions to be taken once the call is answered. Check out the NCCO Reference and see what other actions you could include in your call flow.

{
    "to": [
        {
            "number": {{to}},
            "type": "phone"
        }
    ],
    "from": {
        "number": {{from}},
        "type": "phone"
    },
    "ncco": [
        {
          "action": "talk",
          "text": "This is a text to speech call from Vonage"
        }
      ]
}

This request is now good to go, so push that Send button. Congratulations! And you know what the best part of all this is? If you save your changes and Share Collection, the next person will only have to fill in the missing variable values and press the Send button.

How would you use these handy Postman features? Got any tips and tricks? Let us know; we’re looking forward to seeing what you come up with!

Where Next?

The post Using Variables and Chaining Requests in Postman appeared first on Vonage Developer Blog.

Announcing the Vonage APIs Postman Collection

Julia Biro — Wed, 16 Sep 2020 10:53:56 +0000

At Vonage, we publish OpenAPI specifications for all our APIs. These specs enable our developer community to explore, evaluate, and integrate the Vonage APIs efficiently.

As Lorna mentioned in her article on evaluating APIs using OpenAPI, downloading an OpenAPI Spec and exploring it in Postman is a great way to familiarize yourself with new APIs.

I couldn’t agree more! If you’re not already familiar with Postman, it’s a friendly graphical interface to a powerful cross-platform HTTP client that I encourage you to try.

We’re excited to announce that exploring the Vonage APIs has just gotten even quicker and easier! We’ve added a “Run in Postman” button to the Postman page on our developer portal, so now you’re only a couple of clicks away from making your first request.

It is also discoverable on the main Postman network if you’d rather browse it there.

Once you click on the Run in Postman button, you’ll be taken to your Postman instance of choice, and all of the Vonage API Calls will be waiting for you, nicely organized into a collection.

A great thing about using a Postman Collection is that we can prepare the requests for you, so there’s minimal work involved in making the API calls.

It also has some neat features, like the ability to configure environment variables. This collection comes with a Vonage Environment that lists API_KEY, API_SECRET, and JWT, which are the most commonly used parameters, but feel free to add others as you go. You can find the environments by clicking the cog icon in the top right-hand corner.

To add your credentials, update the current values of API_KEY and API_SECRET with the API key and secret found in your Vonage dashboard (no need to set up JWT for now).

Using the Vonage APIs Postman Collection

Next, let’s have a closer look at using the Vonage APIs Postman Collection to explore the Numbers API.

Expand the collection folder and find the Numbers folder inside it.

Vonage’s Numbers API allows you to manage your virtual number inventory programmatically. To find out more about the available operations, make sure to check out the Numbers API Reference.

For this example, let’s try out the List numbers you own entry.

Your api_key and api_secret will be pulled in dynamically from the Vonage Environment, so double-check that you’ve set those values in the environment, then click send.

Et voilà! You’ve successfully made your fist Vonage API request using our Postman collection!

Give it a try, have fun, and let us know what you think!

Where Next?

The post Announcing the Vonage APIs Postman Collection appeared first on Vonage Developer Blog.

Build a ‘Clock in’ Service With the Shortcuts iOS App

Julia Biro — Thu, 27 Aug 2020 13:27:54 +0000

Years ago people didn’t have phones, places did.

When trying to get ahold of somebody, you’d ring different places. They’d say the person isn’t there, so you’d move on to calling the next place and the next, and then the next one. Until you’d have either reached the person or given up in the process.

Mobile communications flipped that on its head, and now we phone people because everybody has a little device. We can call a friend and talk to them, no matter where they are. Which is excellent for the majority of the use cases we find ourselves in.

However, sometimes we do want to phone a place rather than a person. And we don’t care who we speak to, as long as we get through to someone who’s there.

Offices, shared houses, warehouses, equipment sites, etc. could benefit from that painful process from 20 years ago.

In this tutorial, we’re going to use the Shortcuts iOS app on an iPhone to bring that back, this time without having to install landlines. You’ll be able to call the phone number of the place, and that will automatically be re-routed to whoever is in at the time of the call.

Prerequisites

Shortcuts app installed on an iPhone or an iPad running iOS 12 or later
Vonage Account

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

What Is Shortcuts?

The Shortcuts app allows you to quickly automate repetitive tasks directly on your iPhone and iPad without the need to write code.

You can find hundreds of examples in the Gallery or build your own with just a few taps.

Actions

Each Shortcut comprises a series of actions.

An action is the building block of a Shortcut, a single step that performs a particular function.

Browse the over 300 built-in actions and use them with apps like Contacts, Calendar, Maps, Music, Photos, Camera, Reminders, Safari, Health, or any other app that supports Siri Shortcuts.

Once your Shortcut is ready, you can launch it from the Today widget, from Search or by asking Siri. You can even add an app icon to your home screen for your favorite Shortcuts.

Build Your Shortcut

1. Get a Virtual Number

You’ll need a virtual number to list as a contact number. We will later forward calls from this number to a personal phone number.

In case you already have a Vonage number you’d like to use, find it under Numbers > Your Numbers in your Vonage dashboard. Click on the pencil icon and make sure it is not already in use—settings will be overwritten by the next steps. If all voice config fields are blank, you’re good to continue with creating your Shortcut.

Alternatively, go to Numbers > Buy Numbers and get a voice-enabled number. You can filter the search results by checking VOICE in the Feature drop-down. Pick one from the returned results, click Buy next to it and make a note of it as you’ll need it in the next step.

2. Create a New Shortcut

Next, move on to your mobile device.

Once you have the Shortcuts app installed, please open it and click on the + Create Shortcut button to get started on a new Shortcut.

3. Action 1: Ask for Input

The first action is collecting the user’s phone number as text input.

Click on the + Add Action button, then in the Scripting category under Notification select Ask for Input. Tap on the Question field and fill in the text you’d like to appear to the user when running this Shortcut. For example, “Set on-call number to:”. Next, tap on Show More and make sure the Input Type is text.

Click the + sign to add a second action.

4. Action 2: Get Contents of URL

Next, you’ll set up the call forwarding from the Vonage virtual number to the one collected in Action 1.

To achieve this, you’ll need to make an HTTP request to the Numbers API and update the number that incoming calls should forward to.

In Shortcuts, as a second action, select Get Contents of URL from the Web Requests section of the Web category.

Fill in the action so that it reads:

Get contents of https://rest.nexmo.com/number/update?api_key=YOUR-API-KEY&api_secret=YOUR-API-SECRET, replacing YOUR-API-KEY and YOUR-API-SECRET with your API key and secret found in your Vonage dashboard.

Next, click on Show More, select POST as a Method and Form for Request Body. You’ll have to add four text fields to the Request Body, as follows:

Key	Description
country	The two-character country code in ISO 3166-1 alpha-2 format. For example, GB for Great Britain.
msisdn	Your Vonage virtual number in E.164 format. For example, 447401234567.
voiceCallbackType	Type `tel` to indicate that you’re forwarding calls to a telephone number.
voiceCallbackValue	Select `Provided Input` from the suggested Variables list. This will be the personal number captured in Action 1.

You’re all set to test your Shortcut! Click Done, then the ▶ button to test it out! Submit your personal number when prompted, then ring your virtual number to see the call forwarding in action.

5. Action 3: Append to File

As the final step, let’s create a log of all submitted numbers to keep track of all people that had been on-call.

Click the + sign to add a third action, then under Documents select Append to File in the File Storage section.

After the Append keyword, select Provided Input followed by a filler text like “clocked in on”, then select Current Date with your preferred time and date formats. Choose between iCloud Drive and Dropbox as a Service, then fill in the File Path field and make sure that the Make New Line option is enabled.

Finally, click Done and run your Shortcut. Add it to your Home Screen or keep on building it! Let us know how it goes!

The post Build a ‘Clock in’ Service With the Shortcuts iOS App appeared first on Vonage Developer Blog.

Get a “Beautiful Morning Weather” alert with Zapier and Vonage

Julia Biro — Mon, 13 Jul 2020 13:31:34 +0000

During the past couple of months, most people’s lives and routines took a turn for the unexpected, and mine was no exception.

The rhythm I’d gotten into suddenly wasn’t there anymore, and I’ve found myself in desperate need of bringing some structure back into my day-to-day.

My first action item was to reconquer my mornings and start the day on the right foot. I’ve found taking early morning walks in the sunshine quite uplifting. Throw in an audio book and it gets even better. Afterward, I’d feel energized and having already crossed off two items of my to-do list—exercise and reading, I’d be confident to tackle my day.

Unfortunately, I found rainy, windy and cold British weather powered morning walks more depressing than uplifting. I’d always wish I had slept in for an extra hour, or simply curled up on the sofa with my morning coffee and a good book.

Waking up early just to be disappointed was leaving me disheartened. Not the start to the day I was looking for.

If only there was an alarm clock that would only wake me up if the outdoors were welcoming, right? Right.

In this tutorial, we’ll build a Zapier workflow (Zap) that pulls real-time weather data at a scheduled time, then based on our preferred parameters, gives us a wake-up call only if the requirements are being met.

Prerequisites

Before we get started, you’ll need a couple of things:

– a Zapier account

– a Vonage account

Vonage API Account

A Word about Zapier

What is Zapier?

Zapier is a low-code tool that allows you to connect your favorite apps and services. It enables you to automate repetitive tasks without coding or relying on developers to build the integrations between two or more different services.

To find out more about Zapier, visit their Getting Started with Zapier guide.

Common Terms: Learn to Speak Zapier

Zap

A Zap is an automated workflow that performs repetitive tasks for you. It is the finished product that you’re building, and it consists of at least two parts: a trigger (every day at 6:30am) and one or more actions (get weather data, then make a call).

Trigger

Each Zap starts with one trigger.

A trigger is the event that sets off the Zap. Once you finish and activate a Zap, Zapier will monitor the app for that event. (Your Zap will only be triggered at 6:30am every morning)

Action

An action is an event that happens when your Zap is triggered. In our case, retrieving the weather data is an action. So is filtering the weather data, and making a phone call

Task

Each piece of data you run through your Zap counts as a task. That means, if your Zap sends out an SMS notification to 100 people, your Zap just performed 100 tasks. It’s worth having the number of tasks your Zaps run in mind, as this helps determine which Zapier plan is best suited for your needs.

Build Your Zap

For this Zap, we’ll be using a couple of built-in Zapier apps:

– Schedule by Zapier as our trigger.

– Weather by Zapier as the first action to get weather data.

– Filter by Zapier as the second action to define the conditions under which we want the Zap to execute the following steps.

Then we’ll have a look at two of the Vonage integrations:

– Vonage Voice API to make the wake-up call.

– Vonage SMS API to deliver weather data to your handset via SMS.

To get started, click the Make a ZAP button on the top left corner of your Zapier dashboard page.

The Trigger: Schedule by Zapier

First, select Schedule by Zapier from the list of available built-in apps.

This app offers three trigger events, based on how frequently you’d like your Zap to be run. In this case, select Every Day for a daily reminder.

Next, you’ll be prompted to customize the time of the day you’d like your Zap to be triggered.

Specify whether you prefer it to run on weekends or not, by selecting yes or no from the drop-down menu.

As for the Time of Day, either select a value from the drop-down menu or click Custom and type the desired value. For example, 6:32am.

Finally, Zapier will try to find test data for this event and you’ll be presented with a set of test data. Have a look at these fields and make a note if you find any of the parameters interesting, you’ll be able to pull them in dynamically in later steps!

Click Continue to move on to the next step.

Action 1: Get Weather Data with Weather by Zapier

The first action is getting weather data, and we’ll be using Weather by Zapier powered by Dark Sky to accomplish that. Head over to the Dark Sky docs to find out more about all the data that is being returned by their API.

To configure this action, first select Get Current Weather as an Action Event.

In the Customize Current Weather section you’ll have to fill in the coordinates of your location as Latitude and Longitude as well as whether you prefer the temperature data to be sent in Celsius or Fahrenheit.

LatLong.net is a handy website that returns latitude and longitude for any location of your choice.

Next, press Test & Continue.

Have a look at the test data and think about what parameters you could use to set your wake-up conditions. Would you like to be woken up only if the temperature is over a certain level? Maybe you have an issue with rain but love snowfall. Can’t stand the wind blowing in your face and it pouring down at the same time? Me neither!

Shop around and see what matters to you the most. When you’re ready, click the + sign to get started on the next action.

Action 2: Set Conditions with Filter by Zapier

At this point, we have all the data required to make an informed decision about going out for a walk or curling up on the couch.

Next, let’s describe the case when you’d be up for a walk. What would the weather be like?

We’ll use Filter by Zapier to set up our weather requirements. The Zap will only continue to run if these conditions are being met.

In this example, I picked Precip Probability (the chance it will rain) being less than 0.1 (10%), and Apparent Temperature (the temperature outside) greater than 0 (0 degrees celsius).

Go ahead and have a play with it, create a couple of Only continue if… rules. To add a new condition, click either the + AND or the + OR button, depending on whether you’d like both (or all) conditions met for the Zap to continue running, or you’d be happy to wake up in case any of your conditions evaluate as true.

If at any point you’re unsure of the type of the weather properties or their format, check out the Dark Sky docs where each of the parameters is described in detail.

Once you’re happy with your filter conditions, click the + button to move on to the next action.

Action 3: Create Call with Vonage Voice

Start by searching for and selecting Vonage Voice API as the app for the third action.

Next, select an Action Event to determine how the call progresses.

For this example, we’ll choose Create Text to Speech Call to have a templated message read out to us once the call comes through.

Alternatively, you could go with Create Stream Call to have your favorite tunes streamed into your wake-up call, Create Two Way Call to have the Zap call both you and a second person, placing the two of you into the same conversation.

Some of Vonage’s APIs, including the Voice API, use Vonage Applications to hold security and config information needed to connect to Vonage endpoints.

When prompted to provide your credentials, fill in your API key and secret found in your dashboard, then pick a name for your Vonage Application. Zapier will create this application for you, and you’ll be able to find it in your Vonage account under Your applications going forward.

Finally, you’ll have to set a couple of parameters for the text-to-speech call.

Select one of your virtual numbers from the Number You Want To Use For Caller ID drop-down. This number will appear on the screen of your handset when the call goes through.
Key in the Number You Want To Call in E.164 format. For example 447401234567.
Notice that the Content Of The Message To Read field allows templating. This means that you can mix plain text with dynamic properties from previous steps. Remember all the weather data that came through? Yes, any of that. Take a moment and build the message that you’d like to wake up to. Have a look at the image below for some inspiration.
Choose a Voice name from the drop-down menu to give your message some personality. I’ll go for Nicole, en-AU, female.

When you’re ready, click Continue and test your Zap.

Congratulations! Your Zap is ready to go, turn it on and rest assured that you won’t miss a beautiful morning walk again!

Extra Credit

Action 4: Send Weather Data with Vonage SMS

I try not to be any fussier about my mornings than necessary; clothes on, coffee in hand, go, but sometimes it might be helpful to know whether that inviting morning sunshine comes with 5°C or 25°C attached.

We already have all the weather data from Zapier’s built-in app, so it only takes one extra step to pick the entries we’re interested in and have them delivered via SMS to our handset.

Click on the + button to add another action and search for Vonage SMS API.

Next, select Send SMS as the Action Event and continue.

Provide tour API KEY and API SECRET in the pop-up window to authenticate with the SMS API. Find these credentials in your Vonage API dashboard.

Next, you’ll have to fill in a couple of details:

From: the number or text shown on a handset when it displays your message. You can set it to a custom alphanumeric value like “Weather Zap” if this feature is supported in your country.
To: the number you are sending the SMS to in E.164 format. For example 447401234567.
Text: the content of your SMS message. Feel free to use templating just like in the text-to-speech call action. For example, I was interested in a weather summary and the apparent temperature—see image below.

When you’re done, test your Zap and turn it on!

What’s Next?

Fancy trying another tutorial?

– Text When You Get Home Safely with Zapier

– Send SMS Confirmations for New Stripe Charges with Zapier

– Send SMS Reminders of Google Calendar Events with Zapier

What will you build next? Let us know!

The post Get a “Beautiful Morning Weather” alert with Zapier and Vonage appeared first on Vonage Developer Blog.

I'm Julia, and We Deserve to Be Here

Julia Biro — Mon, 09 Mar 2020 15:02:23 +0000

I'm Julia, and I rarely eat breakfast.

I've heard it's the new health thing - never got the memo.

It's 9:30, and I've got a knot in my stomach. It goes away for a while, then back again at 10:00. 10:30.

Geekbot wants to know what I accomplished yesterday - which is great, except when you feel like you have nothing to account for.

This isn't a strange feeling though, we've been together for a while.

It comes around every time I'm asked what I do for a living. I'm a freelancer, a contractor, I have my own company, I work for an API company, I work in DevRel, I'm the one doing the avocado drawings. The two words you've probably never heard me utter is "designer" and "developer". If I ever have to state my work title, I make sure to put a well emphasized "junior" in front of it. People form expectations when they hear the specifics, and I'm not ready to be measured against them.

Hand me a project or ask me to do something for you. I'll try, I'll have a look, or I'll give it a go. And I most sincerely mean it - I'll set it as my goal, I'll try to accomplish it, I'll give it everything I have and some. What I'll rarely do is make a promise. A promise is a commitment to an end result I'm not confident I can achieve.

Looking back at my time spent at uni, I most vividly remember the only thing I tried to forget.

I'd always been fascinated by computers and had gone for the computer science courses at school. Soon it was time for higher education and I found myself at a technical university, eagerly heading to what I thought would become the highlight of my year - my first ever hardware workshop.

I stepped into a lab full of dismantled computers and random electronics dating back to the 70s. I was in such awe of it all that I completely missed the first ten minutes of the presentation. The daydream didn't last much longer, as my professor's words cut through it: "Pretty faces like you don't belong here".

I brushed it off at the time and moved on.

As the years went by, the pretty face has faded, I can't remember his name or face anymore, but it turns out, "you don't belong here" stuck with me.

I Deserve Credit for...

However, I do deserve credit for realizing that no matter how down you feel, there's still plenty you can do to make a difference.

Regardless of where you are in your journey, it's always worth looking back as you keep on climbing. I promise there will be someone behind you. See if they need a hand!

In 2020 I Continue to Code

Last year I started experimenting with low code, then gathering my thoughts and learnings into blog posts.

Enabling people who wouldn't open up a terminal or IDE to still build out their ideas, is extremely rewarding. It's like living in a series of first "Hello World!" moments while witnessing countless ideas come to life.

In 2020 I continue to code so that more people can code too.

I Hope to See...

It's truly amazing to be part of a supportive community that strives for inclusivity. I'm also incredibly proud of my colleagues for empowering the community to be the change we all need. It's heartwarming to read through the #shecoded and #shecodedally posts, and I recommend you check them out too.

I hope to see this approach applied to different abilities and skill levels, and I hope to see the demystification of the tech industry.

It's 2020, it's time we got rid of the gatekeeping.

Yes, code can be hard, complicated, frustrating, and nerve-wracking, but it can also be fun and rewarding. That's quite a handful of adjectives in there, no need to add scary to them.

My Message for Others

We are fortunate enough to work in an industry where there is space for literally everyone. Let's welcome others and help them discover the parts that keep us all here!

Happy International Women's Day, everyone! 🎉

Sending Group Notifications with Google Sheets and Node-RED

Julia Biro — Fri, 06 Mar 2020 13:16:53 +0000

Ever got a phone call at 7:59 AM telling you your kid’s school is closed? It was handy, as you were only a couple miles away – on your way home, after dropping them off.

The announcement process in most schools is still manual nowadays, which works in most cases. When something unexpected happens though, like the school is snowed in, a handful of people scramble to call hundreds of parents. You might get the notification in time, or you could be part of the lucky bunch that ended up in the last batch at 7:59.

In this tutorial we’re going to build a Node-RED flow that programmatically sends out notifications to a list of contacts, using Google Sheets and the Nexmo SMS API.

Follow along and pitch it to the principal? Saves you being stuck in traffic on a snow day.

Prerequisites

Before getting started, you’ll need a few things:

A Node-RED installation, be it a hosted version or on your machine
A Google account
A Nexmo account — create one for free if you haven’t already
A way to expose your server to the internet. This either means you’re running a hosted version of Node-RED or using a tunneling service like ngrok – get up to speed with this Getting Started with Ngrok in Node-RED tutorial

Setting Up Your Editor

Once you open your Node-RED Editor, make sure you have the following packages installed:

To do this, click on the hamburger menu, select Manage Palette. Check for already installed packages under Nodes, and get new ones from the Install tab.

When you’re done, make sure to restart Node-RED and you’re good to go!

Configuring Your Google Account

To interact with the Google Sheets API, you’ll need to use a service account – an identity that an instance can use to run API requests on your behalf. It will be used to identify apps running on your instance to other Google Cloud services.

In this case, your flow that reads a Google Sheet must first authenticate to the Google Sheets API.

You’ll have to create a service account and grant it access to the Google Sheets API. Next, update your app to pass the service account credentials to the Google Sheets API. This way, your flow authenticates seamlessly to the API without embedding any secret keys or user credentials.

Step 1: Create a New Service Account

We’ll start by creating a new project on the Service Accounts Page of the Google Cloud Platform. Click on CREATE to get started.

Next, give your project a name, either select an organization or leave it blank, then press CREATE.

You’ll shortly see a notification pop up that your project has been created.

Now that you have a project, let’s add a service account to it!

Next, you’ll need to create a key that you’ll use to authenticate with the GSheet node in your flow. Click on Create Key, then select JSON as a key type. Save this file when prompted – keep it handy as you’ll need it soon, then hit Done.

Step 2: Enable Google Sheets API for Your Project

From the hamburger menu select APIs and Services -> Dashboard, then click the ENABLE APIS AND SERVICES button. Look for the Google Sheets API in the API Library, open it and click Enable.

Step 3: Sharing Google Sheets with Your Service Account

Go to the Service Accounts page and make a note of the email address associated with the service account you’ve just created. You’ll need to use this email address to share your spreadsheets with the Service Account.

Sending Group Notifications with Google Sheets and Node-RED

Create a Spreadsheet

In case you don’t have a Google Sheet ready, go ahead and create one now.

Google Sheets use a cell-matrix system, where each column can be identified with a letter (starting with A as the first column) and rows are numbered (1 being the first row). In case you’d like to select the second element of the first row, this would be B1.

You can also select ranges of cells by using the TOP_LEFTMOST_CELL:BOTTOM_RIGHTMOST_CELL notation. For example, to select the second and third element of rows 1-5, use B1:C5.

After creating a spreadsheet you’ll see a Sheet1 tab at the bottom of the screen, which is the worksheet you’re currently one. You can rename it or add more worksheets to your spreadsheet.

For this tutorial, I’m using one worksheet with 4 columns: Name, Surname, Phone, and Email – you’ll need at least 2 rows of data to follow along.

Make sure you add a phone number you have access to, so that you can test your flow later on.

Once your spreadsheet is ready, it’s time to share it with your Service Account.

Getting the Data from Your Google Sheet

Start your flow by adding a GSheet node to your workspace. Configure this node to pull in the data from your Google Sheet by filling out the following fields accordingly:

PARAMETERS	DESCRIPTION
Creds	Press the edit button to provide your Service Account key. Remember the JSON file you downloaded earlier? Copy and paste this JSON key in the text field.
Method	Select Get Cells from the drop-down menu. This will grab the data from the Google Sheet and pull it into your flow.
SpreadsheetID	You can figure out your spreadsheet ID from the URL of your Google Sheet. For example, if the URL is https://docs.google.com/spreadsheets/d/1mmXhj40aeSooxmtku3ma4auLyrHhO8xCSQsklZ1_BU/edit#gid=0, the SpreadsheetID will be the string found in between `d/` and `/edit`: 1mmXhj40aeSooxmtku3ma4auLyrHhO8xCSQsklZ1_BU. Have a look at your spreadsheet URL and find your SpreadSheetID. Then paste this string in the SpreadSheetID field.
Cells	Select the cells where your data is located on the spreadsheet. In the example below, this value will be: `Sheet1!A2:D30`, as the data is found on the worksheet named “Sheet1”, in columns A-D on rows 2-30. Note that we’re not including the table headers.

Once you’re done editing the GSheet node, press Done.

Next, let’s have a look at the data we’re getting from the Google Sheets API.

Add an inject and a debug node to your workspace and connect them to the GSheet one. Hit Deploy, click on the inject node’s button, then have a look at your debug sidebar.

You’ll notice that the response in msg.payload is an array of arrays, each of these arrays having 4 elements – one line worth of data.

Split the msg.payload Array

This data structure isn’t ideal for further processing, so let’s split the array of arrays into individual arrays.

Fortunately, there is a default node already in your palette that will do the heavy lifting for you.

Find the split node under sequence in your node palette o the left side of your screen. Add it to your workspace, connect it after the GSheet node, follow with a debug , then press Deploy and run your flow again.

Glance over to the debug sidebar and notice the response coming through as a sequence of individual arrays. This way we can process them one at a time, as they are coming in.

Set Delay

In most cases, you wouldn’t want to send out messages at this speed, be it via email, SMS or the channel of your choice.

For example, the Nexmo SMS API has a throughput limit for outbound SMS – all API keys are set with 30 API request per second throughput restriction by default. On top of this, there are also restrictions when sending from certain numbers, so you might be restricted to 1 SMS per second.

To make sure you’re not reaching the throughput limits, it’s a good idea to set a delay on each array coming through msg.payload.

To do this, find the delay node in the function section of your node palette, and connect it after the split node. Double-click on it to open up the node properties and set the delay to 1 second – this should cover most use cases, but feel free to adjust it as needed.

Preparing the Message

At this point, we have all the information we need about the recipients, so let’s move on to the message!

Although you could send the same message to all recipients, it’s always a good idea to make it a little more personal. Getting the bad news is frustrating enough, and a bad user experience won’t make it any better.

Adding a bit of templating won’t only give your message a personal touch, it will also make it appear more professional.

Add a template node after delay. Double-click on it, set Property to msg.text and get creative with your message in the text field!

This text field supports Mustache templating, so you could start with greeting the recipient using their name: {{payload.0}}. This expression references the first element of the msg.payload array, the recipient’s first name.

When you’re done editing, press Done, then Deploy.

Sending SMS Notifications

There are many channels available to deliver your notifications, but in bad weather conditions SMS might be your best bet, so we’ll start with this option.

To send the SMS messages, we’ll use the Nexmo SMS API.

Scroll down to the nexmo section of your node palette and add sendsms to your workspace, connected after the template node.

Set up this node by double-clicking on it and filling in the parameters below. You’ll find API KEY and API SECRET by clicking on the edit button next to Nexmo Credentials.

KEY	DESCRIPTION
API KEY	Your Nexmo API key, shown in your account overview.
API SECRET	Your Nexmo API secret, shown in your account overview.
TO	The number you are sending the SMS to, `{{msg.payload.2}}` in this case.
FROM	The number or text shown on a handset when it displays your message. You can also set a custom alphanumeric FROM value if this feature is supported in your country.
TEXT	The content of your message. Use `{{msg.text}}` to reference the templated message you’ve created earlier.

Make sure Unicode is ticked to keep the formatting of your message, then press Done and Deploy.

Run your flow again and see your templated messages appear in the debug sidebar.

Delivery Receipts

When you make a successful request to the SMS API, it returns an array of message objects. Ideally, each of these has a status of 0, indicating that your message has successfully been scheduled for sending. These are the response objects that you’ve just seen in the debug area.

While inspecting this output is quite helpful in determining what the Nexmo SMS API did, there is no guarantee that the message reached the recipient’s handset. Not exactly what you want to hear while sending out snow day alerts, is it?

Once the message reaches its destination, the carrier returns a Delivery Receipt to Nexmo – so don’t panic! All you need to do is set up a webhook endpoint that Nexmo can forward these Delivery Receipts to.

Connect a http input node to a http response node, as well as to a debug node, then fill in the URL field with /receipt in the http input node.

Next, you’ll have to let the Nexmo SMS API know where it should forward the delivery receipts. Go to your API settings in the Default SMS Setting section.

Set the default webhook URL for delivery receipts to YOUR_URL/receipt, then Save changes.

Now you can rest assured that your snow day notifications have indeed reached everyone on your list! Don’t take my word for it though, head over to the debug sidebar and read through your delivery receipts.

Where Next?

Extra Credit: Write Your Delivery Receipts to the Google Sheet

Although the debug sidebar gives you all the insight you’ll ever need, sometimes it’s easier to grasp the result if the data is presented in a more organized fashion.

In this section, we’ll look into writing your delivery receipts back to the same spreadsheet, on a different worksheet(tab).

Pick Your Data

The delivery receipts will contain the following properties of the msg.payload object:

PROPERTY	DESCRIPTION
msisdn	The number the message was sent to.
to	Your Nexmo number or the SenderID you’ve set when sending the SMS.
network-code	The Mobile Country Code Mobile Network Code (MCCMNC) of the carrier the destination phone number is registered with.
messageId	The Nexmo ID for this message.
price	The cost of this message.
status	Will be one of: delivered, expired, failed, rejected, accepted, buffered or unknown, based on where the message is in the delivery process.
scts	When the delivery receipt was received from the carrier in YYMMDDHHMM format. For example, 2001011400 is at 2020-01-01 14:00
err-code	The status of the request. Will be a non 0 value in case of an error. See the Delivery Receipt documentation for more details.
api-key	Your Nexmo API key.
message-timestamp	The time when Nexmo started to push this Delivery Receipt to your webhook endpoint.

Decide on which of these parameters matter to you, then using a change node, set msg.payload to an array of the respective properties.

For example, I’m interested in the timestamp, recipient’s number, status, error code and message ID, so I’ll set msg.payload to the following expression:

[payload.`message-timestamp`, payload.msisdn, payload.status, payload.`err-code`, payload.messageId]

Connect this change node into the /receipt webhook, then follow with a GSheet node.

Write Your Data to the Google Sheet

Add another worksheet(tab) to your Google Sheet and make a note of its name – will be “Sheet2” by default.

Next, head back over to your Node-RED editor and open up the GSheet node properties. Select your credentials from the creds drop-down, select Append Row as a Method, fill in your SpreadsheetID, then specify the cell range where you’d like the data to be written. In my case this will be Sheet2!A:E, as I’d like the data to be spread accross columns A-E on worksheet “Sheet2”.

When you’re ready, click Done and Deploy, then run your flow again.

Congratulations! Your Delivery Receipts have now been logged onto the second worksheet of your spreadsheet. Head over to your Google Sheet and check them out!

Further Hack Ideas

Tired of having to open up your Node-RED Editor to start your flow? Experiment with different ways to kick it off!

Try replacing the inject node with an inbound SMS webhook. Send an SMS to your Nexmo number to achieve your task!
Inbound calls would be another great option! You could even build on it and set up an Interactive Voice Response Menu
Set up a user interface using the dashboard nodes

Resources

SMS API Reference
Getting Started with Ngrok in Node-RED
Get a better understanding of delivery receipts
Mustache templating
JSONata Docs
JSONata Exerciser

Try Another Tutorial

How to Build an IVR using Node-RED and the Nexmo APIs

Julia Biro — Wed, 08 Jan 2020 10:01:04 +0000

An IVR or Interactive Voice Response is a menu of options presented to a caller. They then navigate that menu using the numbers on their keypad to send DTMF (Dual Tone Multi-Frequency) signals.

Each option on the IVR can direct the call to a different path, for example forwarding the call to a specific destination, playing a recorded piece of information or even triggering another service such as an SMS.

IVRs are the fundamental navigation method of Voice Call applications. They can have multiple levels, where the selection of one option presents the user with more options, and this can go on to an infinite depth!

For this tutorial we will just create a single level IVR with three possible paths:

Forward the call to a specific number
Send caller to voicemail
Send the caller an SMS

Dependencies

Prerequisites

Before getting started, you’ll need a few things:

Node.js and Node-RED installed if you’re developing locally
A Nexmo account — create one for free if you haven’t already
A way to expose your server to the internet. This either means you’re running a hosted version of Node-RED or using a tunneling service like ngrok – get up to speed with this Getting Started with Ngrok in Node-RED tutorial

Getting Your Credentials

To use the Nexmo nodes in Node-RED you’ll have to provide your credentials, so it’s best to keep them handy. Go to your dashboard to find your API key and secret and make a note of them.

Next, you’ll need a voice-enabled virtual number. Go to Numbers > Buy numbers to get one.

Setting Up Your Node-RED Editor

Access your Node-RED editor by pointing your browser at http://localhost:1880.

Once you have the editor open, you’ll need to install the Nexmo nodes, the Ngrok node(if not using a hosted version of Node-RED) and the default Email node. You can do so under the Manage palette menu, by searching for the corresponding packages and clicking install:

Nexmo: node-red-contrib-nexmo
Ngrok: node-red-contrib-ngrok
Email: node-red-node-email

After restarting Node-RED, you should see all of these nodes appear on the left side of your screen – in your node palette, among other default nodes.

Expose Your Local Server to the Internet

In case you’re not using a hosted version of Node-RED, the Nexmo Voice API will need another way to access your webhook endpoints, so let’s make your local server accessible over the public internet. If you’re running Node-RED on a public webserver instead of your local machine, you’re all set and ready to move on to the [Create a Nexmo Voice Application] step.

A convenient way to do this is by using a tunneling service like ngrok, and there is a node for it that you’ve just added to your palette.

It takes the strings on and off as input to start/stop the tunnel, and outputs the ngrok host address as the msg.payload. Check out our tutorial on Getting Started with Ngrok in Node-RED to find out more.

Import from Clipboard the snippet below, then open up the ngrok node properties and specify the port number (1880 for Node-RED) and the Region.

[{ "id": "faed0f7.1e524f", "type": "inject", "z": "5b8bbfc3.1a9f18", "name": "", "topic": "", "payload": "on", "payloadType": "str", "repeat": "", "crontab": "", "once": false, "onceDelay": 0.1, "x": 190, "y": 100, "wires": [ [ "8a01baeb.6756d"] ] }, { "id": "11051fa9.75bd1", "type": "inject", "z": "5b8bbfc3.1a9f18", "name": "", "topic": "", "payload": "off", "payloadType": "str", "repeat": "", "crontab": "", "once": false, "onceDelay": 0.1, "x": 190, "y": 160, "wires": [[ "8a01baeb.6756d"] ] }, { "id": "8a01baeb.6756d", "type": "ngrok", "z": "5b8bbfc3.1a9f18", "port": "1880", "creds": "5a9e2b8c.173a2c", "region": "ap", "subdomain": "", "name": "", "x": 400, "y": 140, "wires": [[ "93fd5675.743c1"] ] }, { "id": "93fd5675.743c1", "type": "debug", "z": "5b8bbfc3.1a9f18", "name": "", "active": true, "tosidebar": true, "console": false, "tostatus": false, "complete": "false", "x": 620, "y": 140, "wires": [] }, { "id": "5a9e2b8c.173a2c", "type": "ngrokauth", "z": "" }]

Hit Deploy and click on the on inject node’s button, then navigate to the URL displayed in the debug area (YOUR_URL for future reference) to find your Node-RED editor at a public address.

Create a Nexmo Voice Application

The Nexmo Voice API uses Nexmo Applications to hold security and config information needed to connect to Nexmo endpoints.

In the Nexmo Node-RED palette, several nodes have the capability to create these applications: getrecording, earmuff, mute, hangup, transfer, createcall, playaudio, playtts and playdtmf.

Drag any of these nodes into your workspace, then double-click on it to open up the node properties.

Next to the Nexmo Credentials, select “Add new nexmovoiceapp…” from the drop-down menu and click the edit button. Fill in the details below and click Create New Application.

KEY	DESCRIPTION
`Name`	Choose a name for your Voice Application, for example, “Nexmo Voice Application”.
`API Key`	Your Nexmo API key, shown in your account overview.
`API Secret`	Your Nexmo API secret, shown in your account overview.
`Answer URL`	YOUR_URL/answer, you’ll be hosting a Nexmo Call Control Object (NCCO) here. – more about this later on.
`Event URL`	YOUR_URL/event, you’ll need to reference this when setting up the event handler.

Node-RED will then create a new Nexmo Application on your account and fill in the App ID and Private Key fields. After this step, feel free to delete the Nexmo node you used, as a nexmovoiceapp config node has been created, and that contains all the Nexmo credentials this flow needs.

Set up a Number to Call

Next, you’ll have to link your virtual number to this application.

Find the Voice Application you’ve just created in your Nexmo Dashboard by navigating to Voice > Your Applications.

Click on the name of this application, then under the Numbers tab click on the Link button next to the virtual number you’ve rented earlier.

In case the number you’d like to use is already linked to another app, click on Manage number and configure it to forward incoming calls to your app.

Bonus tip: Use a comment node to take note of the Nexmo number linked to your application, this way you always have it handy.

Log Call Events

While building flows, it’s quite useful to see your call events in the debug area and have a better understanding of what’s really going on, so let’s add an event webhook! This will also help debugging later on, if needed.

Connect an http in node to an http response node, as well as to a debug node, so that you can view your call events in the debug sidebar.

In the http in node, select POST as a Method and fill in the URL field with /event.

The http response node should have 200 set as Status code, but don’t worry about it, this is the default value as well.

Handle Inbound Calls

When you receive an inbound call to your virtual number, the Nexmo Voice API makes a GET request to an endpoint you define, YOUR_URL/answer, and expects a set of instructions on how to handle the call.

First, let’s implement this endpoint.

Define the Webhook Endpoint for Inbound Calls

Add a voice webhook and a return ncco node to your workspace, and wire them together to define a webhook endpoint.

Next, open up the voice webhook node properties, select GET as a Method and type /answer in the URL field, then press Deploy.

Great! Now you have a webhook that returns an NCCO to Nexmo’s API. At this point it doesn’t contain any instructions, so let’s add some!

Build the Nexmo Call Control Object (NCCO)

The instructions expected by the Nexmo API come in the form of a Nexmo Call Control Object, also known as NCCO.

There are lots of different actions available, find the corresponding dark green nodes under the Nexmo palette in your Node-RED editor or check out the NCCO Reference to find out more about them.

In this case, you’ll probably want to greet the caller and explain the different routes they could take, then listen for their input. To do this, you’ll need to add a talk node followed by an input node.

Add them to your workspace, then connect them in between the voice webhook and return ncco nodes.

`talk`

Next, open up the talk node editor and set the Text{} field to the message you’d like to be read out to the caller.

In this tutorial we’ll be implementing 3 routes:

get connected to a human
leave a voice message
receive an SMS with an online booking link, so let’s add the Text{}accordingly. E.g. “Hi! You’ve reached X, please press 1 to get connected, press 2 to leave a message, or press 3 to book online.”

You could also further personalize the experience by selecting a Voice Name or by making use of SSML tags.

Make sure to also tick the Barge In option, which allows the caller to send their input before the text has finished being read. It’s very useful in an IVR and prevents people from having to listen to a long list of options.

`input`

Next, we configure the input node.

Once the user has entered the required number of digits, those will be sent as a new webhook, so we need to configure that path.

In the URL {} field enter the full address of your NodeRED instance followed by /input1 (YOUR_URL/input1), then set the Method to GET. If we were to later create a second level to our IVR, we would need to send that input to a different address, e.g. /input2.

Let’s take this opportunity to pass along the caller number by updating the URL {} field to YOUR_URL/input1?from={{msg.call.from}}. It might come in handy later on if we want to keep a record of these numbers.

Leave Submit on Hash unchecked for now – this would cause the input to be sent by the user pressing the # key, e.g. for collecting something like an account number. Keep the default value of Time Out, but set Max Digits to 1. This ensures that the user can only press a single key before the input is sent, leaving us with a maximum of 9 options in our menu.

Handle the Input

After the caller has submitted their input, we need to listen to it at the new webhook for the input event.

First, we’ll have to implement this endpoint to capture the input value, then based on this value, continue with the route chosen by the caller.

To make a decision based on the input value, we’ll use a switch node, then for each of the options we’ll build the NCCO by wiring together action nodes, closed off by a return NCCO output node.

`voice webhook`

Start by adding a voice webhook node to your workspace. In its node properties, select POST as a method and type /input in the answer URL field.

If you were to connect a debug node after it, after finishing and running the flow, you would see the parameters returned to the /input URL:

Name	Description
`uuid`	The unique ID of the Call leg for the user initiating the input.
`conversation_uuid`	The unique ID for this conversation.
`timed_out`	Returns true if this input timed out based on the value of `Time Out`.
`dtmf`	The numbers input by your caller, in order.

In our use case, we are trying to get the dtmf value, as this is the route chosen by the caller.

Having a closer look at the debug sidebar on completion, we can see that it’s going to be in the dtmf property of the call object nested inside the msg object, so we can reference it as {{msg.call.dtmf}} in the other nodes of this path.

`switch`

Next, we will separate the different routes based on the {{msg.call.dtmf}} value as follows:

is empty -> read out the options again
It’s not one of the options given (contains 0, 4, 5, 6, 7, 8, 9) -> read out the options again
= 1 -> connect caller
= 2 -> send to voicemail
= 3 -> send online booking link via SMS to the caller.

To do so, add a switch node to your canvas, in its node editor set Property to {{msg.call.dtmf}}, then define rules for the five cases mentioned above.

Route 1 & 2: Invalid Input

Connect the first two outputs of the switch node into the talk node’s input. This way if the caller gives an invalid input (not 1, 2 or 3), the initial TTS message will be repeated, listing the available options.

Route 3: Connect Caller

To forward the incoming call, we need to connect it to a new endpoint – in this case, a phone number. To do so, we need a connect action. Optionally, we could also add a talk node to notify the caller that the connection is being made.

Wire a talk node into the switch node’s third output, then follow with a connect and a return ncco node.

First, let’s notify the caller that they are being connected. In the talk node properties, set Text {} to something like Please wait while we connect you. or the message of your choice. Feel free to customize this experience by selecting a Voice Name or by using SSML tags.

Next, open up the connect node editor, select Phone as an Endpoint and type in the number you’d like to call in the Number {} field.

Leave the From {} field empty for the Caller ID to appear as unknown, or fill it in with one of your Nexmo virtual numbers.

If you’d like to have a sneak peek of the finished product, call your Nexmo number and try it out! Just make sure you don’t press 2 or 3, as we haven’t implemented those routes yet.

You might also want to check out our Forward a Call via a Voice Proxy with Node-RED blog post for a more detailed explanation of this path.

Route 4: Send to Voicemail

The next case we’re going to cover is when the caller presses 2, opting for leaving a voice message.

If you’d like to build the voicemail from scratch, head over to our Build Your Own Voicemail With Node-RED and the Nexmo Voice API tutorial for a step-by-step guide.

Otherwise, import from Clipboard the following JSON file into your Node-RED Editor:

[{ "id": "1a10292a.0468d7", "type": "talk", "z": "5b66a8fe.c283c", "text": "Please leave your message at the tone.", "voicename": "", "bargein": false, "loop": "", "level": "", "x": 150, "y": 140, "wires": [ [ "9f6c7f15.1e4d48"] ] }, { "id": "9f6c7f15.1e4d48", "type": "record", "z": "5b66a8fe.c283c", "format": "mp3", "channel": "", "endonsilence": "3", "endonkey": "", "timeout": "", "beepstart": true, "eventurl": "YOUR\_URL/record?from={{msg.call.from}}", "eventmethod": "post", "x": 360, "y": 140, "wires": [[ "f5ae270b.51ba6"] ] }, { "id": "3062ef0c.58d478", "type": "http in", "z": "5b66a8fe.c283c", "name": "", "url": "/record", "method": "post", "upload": false, "swaggerDoc": "", "x": 230, "y": 300, "wires": [[ "5b9e35c2.78611c", "a0e2a9ff.c666d8", "200966c.00b679a"] ] }, { "id": "200966c.00b679a", "type": "http response", "z": "5b66a8fe.c283c", "name": "", "statusCode": "", "headers": {}, "x": 510, "y": 300, "wires": [] }, { "id": "5b9e35c2.78611c", "type": "getrecording", "z": "5b66a8fe.c283c", "creds": "", "filename": "recordings/{{msg.req.query.from}}\_{{msg.payload.timestamp}}.mp3", "x": 460, "y": 360, "wires": [[ "1c3d166.591956a"] ] }, { "id": "a0e2a9ff.c666d8", "type": "debug", "z": "5b66a8fe.c283c", "name": "", "active": false, "tosidebar": true, "console": false, "tostatus": false, "complete": "true", "targetType": "full", "x": 470, "y": 240, "wires": [] }, { "id": "a4651c0b.926068", "type": "e-mail", "z": "5b66a8fe.c283c", "server": "smtp.gmail.com", "port": "465", "secure": true, "tls": true, "name": "", "dname": "", "x": 930, "y": 360, "wires": [] }, { "id": "1c3d166.591956a", "type": "change", "z": "5b66a8fe.c283c", "name": "", "rules": [{ "t": "set", "p": "topic", "pt": "msg", "to": "'Voicemail from ' & msg.req.query.from", "tot": "jsonata" }], "action": "", "property": "", "from": "", "to": "", "reg": false, "x": 720, "y": 360, "wires": [[ "a4651c0b.926068"] ] }, { "id": "5a0c6126.26ff9", "type": "return ncco", "z": "5b66a8fe.c283c", "name": "", "x": 770, "y": 140, "wires": [] }, { "id": "f5ae270b.51ba6", "type": "talk", "z": "5b66a8fe.c283c", "text": "Thank you, good bye!", "voicename": "", "bargein": false, "loop": "", "level": "", "x": 550, "y": 140, "wires": [[ "5a0c6126.26ff9"] ] }]

There are a couple of things you’ll need to do for this to work.

First, connect the switch node’s 4th output into the talk node.
Next, in the record node properties replace YOUR_URL with the address you’re hosting the Node-RED editor at (YOUR_URL/record?from={{msg.call.from}}).
In the Get Recording node under Nexmo Credentials select your Voice Application from the drop-down menu.
In the email node, set To to the email address where you’d like to send the voice recordings, then provide your email client credentials in the Userid and Password fields.

Hit Deploy, then your voicemail should be up and running. Give it a try!

Route 5: Link via SMS

The last route we have to build is for the case when the caller presses 3, choosing to receive an online booking link via SMS.

First, let’s Import from Clipboard the snippet below:

[{ "id": "a69bd1e4.39586", "type": "sendsms", "z": "5b66a8fe.c283c", "creds": "", "to": "{{msg.call.from}}", "fr": "", "text": "This is supposed to be your link :)", "unicode": false, "x": 550, "y": 660, "wires": [ [ "3fd04afe.60abf6"] ] }, { "id": "3fd04afe.60abf6", "type": "debug", "z": "5b66a8fe.c283c", "name": "", "active": true, "tosidebar": true, "console": false, "tostatus": false, "complete": "true", "targetType": "full", "x": 750, "y": 660, "wires": [] }, { "id": "2af4d230.bb1bbe", "type": "talk", "z": "5b66a8fe.c283c", "text": "Your message is on its way!", "voicename": "", "bargein": false, "loop": "", "level": "", "x": 350, "y": 600, "wires": [[ "a69bd1e4.39586", "6f1df801.8db2e8"] ] }, { "id": "6f1df801.8db2e8", "type": "return ncco", "z": "5b66a8fe.c283c", "name": "", "x": 610, "y": 600, "wires": [] }]

After adding it to your workspace, connect the switch node’s last output into the talk node’s input.

Next, let’s have a closer look at the individual nodes in this path.

`talk`

We use the talk node to give feedback to the caller that something is happening. Feel free to get creative with custom voice names or SSML tags, but a simple “Your message is on its way!” will suffice as well.

`return NCCO`

It is followed by a return NCCO node to close off this path as well and send our “set of instructions” back to the Nexmo API. There’s no setup needed here.

`Send SMS`

The Send SMS node does the heavy lifting of this path, as it is the one sending the SMS.

You can set up this node by double clicking on it and filling in the parameters below. You’ll find API KEY and API SECRET by clicking on the edit button next to Nexmo Credentials, after selecting Add new nexmobasic from the drop-down.

KEY	DESCRIPTION
`API KEY`	Your Nexmo API key, shown in your account overview.
`API SECRET`	Your Nexmo API secret, shown in your account overview.
`TO`	The number you are sending the SMS to. In this case `{{msg.call.from}}`, the caller.
`FROM`	The number or text shown on a handset when it displays your message. You can set a custom alphanumeric FROM to better represent your brand, if this feature is supported in your country. Otherwise, add one of your Nexmo numbers.
`TEXT`	The content of your message. Time to get creative 🙂

The debug node is completely optional, but it does come in handy when you want to see a bit more details in the debug sidebar.

You might want to glance over at our How to Send SMS Messages with Node-RED guide to find out more about using the SMS API.

Try It!

Congratulations! You’ve just built yourself a fully functional Interactive Voice Response Menu! It’s finally time to try it out, so enjoy!

Where Next?

Resources

Try another tutorial!

Build Your Own Voicemail With Node-RED and the Nexmo Voice API

Julia Biro — Thu, 14 Nov 2019 12:54:36 +0000

I have been avoiding voicemail for most of my life. Most of the time for one simple reason—I could never quite get 100% of the message.

I would have considered myself lucky if they’d slurred out a number I could have called back, the voicemail had been empty-ish or they had gotten past their first name. In most cases though it would go something like this:

“Hi Julia, this is Ted, I’m with didn’t_really_get_the_name . I’m sorry we haven’t been able to get back together on this – if you’re like me I’m sure you’re being pulled in many different directions and are real busy. Do me a favour, though, and when you get this message, just call me back and leave a message with what you’ve decided to do about my proposal. Either way, it will be nice for me to know. Thanks in advance for that, and I’ll be waiting for your call..”

Ted… Mosby? Crilly? Maybe, Cassidy? We’ll never know.

Luckily, building your own voicemail in Node-RED is both faster and easier than deciphering those messages. Follow along to see how it works!

What You’re Going to Build

This tutorial is part of the “Getting Started with Nexmo and Node-RED” series.

These articles show you how to get started with Nexmo APIs like SMS, Voice and Verify, so feel free to refer back to them as you go, or in case you’d like to add another functionality.

In this tutorial we’ll be building a simple voicemail service that allows callers to reach your Nexmo number and leave a message.

The recorded voice message will then be fetched from the Nexmo servers and sent to your email address.

Dependencies

Prerequisites

Before getting started, you’ll need a few things:

Node.js and Node-RED installed, if you’re developing locally
A Nexmo account — create one for free if you haven’t already
A way to expose your server to the internet. This either means you’re running a hosted version of Node-RED, or using a tunneling service like ngrok – get up to speed with this Getting Started with Ngrok in Node-RED tutorial

Getting Your Credentials

To use the Nexmo nodes in Node-RED you’ll have to provide your credentials, so it’s best to keep them handy. Go to your dashboard to find your API key and secret and make a note of them.

Next, you’ll need a Voice-enabled virtual number. Go to Numbers > Buy numbers to get one.

Setting Up Your Node-RED Editor

Access your Node-RED editor by pointing your browser at http://localhost:1880.

Nexmo: node-red-contrib-nexmo
Ngrok: node-red-contrib-ngrok
Email: node-red-node-email

After restarting Node-RED, you should see all of these nodes appear on the left side of your screen – in your node palette, among other default nodes.

Expose Your Local Server to the Internet

In case you’re not using a hosted version of Node-RED, the Nexmo Voice API will need another way to access your webhook endpoints, so let’s make your local server accessible over the public internet. If you’re running Node-RED on a public web server instead of your local machine, you’re all set and ready to move on to the [Create a Nexmo Voice Application] step.

A convenient way to do this is by using a tunneling service like ngrok, and there is a node for it that you’ve just added to your palette.

Import from Clipboard the snippet below, or have a stab at building this path yourself.

[{ "id": "faed0f7.1e524f", "type": "inject", "z": "5b8bbfc3.1a9f18", "name": "", "topic": "", "payload": "on", "payloadType": "str", "repeat": "", "crontab": "", "once": false, "onceDelay": 0.1, "x": 190, "y": 100, "wires": [ [ "8a01baeb.6756d"] ] }, { "id": "11051fa9.75bd1", "type": "inject", "z": "5b8bbfc3.1a9f18", "name": "", "topic": "", "payload": "off", "payloadType": "str", "repeat": "", "crontab": "", "once": false, "onceDelay": 0.1, "x": 190, "y": 160, "wires": [[ "8a01baeb.6756d"] ] }, { "id": "8a01baeb.6756d", "type": "ngrok", "z": "5b8bbfc3.1a9f18", "port": "1880", "creds": "5a9e2b8c.173a2c", "region": "ap", "subdomain": "", "name": "", "x": 400, "y": 140, "wires": [[ "93fd5675.743c1"] ] }, { "id": "93fd5675.743c1", "type": "debug", "z": "5b8bbfc3.1a9f18", "name": "", "active": true, "tosidebar": true, "console": false, "tostatus": false, "complete": "false", "x": 620, "y": 140, "wires": [] }, { "id": "5a9e2b8c.173a2c", "type": "ngrokauth", "z": "" }]

At this point, your editor should look similar to this:

As the last step before hitting Deploy , open up the ngrok node properties and specify the port number (1880 for Node-RED) and the Region.

You can also add your authtoken if you already have a ngrok account. Don’t worry if you don’t, just skip this step for now. The node will warn that it is not fully configured but this is not an issue.

Hit Deploy and click on the on inject node’s button, then navigate to the URL displayed in the debug area (YOUR_URL for future reference) to find your Node-RED editor at a public address.

Create a Nexmo Voice Application

The Nexmo Voice API uses Nexmo Applications to hold security and config information needed to connect to Nexmo endpoints.

Drag any of these nodes into your workspace, then double-click on it to open up the node properties.

Next to the Nexmo Credentials, select “Add new nexmovoiceapp…” from the drop-down menu and click the edit button. Fill in the details below and click Create New Application.

KEY	DESCRIPTION
`Name`	Choose a name for your Voice Application, for example “Nexmo Voice Application”.
`API Key`	Your Nexmo API key, shown in your account overview.
`API Secret`	Your Nexmo API secret, shown in your account overview.
`Answer URL`	YOUR_URL/answer, you’ll be hosting a Nexmo Call Control Object (NCCO) here. – more about this later on.
`Event URL`	YOUR_URL/event, you’ll need to reference this when setting up the event handler.

Set Up a Number to Call

Next, you’ll have to link your virtual number to this application.

Find the Voice Application you’ve just created in your Nexmo Dashboard by navigating to Voice > Your Applications.

Click on the name of this application, then under the Numbers tab click on the Link button next to the virtual number you’ve rented earlier.

In case the number you’d like to use is already linked to another app, click on Manage number and configure it to forward incoming calls to your app.

Bonus tip: Use a comment node to take note of the Nexmo number linked to your application, this way you always have it handy.

Handle Inbound Calls

First, let’s implement this endpoint.

Define the Webhook Endpoint for Inbound Calls

Add a voice webhook and a return ncco node to your workspace, and wire them together to define a webhook endpoint.

Next, open up the voice webhook node properties, select GET as a Method and type /answer in the URL field, then press Deploy.

Great! Now you have a webhook that returns an NCCO to Nexmo’s API. At this point it doesn’t contain any instructions, so let’s add some!

Build the Nexmo Call Control Object (NCCO)

The instructions expected by the Nexmo API come in the form of a Nexmo Call Control Object, also known as NCCO.

There are lots of different actions available, find the corresponding nodes under the Nexmo palette in your Node-RED editor or check out the NCCO Reference to find out more about them.

In this case, you’ll probably want to greet the caller then start recording the message. To do this, you’ll need to add a talk node followed by a record node.

Add them to your workspace, then connect them in between the voice webhook and return ncco nodes.

`talk`

Next, open up the talk node editor and set the Text{} field to the message you’d like to be read out to the caller. Eg. “Hi! You’ve reached X, please leave a message.”

If you’re feeling nostalgic about old school voicemails, you’re all set. On the other hand, you could also personalize the experience by selecting a Voice Name or by making use of SSML tags, so that it sounds more like a person and less like a robot.

`record`

In the record node properties fill in the URL {} field with YOUR_URL/record. This is going to be the eventURL that Nexmo will return a set of parameters to, once the recording has completed.

If you glance over at the NCCO Reference you’ll soon realize that the calling number is not one of them.

Fortunately, we can grab the caller’s phone number from the answerURL and pass it as a query parameter.

Update the URL {} field to YOUR_URL//record?from={{msg.call.from}}. This way we’ll be able to access the from value through the record eventURL by referencing msg.req.query.from.

Before moving on to the next step, make sure you’ve selected POST as a Method, MP3 as a Format and that you’ve set a value for End On Silence (eg. 3).

If you’d like to see the generated NCCO, go to YOUR_URL/answer. You’ll see a set of actions, or “instructions”, in JSON format that Nexmo will use to control the call flow.

Ready to take it a step further? Dial your Nexmo number to see it in action!

Fetch Recording

At this point, the caller is greeted by a TTS message followed by a beep tone and their message gets recorded. The next step is to fetch the recording from the Nexmo servers.

Record eventURL

First, let’s define the record eventURL where we’re expecting the recording parameters to be sent upon completion.

Add a http in node to your workspace, then connect a http response node, as well as to a debug node to it. This way you can start logging events in the debug area and gain a bit more insight into what is really going on.

Open up the http in node properties, select POST as a Method and fill in the URL field with /record.

The http response node should have 200 set as Status code, but don’t worry about it, this is the default value as well.

Although the recording data is coming through as msg.payload, we still have the from value stored in msg.req.query.from. Make sure you select complete msg object in the debug node’s editor as Output.

Get Recording

To actually retrieve the recording, we’ll be using the getrecording Nexmo node.

Add one to your canvas, connect it to the /record http in node and open up its node editor.

You’ll see two fields:

Nexmo Credentials – select the voice application you created earlier from the drop-down menu.
Filename {} – Notice the {} sign in the label, which means that this field supports Mustache templating and the value can be set dynamically. This gives us the perfect opportunity to include the caller’s number and a timestamp in the filename, so let’s set it to recordings/{{msg.req.query.from}}_{{msg.payload.timestamp}}.mp3.

Note, this node does not write the audio to disk, the filename field is there to set the value of msg.filename. Next, there are a couple different routes you can take: upload the audio to your own server, follow with a file node and download it to your computer, or use an e-mail node and send it to yourself.

Send Recording to an Email Address

For this example we’ll use the default Node-RED e-mail node, which sends the msg.payload as an email, with a subject of msg.topic.

In our case, msg.payload is a binary buffer (the recording) and it will be converted to an attachment. If you wish to add a body to your email set it as msg.description using a change node in the flow before the e-mail node.

The filename will be msg.filename, which we’ve already specified.

Connect a change node into getrecording, followed by an e-mail node. You’ll find both in your node palette, change under function and e-mail under social.

Next, let’s see how to configure them.

`change`

Open up the change node properties and define two rules using the set operation.

First, let’s set msg.topic, the subject of the email.

In the upper field replace payload with topic, then select expression type from the to drop-down, which uses the JSONata query and expression language. To include the caller’s number in the email subject, fill in this field with something like 'Voicemail from ' & msg.req.query.from.

Click on the add button to define a second rule. This time we’ll be setting the value of msg.description, the email body. You could use an expression again, or just go with a simple string like “Hey, you’ve got voicemail!”.

Press Done once you’re finished, and let’s move on to the e-mail node!

`e-mail`

In the e-mail node editor there are three fields you need to fill in: To – the recipient email address, Userid and Password – your email login details.

Once you’re done, hit Done and Deploy. Your Voicemail is up and running!

Log Call Events

One more thing before you go! It’s quite useful to see your call events in the debug area and have a better understanding of what’s really going on, so let’s add an event webhook!

Connect an http in node to an http response node, as well as to a debug node, so that you can view your call events in the debug area.

In the http in node, select POST as a Method and fill in the URL field with /event.

The http response node should have 200 set as Status code, but don’t worry about it, this is the default value as well.

Now call your Nexmo number and follow your call events in the debug sidebar!

Try it Out!

Et voilà! You’ve built your own voicemail service and, hopefully, you’ll never have to put up with another pesky voicemail again. Call your Nexmo number and an email will be headed your way shortly.

Where Next?

Forward a Call via a Voice Proxy with Node-RED

Julia Biro — Thu, 17 Oct 2019 08:09:37 +0000

In this tutorial we’ll be using the Nexmo Voice API to make private calls, by forwarding a call via a voice proxy, and as an additional bonus we’re also going to add a recording feature to it at the end.

Find out more of what can be done with Node-RED at Vonage Campus, our first customer and developer conference taking place in San Francisco on October 29-30. It’s free to attend, so register to join us now!

If you’ve ever wondered how you can contact your ride share driver, Airbnb host or courier without knowing their number, or you’re simply interested in making private calls, follow along and find out how this is done!

Dependencies

Prerequisites

Before getting started, you’ll need a few things:

Node.js and Node-RED installed, if you’re developing locally
A Nexmo account — create one for free if you haven’t already
A way to expose your server to the internet. This either means you’re running a hosted version of Node-RED, or using a tunneling service like ngrok – get up to speed with this Getting Started with Ngrok in Node-RED tutorial

Getting Your Credentials

To use the Nexmo nodes in Node-RED you’ll have to provide your credentials, so it’s best to keep them handy. Go to your dashboard to find your API key and secret and make a note of them.

Next, you’ll need a Voice-enabled virtual number. Go to Numbers > Buy numbers to get one.

Setting Up Your Node-RED Editor

Access your Node-RED editor by pointing your browser at http://localhost:1880.

Once you have the editor open, you’ll need to install the Nexmo nodes. You can do so under the Manage palette menu, by searching for the node-red-contrib-nexmo package and clicking install.

Now you should see all of the Nexmo nodes appear on the left side of your screen – in your node palette, among other default nodes.

Expose Your Local Server to the Internet

In case you’re not using a hosted version of Node-RED, the Nexmo Voice API will need another way to access your webhook endpoints, so let’s make your local server accessible over the public internet. If you’re running Node-RED on a public web server instead of your local machine, you’re all set and ready to move on to the Create a Nexmo Voice Application step.

A convenient way to do this is by using a tunneling service like ngrok, and there is a node for it that you can install directly from your editor.

Feel free to also check out our tutorial on Getting Started with Ngrok in Node-RED to find out more.

Once you’ve installed the ngrok node and restarted your editor, the ngrok node should appear in you node palette. It takes the strings on or off as input to start/stop the tunnel, and outputs the ngrok host address as the msg.payload.

Import from Clipboard the snippet below, or have a stab at building this path yourself.

[{ "id": "faed0f7.1e524f", "type": "inject", "z": "5b8bbfc3.1a9f18", "name": "", "topic": "", "payload": "on", "payloadType": "str", "repeat": "", "crontab": "", "once": false, "onceDelay": 0.1, "x": 190, "y": 100, "wires": [ [ "8a01baeb.6756d"] ] }, { "id": "11051fa9.75bd1", "type": "inject", "z": "5b8bbfc3.1a9f18", "name": "", "topic": "", "payload": "off", "payloadType": "str", "repeat": "", "crontab": "", "once": false, "onceDelay": 0.1, "x": 190, "y": 160, "wires": [[ "8a01baeb.6756d"] ] }, { "id": "8a01baeb.6756d", "type": "ngrok", "z": "5b8bbfc3.1a9f18", "port": "1880", "creds": "5a9e2b8c.173a2c", "region": "ap", "subdomain": "", "name": "", "x": 400, "y": 140, "wires": [[ "93fd5675.743c1"] ] }, { "id": "93fd5675.743c1", "type": "debug", "z": "5b8bbfc3.1a9f18", "name": "", "active": true, "tosidebar": true, "console": false, "tostatus": false, "complete": "false", "x": 620, "y": 140, "wires": [] }, { "id": "5a9e2b8c.173a2c", "type": "ngrokauth", "z": "" } ]

At this point, your editor should look similar to this:

As the last step before hitting Deploy , open up the ngrok node properties and specify the port number (1880 for Node-RED) and the Region.

You can also add your authtoken for your ngrok account if you have one. Don’t worry if you don’t, just skip this step for now. The node will warn that it is not fully configured but this is not an issue.

Hit Deploy and click on the on inject node’s button, then navigate to the URL displayed in the debug area (YOUR_URL for future reference) to find your Node-RED editor at a public address.

Create a Nexmo Voice Application

Some of Nexmo’s APIs, including the Voice API, use Nexmo Applications to hold security and config information needed to connect to Nexmo endpoints.

In the Nexmo Node-RED palette, several nodes have the capability to create these applications: getrecording , earmuff , mute , hangup , transfer , createcall , playaudio , playtts and playdtmf.

Drag any of these nodes into your workspace, then double-click on it to open up the node properties.

Next to the Nexmo Credentials, select “Add new nexmovoiceapp…” from the drop-down menu and click the edit button. Fill in the details below and click Create New Application.

KEY	DESCRIPTION
`Name`	Choose a name for your Voice Application, for example “Nexmo Voice Application”.
`API Key`	Your Nexmo API key, shown in your account overview.
`API Secret`	Your Nexmo API secret, shown in your account overview.
`Answer URL`	YOUR_URL/answer, you’ll be hosting a Nexmo Call Control Object (NCCO) here. – more about this later on.
`Event URL`	YOUR_URL/event, you’ll need to reference this when setting up the event handler.

Set Up a Number to Call

Next, you’ll have to link your virtual number to this application.

Find the Voice Application you’ve just created in your Nexmo Dashboard by navigating to Voice > Your Applications.

Click on the name of this application, then under the Numbers tab click on the Link button next to the virtual number you’ve rented earlier.

In case the number you’d like to use is already linked to another app, click on Manage number and configure it to forward incoming calls to your app.

Bonus tip: Use a comment node to take note of the Nexmo number linked to your application, this way you always have it handy.

Handle Inbound Calls

When you receive an inbound call, the Nexmo Voice API makes a GET request to an endpoint you define, YOUR_URL/answer, and expects a set of instructions on how to handle the call.

These instructions come in the form of a Nexmo Call Control Object, also known as NCCOs.

There are lots of different actions available, find the corresponding nodes under the Nexmo palette in your Node-RED editor or check out the NCCO Reference to find out more about them.

For this tutorial we’ll be using the connect action, so that when the inbound call is received, it gets connected to a new phone number we specify.

Define the Webhook Endpoint for Inbound Calls

Add a voice webhook and a return ncco node to your workspace, and wire them together to define a webhook endpoint.

Next, open up the voice webhook node properties, select GET as a Method and type /answer in the URL field, then press Deploy.

Great! Now you have a webhook that returns an NCCO to Nexmo’s API. At this point it doesn’t contain any actions, so let’s add one!

Build the Nexmo Call Control Object

To forward the incoming call, we need to connect it to a new endpoint. To do so, we need a connect action.

Add a connect node in between the voice webhook and a return ncco nodes. This will add a connect action to the NCCO.

Open up the connect node editor, select Phone as an Endpointand type in the number you’d lilke to call in the Number {} field.

Leave the From {} field empty for the Caller ID to appear as unknown, or fill it in with one of your Nexmo virtual numbers.

To find out more about the other parameters and the connect action, check out the NCCO Reference.

Log Call Events

Finally, connect an http in node to an http response node, as well as to a debug node, so that you can view your call events in the debug area.

In the http input node, select POST as a Method and fill in the URL field with /event.

The http response node should have 200 set as Status code, but don’t worry about it, this is the default value as well.

Now call your Nexmo number and follow your call events in the debug sidebar!

Add a Recording Feature

When making business phone calls, it’s often helpful to have the option to also record them. So let’s have a look at how we can transform the flow above to give us a recording of the conversation.

Update the NCCO

First, we’ll need a record action added to the Nexmo Call Control Object.

Recording starts when the record action is executed in the NCCO and finishes when the synchronous condition in the action is met. That is, End On Silence, timeOut or endOnKey.

If you do not set a synchronous condition, the Voice API immediately executes the next NCCO without recording.

In our use case, this means that we need to add a record node before the connect node, and no End On Silence, Time Out or End On Key values should be set.

Go ahead and add a record node to your flow, between the voice webhook and connect nodes.

Open up its properties, fill in the URL {} field with something like YOUR_URL/record, select POST as a Method and pick a Format for the recording file – I’ll go with MP3. You could also tick Beep Start to have a clear indication of when exactly the recording starts.

Add Handler for the Recording eventURL

Next, we need to add a handler for the recording eventURL – YOUR_URL/record.

This way we receive the event on completion of recording, and then be able to download said recording to our machine.

Add an http in node and an http response node to your workspace and wire them together. Consider also adding a debug node to see what’s coming through the recording eventURL.

In the http input node, select POST as a Method and fill in the URL field with /record.

The http response node should have 200 set as Status code, but this is the default value as well.

Download Recording

Once the recording has completed, Nexmo sends us the recording URL in the recording event webhook . The last step is fetching the recording and downloading it.

For this step we’ll need a getrecording node to fetch the recording audio from the supplied URL, and a file node to write it to a file on our machine.

Add a getrecording node after the /record http in node, then in its node properties select the voice application created earlier from the Nexmo Credentials drop-down and provide an absolute path as Filename {}.

And finally, add a file node after getrecording. In its node editor, make sure the Create directory if it doesn’t exist? option is ticked and select either overwrite or append to file from the Action drop-down. Leave the Filename field empty, as this value will be passed in from the getrecording node, in {{msg.filename}}.

That’s a wrap! Get a second device or have a friend call your Nexmo number, have a conversation and once you’re done, the recording file will be waiting for you, already domnloaded to your machine. Enjoy!

Where Next?

Build a Conference Call with Node-RED

Julia Biro — Mon, 07 Oct 2019 21:52:57 +0000

In previous tutorials you’ve had a chance to get your feet wet in the world of Nexmo APIs, making and receiving phone calls using the Voice API, and hopefully also customizing these experiences.

In today’s tutorial, we’ll take it a step further and build a voice-based conferencing service.

The user calls a predefined virtual number and inputs a meeting ID using the dial pad, then they get placed in the same conference call with everyone else who has provided the same ID.

Steps:

Prerequisites
Expose Your Local Server to the Internet
Define the Webhook Endpoint for Inbound Calls
Define the Webhook Endpoint for the Input Event
Create a Nexmo Voice Application
Set Up a Number to Call
Handle Your Call Events
Try it out!

Prerequisites

Before getting started, you’ll need a few things:

Node.js and Node-RED installed on your machine
A Nexmo account—create one for free if you haven’t already
A way to expose your server to the internet. This either means you’re running a hosted version of Node-RED, or in case you’re developing locally, using a tunneling service like ngrok—get up to speed with this Getting Started with Ngrok in Node-RED tutorial

Getting Your Credentials

To interact with the Voice API, you’ll need to make note of a couple of things. Once you’ve created a Nexmo account, go to the dashboard to find your API key and secret.

Next, you’ll need a Voice-enabled virtual number. Go to Numbers > Buy numbers to get one.

Setting Up Your Node-RED Editor

First, you’ll need to install the runtime and editor. This could be done either on your local machine, on a Single Board Computer (eg. Raspberry Pi), or through several cloud-hosted options. This example will be using your local machine, so once you’ve installed Node-RED globally, type the command below in your terminal to get started.

$ node-red

You can then access the Node-RED editor by pointing your browser at http://localhost:1880.

Once you have your editor open, you’ll need to install the Nexmo nodes. You can do so under the Manage palette menu, by searching for the node-red-contrib-nexmo package and clicking install.

Now you should see all of the Nexmo nodes appear on the left side of your screen—in your node palette, among other default nodes.

Expose Your Local Server to the Internet

The Nexmo API will need access to this webhook to make calls against it, so let’s make the URL accessible over the public internet. If you’re running Node-RED on a public web server instead of your local machine, you’re all set and ready to move on to the Create a Nexmo Voice Application step.

Otherwise, a convenient way to do this is by using a tunneling service like ngrok.

First, you’ll need to install the ngrok node. To do so, open up Manage palette from the hamburger menu in your Node-RED editor, search for the node-red-contrib-ngrok package, and click install. After restarting your editor, the ngrok node should appear in the node palette.

The ngrok node takes the strings on or off as input to start/stop the tunnel, and outputs the ngrok host address as the msg.payload.

The easiest way to set this up is to wire two inject nodes as the ngrok node’s input, one with the payload of the string on and the other with off. For easier use, you could also set the Name of these nodes accordingly in the node properties, so that it’s clear what functionality they have. Next, to display the host address in the debug sidebar, connect a debug node after ngrok.

As the last step before hitting Deploy, open up the ngrok node properties and specify the port number. In case of Node-RED, the default value is 1880. The default ngrok Region is US but you can also set it to Europe or Asia. You can also add your authtoken for your ngrok account if you have one. Don’t worry if you don’t, just skip this step for now. The node will warn that it is not fully configured but this is not an issue.

And you’re all set! Once you hit Deploy and click on the on inject node’s button, navigate to the URL displayed in the debug area (YOUR_URL for future reference) to find your Node-RED editor at a public address.

Define the Webhook Endpoint for Inbound Calls

Nexmo calls are controlled using Nexmo Call Control Objects, also known as NCCOs. An NCCO defines a list of actions to be followed when a call is handled. There are lots of different actions available; find the corresponding nodes under the Nexmo palette in your Node-RED editor or check out the NCCO Reference to find out more about them.

When handling inbound calls, you need your NCCO hosted at an Answer URL. In this case, we’ll be using a talk action to ask tor the meeting ID, then an input action to collect it.

Add a voice webhook input node to your canvas, followed by a talk node, an input node and a return NCCO output node.

Next, in the voice webhook node, select GET as a Method and type /answer in the answer URL field.

In the talk node properties set the Text{} field to the message you’d like to be read out when the call is answered. E.g. “Please enter the meeting ID”. You can also select a Voice Name, see the Text to Speech Guide for the full list of options.

Finally open the input node editor, set YOUR_URL/input as the URL {} and POST as a Method.

At this time you could also set a couple of other parameters to further customize the experience:

Name	Description
`Submit On Hash`:	Set to true so the caller’s activity is sent to your webhook endpoint at `YOUR_URL/input` after they press `#`. If `#` is not pressed the result is submitted after `Time Out` seconds. The default value is false.
`Time Out`:	The result of the caller’s activity is sent to the `YOUR_URL/input` webhook endpoint `Time Out` seconds after the last action. The default value is 3. Max is 10.
`Max Digits`:	The number of digits the user can press. The maximum value is 20, the default is 4 digits.

Find out more about these in the NCCO Reference.

Define the Webhook Endpoint for the Input Event

You’ll also need a second endpoint to capture the DTMF input from the user, and based on the code they have submitted, place them into a conversation.

Add another voice webhook input node to your canvas, followed by a talk node, a conversation node and a return NCCO output node.

`voice webhook`

In the voice webhook node properties, select POST as a method and type /input in the answer URL field.

If you were to connect a debug node after it, after finishing and running the flow, you would see the parameters returned to the /input URL:

Name	Description
`uuid`	The unique ID of the Call leg for the user initiating the input.
`conversation_uuid`	The unique ID for this conversation.
`timed_out`	Returns true if this input timed out based on the value of `Time Out`.
`dtmf`	The numbers input by your caller, in order.

In our use case, we are trying to get the dtmf value, as this is the meeting ID provided by the caller.

Having a closer look at the debug sidebar on completions, we can see that it’s going to be in the dtmf property of the call object nested inside the msg object, so we can reference it as {{msg.call.dtmf}} in the other nodes of this path.

`talk`

Next, open up the talk node editor and set the Text{} field to the message you’d like to be read out once the caller inputs the meeting ID.

Note the {} sign next to the Text label, showing that this value can be set dynamically, using Mustache templating, so you could go with something like Joining meeting {{msg.call.dtmf}}.

Feel free to further personalize the experience by selecting a Voice Name or by making use of SSML tags

`conversation`

We’re using the conversation action to create a standard conference, so the only parameter we have to set is Name {}. Using the conversation action with the same name reuses the same persisted Conversation, so it’s handy to name it after the meeting ID, referencing {{msg.call.dtmf}} The first person to call the virtual number assigned to the conversation creates it.

In the future, you might want to take this a step further and create a moderated Conversation with selective audio controls. Check out the NCCO reference to find out more.

Once you’re done with this path, it should look similar to this:

Create a Nexmo Voice Application

Some of Nexmo’s APIs, including the Voice API, use Nexmo Applications to hold security and config information needed to connect to Nexmo endpoints.

Drag any of these nodes into your workspace, then double-click on it to open up the node properties.

Next to the Nexmo Credentials, select “Add new nexmovoiceapp…” from the drop-down menu and click the edit button. Fill in the details below and click Create New Application.

KEY	DESCRIPTION
`Name`	Choose a name for your Voice Application, for example `Conference Call`.
`API Key`	Your Nexmo API key, shown in your account overview.
`API Secret`	Your Nexmo API secret, shown in your account overview.
`Answer URL`	YOUR_URL/answer, you’ll be hosting a Nexmo Call Control Object (NCCO) here. – more about this later on.
`Event URL`	YOUR_URL/event, you’ll need to reference this when setting up the event handler.

Node-RED will then create a new Nexmo Application on your account and fill in the App ID and Private Key fields for you to save. After this step, feel free to delete the Nexmo node you used, as a nexmovoiceapp config node has been created, and that contains all the Nexmo credentials this flow needs.

Set Up a Number to Call

Next, you’ll have to link your virtual number to this application.

Find the Voice Application you’ve just created in your Nexmo Dashboard by navigating to Voice > Your Applications.

Click on the name of this application, then under the Numbers tab click on the Link button next to the virtual number you’ve rented earlier.

In case the number you’d like to use is already linked to another app, click on Manage number and configure it to forward incoming calls to your app.

Bonus tip: Use a comment node to take note of the Nexmo number linked to your application, this way you always have it handy.

Handle Your Call Events

If you’d like to receive events about the progress of your call, you can also set up an event webhook.

Connect an http input node to an http response node, as well as to a debug node, so that you can view your call events in the debug area.

In the http input node, select POST as a Method and fill in the URL field with /event.

The http response node should have 200 set as Status code, but don’t worry about it; this is the default value as well.

Try it Out!

And that’s a wrap! Get a friend or more and take it for a spin! Don’t forget to take a peek in the debug area to follow your call events. Enjoy!

Where Next?

Resources:

Verify Phone Numbers with Node-RED

Julia Biro — Wed, 25 Sep 2019 08:00:13 +0000

In previous tutorials you’ve learnt about the Nexmo SMS and Voice APIs, you’ve gotten comfortable with sending and receiving messages and calls, and hopefully, you’ve also had a chance to experiment and play around with customizing these experiences in Node-RED.

Interested in learning more about Node-RED? We’ve got a whole session dedicated to it at Vonage Campus, our first customer and developer conference taking place in San Francisco on October 29-30. It’s free to attend, so request your invite now!

In this tutorial, we’ll look at the Verify API and explore a handy way of validating your users’ phone numbers.

Many apps on-board users with not much more than a phone number in order to keep the process as simple as possible, and they need to use that identifier for authentication later on.

So let’s take a look at how we can do that, as well as ensure that there are no duplicate accounts and that the users are indeed reachable on the phone numbers provided by them.

Prerequisites

Before getting started, you’ll need a few things:

Node.js and Node-RED installed on your machine
A Nexmo account – create one for free if you haven’t already

Getting Your Credentials

In order to interact with the Verify API, you’ll need to make note of a couple of things. Once you’ve created a Nexmo account, go to the dashboard to find your API key and secret. You’ll be using these credentials later on to authenticate with the API.

Setting Up Your Node-RED Editor

First, you’ll need to install the runtime and editor. This could be done either on your local machine, on a Single Board Computer (eg Raspberry Pi), or a number of cloud-hosted options.

This example will be using your local machine, so once you’ve installed Node-RED globally, type the command below in your terminal to get started.

$ node-red

You can then access the Node-RED editor by pointing your browser at http://localhost:1880.

Once you have your editor open, you’ll need to install the Nexmo nodes. You can do this under the Manage palette menu, by searching for the node-red-contrib-nexmo package and clicking install.

Next, repeat the previous step for the node-red-dashboard package as well.

After restarting Node-RED, you should now see all of the Nexmo and Dashboard nodes appear on the left side of your screen, among the other default nodes in the node palette.

User Interface

For this tutorial you’ll need a simple user interface to collect user input. There are a couple of ways you could go about this, including writing your own HTML and CSS, but a much quicker alternative is using the Node-RED dashboard nodes.

What you’ll need:

A text field collecting the user’s phone number
A text field collecting the PIN code
A Cancel Verification button
A Call Me button – this will give the user the option to request a phone call on top of an SMS, as a means of receiving the PIN code.

Speed up the process by Importing from Clipboard the snippet below, or experiment with the dashboard nodes for yourself.

[{ "id": "463e8e92.d82a78", "type": "tab", "label": "Verify Demo", "disabled": false, "info": "" }, { "id": "fb7955ef.0e5fd8", "type": "ui\_form", "z": "463e8e92.d82a78", "name": "", "label": "Verify your phone number:", "group": "91563061.fc448", "order": 1, "width": 0, "height": 0, "options": [ { "label": "eg. 447401234567", "value": "number", "type": "text", "required": true }], "formValue": { "number": "" }, "payload": "", "submit": "Send me a code", "cancel": "delete", "topic": "", "x": 430, "y": 140, "wires": [[] ] }, { "id": "b60bf0b2.9a839", "type": "ui\_button", "z": "463e8e92.d82a78", "name": "", "group": "91563061.fc448", "order": 2, "width": "0", "height": "0", "passthru": false, "label": "Call me", "tooltip": "", "color": "", "bgcolor": "", "icon": "", "payload": "", "payloadType": "str", "topic": "", "x": 520, "y": 580, "wires": [[] ] }, { "id": "b182a10d.c8f08", "type": "ui\_button", "z": "463e8e92.d82a78", "name": "", "group": "91563061.fc448", "order": 3, "width": 0, "height": 0, "passthru": false, "label": "Cancel Verification", "tooltip": "", "color": "", "bgcolor": "red", "icon": "", "payload": "", "payloadType": "str", "topic": "", "x": 550, "y": 760, "wires": [[] ] }, { "id": "a2251664.3ba2f", "type": "comment", "z": "463e8e92.d82a78", "name": "Start Verification - Collect phone number to be verified", "info": "", "x": 520, "y": 80, "wires": [] }, { "id": "7185f18d.87142", "type": "comment", "z": "463e8e92.d82a78", "name": "Check if received code matches the generated one", "info": "", "x": 510, "y": 280, "wires": [] }, { "id": "7f30e.60359cf28", "type": "comment", "z": "463e8e92.d82a78", "name": "Next Verification - Escalate to TTS Call", "info": "", "x": 610, "y": 520, "wires": [] }, { "id": "c46fa301.4eb0d8", "type": "comment", "z": "463e8e92.d82a78", "name": "Cancel Verification", "info": "", "x": 550, "y": 700, "wires": [] }, { "id": "ab7fb094.d7d1f8", "type": "ui\_form", "z": "463e8e92.d82a78", "name": "", "label": "Check code:", "group": "91563061.fc448", "order": 4, "width": 0, "height": 0, "options": [{ "label": "Enter the PIN code you received", "value": "code", "type": "text", "required": true }], "formValue": { "code": "" }, "payload": "", "submit": "submit", "cancel": "delete", "topic": "", "x": 390, "y": 340, "wires": [[] ] }, { "id": "91563061.fc448", "type": "ui\_group", "z": "", "name": "Verify Demo Input Fields", "tab": "fdce8e2a.f4364", "disp": false, "width": "8", "collapse": false }, { "id": "fdce8e2a.f4364", "type": "ui\_tab", "z": "", "name": "Verify Demo", "icon": "dashboard", "disabled": false, "hidden": false }]

When you’re ready, your editor should look similar to this:

To see your UI, navigate to http://127.0.0.1:1880/ui.

Verifying your user

Once we’ve collected a user’s phone number, we can start the verification process by sending a verify request to the Verify API.

Start Verification

To start a verification, you’ll need a sendverify node wired to the form capturing the user’s phone number. By default, this will send a short custom text and a PIN code in an SMS message to the user’s phone number, followed by two text-to-speech phone calls in case they fail to submit the received code.

Open up the sendverify node properties by double-clicking on it. There you’ll find the three required fields that you’ll need to fill in: Nexmo Credentials, To {} and Brand {}.

Note the {} next to the labels, which means that those fields will support Mustache Templating and you will be able to pass in values dynamically.

From the Nexmo Credentials drop-down select Add new nexmobasic and click the edit button. You will then be prompted to provide your API Key and API Secret to authenticate with the Verify API – both of these can be found in your Nexmo Dashboard.

Once you’re done, click add. Now next to the Nexmo Credentials label you’ll see a config node, this will be storing your credentials going forward.

Next, you’ll have to pass your user’s phone number into the To {} field. If you imported the UI snippet above, this will be {{msg.payload.number}}, since we specified in the first form node that the input value is to be collected in the number key of msg.payload. You can change this by opening up the form node properties and choosing a different Name.

Finally, you can personalize the verification request SMS body under Brand {} to help users identify your company or application name. It takes an 18-character alphanumeric string that will be prepended to the PIN number generated by the Verify API.

For example: “Your Acme Inc PIN is …”

The sendverify node outputs the API response received from Nexmo, containing a request_id and a status parameter. Find out more about the status codes in the Verify API Reference.

The request_id will be used for all following steps, so we have to make it accessible by all other nodes in the current flow. To do this, connect a change node to sendverify , open up its node properties and set flow.request_id to msg.payload.request_id.

To have a bit more insight into what’s happening, you can also wire a debug node into sendverify. This way you can follow the API response in the debug sidebar.

Check PIN Code

The request has successfully been accepted by Nexmo, your user has received a verification code and has already submitted it through the corresponding form. Success? Almost.

Now we have to figure out if the submitted code is indeed the one generated and sent by the Verify API.

For this step we’ll need the checkverify node, which will take as input the Request ID and the Code supplied by the user, compare the two, then output the API response into msg.payload.

After dragging it into your workspace, wire it to the form capturing the PIN code submitted by the user, then connect a debug node after it to see the response object in the debug sidebar.

Open up the checkverify node properties. From the Nexmo Credentials drop-down select the config node created by sendverify , fill in the Request ID {} field with {{flow.request_id}} and pass the code submitted by your user into the Code {} field.

If you imported the UI snippet above, this will be {{msg.payload.code}}, since we specified in the second form node that the input value is to be collected in the code key of msg.payload. You can change this by opening up the form node properties and picking a different Name.

Congrats! Your Verify flow is up and running, go to http://localhost:1880/ui and give it a try!

After submitting the received PIN code, go back to your Node-RED Editor and have a closer look at the debug sidebar.

The response object will contain details about your request including status, which indicates whether it has been successful or not. If the PIN submitted by the user matches the one generated by the Verify API, status will have a value of "0".

Check Verification Status

Although the user’s phone number has been successfully validated, there is no sign of this event besides the debug sidebar at this moment.

To define what is to happen after the verification process has ended, we can use the status property of msg.payload to separate the different scenarios.

You might want to grant access to this user to a certain webpage or application, save the successfully verified user’s details into a database, or let them know what the result was and prompt them to try again in case it had failed. It really all depends on your use case and why you are trying to verify your users in the first place.

To keep things simple, we are going to evaluate the status property, then based on its value let the user know whether the verification has been successful or not. If you’d like to be more precise with your error messages, feel free to add more routes for other status codes as well.

To do this, we’ll need:

– a switch node to check the value of msg.payload.status

– a notification dashboard node to inform the user

– two change nodes to prepare the message the notification node is going to display – one in case of success and one in case of a failed attempt.

Add these nodes into your workspace and connect them as seen in the picture below.

Now, let’s have a closer look at each of these nodes:

`switch`

The switch node routes messages based on their property values or sequence position. In this case, we’re looking to create two routes based on the value of msg.payload.status.

When a message arrives, the node will evaluate each of the rules defined in its node properties, and forward the message to the corresponding outputs of any matching rules.

First, double-click on the switch node to access its properties. In the Property field replace “payload” with “status”, so that it’s msg.payload.status that gets evaluated.

Next, we have to define rules based on its value.

Click on the add button to add a second rule, as we will be needing two:

success: in the first rule, select “==” from the first drop-down and write a “0” in the text field next to it;
failure: in the second rule, select “!=” from the first drop-down and write a “0” in the text field next to it. This will cover all cases when the verification is not a success.

Note how the rules have a -> 1 and a -> 2 sign next to them. This indicates that if the first statement is true, nodes connected to the first output will be triggered. In all other cases, the ones wired into the second output will be set off.

`notification`

The notification node shows msg.payload as a pop-up notification or an OK/Cancel dialog message on the user interface. You can choose the type of notification from the Layout drop-down in the node properties, and in case of a pop-up, you can also configure its position.

Set the duration in the Timeout (S) field by entering the number of seconds you wish to keep it visible on the UI.

If you’d like to set a title, you can do so in the Topic field, or in case a msg.topic is available it will be used as the title.

It’s possible to further customize the experience by defining a border colour, either in the Border field or by passing it in dynamically in msg.highlight.

`change`

In the change nodes we’ll be using the Set operation to specify the values of msg.payload and msg.highlight.

Let’s open up the node properties of the first change node (make sure it’s wired into the first output of the switch node, our success scenario). Set msg.payload to a success message like “Successful verification!”, click the add button to define a second rule, and set msg.highlight to “green”.

Repeat the same steps for the second change node, but this time give msg.payload “Verification failed!” as value and set msg.highlight to “red”. Also, make sure it’s connected into the second output of the switch node.

Hit Deploy and give it another try! Now, when the verification process completes, you’ll see a pop-up appear with the result!

Next Verification

Once the verification process has started, Nexmo will make three attempts at delivering the PIN code to the submitted phone number: an SMS message and two text-to-speech(TTS) phone calls.

There are times when a phone call is the better option, be it for accessibility reasons or out of pure personal preference. It’s always a nice touch to give our users the option to choose an alternative delivery method, so let’s have a look at implementing a button that would escalate the verification process to a TTS call instantly.

In the provided flow template, find the Call Me button and connect a nextverify node into it. Open up the nextverify node properties, select your Nexmo Credentials from the drop-down menu and fill in the Request ID {} field with {{flow.request_id}}.

You might want to also consider adding a debug node for a bit more insight on your end, and a change node followed by a notification node to let the user know what’s going on – just like you did at the previous step, but it’s completely optional.

Cancel Verification

In an ideal world we would stop here, but something always comes up, doesn’t it? You’ve made a mistake while filling in a form and hit submit – too late to change your mind and hit that Delete now, the verification has already started.

You might think you could just wait it out and try again once it’s failed. Yes, that works as well, but it’s not an ideal way to go about it. Besides giving a frustrating experince to your users, think about the poor unsuspecting soul that ends up getting two phone calls in addition to that initial verification message – at 2am. Oops.

Fortunately, there’s a quick and easy way of implementing a Cancel Verification button.

If you imported the provided UI snippet, all you need to do is connect a cancelverify node into the Cancel Verification button’s output, open up the cancelverify node properties, select your Nexmo Credentials from the drop-down menu and fill in the Request ID {} field with {{flow.request_id}}.

You could also add a debug node to see the response object in the debug sidebar, and a change node followed by a notification node to let the user know it has successfully been cancelled.

Now hit that Deploy button and test it out! Keep in mind that for a cancel request to be valid, it has to be initiated at least 30 seconds after the phone number has been submitted. Still plenty of time to avoid that TTS call being initiated!

Et voilà! With your safety guard in place, you can now sleep better at night – and so can all the unsuspecting strangers you’ll be verifying as well. Good job!

Extra Credit – Search Verification

You can already follow the flow of the verification process in the debug sidebar, since every return object received from the Nexmo API is logged by a debug node, and it provides valuable insight into what’s happening.

Sometimes the debug area can get a little crowded, making it hard to pinpoint the piece of information you’re looking for. Besides that, you might want to check on your verification in between events, not having to wait for the next one to occur in order for another return object to pup up. It might have already completed, but you’re not exactly sure whether it failed or completed successfully.

The good news is, there’s a searchverify Nexmo node that takes care of all these concerns. Being triggered by, let’s say, an inject node, it will output all available information about a past or current verification request identified by a request_id.

Add a searchverify node to your workspace, wire it between an inject and a debug node. In the searchverify node properties select your Nexmo Credentials from the drop-rown menu and fill in the Request ID {} field with {{flow.request_id}} to get details about the current verification. You could also paste in a specific request_id in this field, in case you wanted to check on a verification that took place before the current one.

Now when you look at the debug sidebar, after taking your app for a spin, you’ll notice that every time you click on the inject node’s button in your editor it will return an object with all available details about the request in question. Have a closer look at the response fields and head over to the Nexmo API Reference to find out more about each of them.

Where next?

Nexmo Verify API Reference
Verify Documentation

Try another tutorial:

– How to Stream Audio into a Call with Node-RED

– How to Make Text-to-Speech Phone Calls with Node-RED

– How to Receive Phone Calls with Node-RED

– Announcing the Nexmo Node-RED Package

– How to Send SMS Messages with Node-RED

– How to Receive SMS Messages with Node-RED

Forem: Julia Biro

Introducing the Vonage Voice API on Zapier

The Vonage Voice API

Zapier 101

Vonage Voice API Triggers

Vonage Voice API Actions

Where Next?

Further Reading

Using Variables and Chaining Requests in Postman

Prerequisites

Variables are Your Friends

Chaining Requests

The Pre-Request Script

Tests: Why Not Post-Request Script?

The Request Body

Where Next?

Announcing the Vonage APIs Postman Collection

Using the Vonage APIs Postman Collection

Where Next?

Build a ‘Clock in’ Service With the Shortcuts iOS App

Prerequisites

Vonage API Account

What Is Shortcuts?

Actions

Build Your Shortcut

1. Get a Virtual Number

2. Create a New Shortcut

3. Action 1: Ask for Input

4. Action 2: Get Contents of URL

5. Action 3: Append to File

Get a “Beautiful Morning Weather” alert with Zapier and Vonage

Prerequisites

Vonage API Account

A Word about Zapier

What is Zapier?

Common Terms: Learn to Speak Zapier

Zap

Trigger

Action

Task

Build Your Zap

The Trigger: Schedule by Zapier

Action 1: Get Weather Data with Weather by Zapier

Action 2: Set Conditions with Filter by Zapier

Action 3: Create Call with Vonage Voice

Extra Credit

Action 4: Send Weather Data with Vonage SMS

What’s Next?

I'm Julia, and We Deserve to Be Here

I Deserve Credit for...

In 2020 I Continue to Code

I Hope to See...

My Message for Others

Sending Group Notifications with Google Sheets and Node-RED

Prerequisites

Setting Up Your Editor

Configuring Your Google Account

Step 1: Create a New Service Account

Step 2: Enable Google Sheets API for Your Project

Step 3: Sharing Google Sheets with Your Service Account

Sending Group Notifications with Google Sheets and Node-RED

Create a Spreadsheet

Getting the Data from Your Google Sheet

Split the msg.payload Array

Set Delay

Preparing the Message

Sending SMS Notifications

Delivery Receipts

Where Next?

Extra Credit: Write Your Delivery Receipts to the Google Sheet

Pick Your Data

Write Your Data to the Google Sheet

Further Hack Ideas

Resources

Try Another Tutorial

How to Build an IVR using Node-RED and the Nexmo APIs

Dependencies

Prerequisites

Getting Your Credentials

Setting Up Your Node-RED Editor

`talk`

`input`

`voice webhook`

`switch`

`talk`

`return NCCO`

`Send SMS`

`talk`

`record`

`change`

`e-mail`