Send SMS with KPN SMS API and Node-RED

Happy with this tutorial and want to test the KPN SMS API more? Head over to the documentation and the API reference for all the information you need to use the API.

Go to KPN SMS documentation

Introduction

The KPN SMS API allows you to send an SMS using a simple HTTP-based API. In this tutorial, you are going to use Node-RED to integrate the API into your own (fictional) application.

Have a look

What is Node-RED

Node-RED is a browser-based programming tool for wiring together hardware devices, APIs and online services in new and interesting ways. It is based on Node.js. It provides an editor with which you can wire together flows using the wide range of nodes in the palette that can be deployed to its runtime in a single click. Flows are individual programs. They consist of several nodes that perform a single task on a message object, which is passed down the flow. Flows are easy to create and there are a lot of free nodes and flows available. Find out more about Node-RED.

What you’ll learn

• How to install Node.js, Node-RED. Alternatively, you could try this tutorial in the Node-RED cloud solution.
• How to configure and connect Node-RED flows.
• How to obtain an access token (bearer token) from the KPN Developer Portal.
• How to send an SMS by triggering a Node-RED flow.
• How to debug flows to catch errors or success messages.

What you’ll need

• For running Node-RED locally, you'll need to:

  • Install the Node.js JavaScript runtime environment
  • Install or run Node-RED.
  • Open the Node-RED editor.
  • Install the Node-RED credentials package. *Import the tutorial flow.

You follow a slightly different route to get set up if you decide to use Node-RED via the cloud. Then step 1 and 2 are replaced by a single step in which you set up the Node-RED cloud solution. The rest of the steps are essentially the same, though the execution is slightly different. It will all become clear in the description of the tutorial steps below.

• For running Node-RED in the cloud, you'll need to:

  • Create an account on FRED (Front End For Node-RED.
  • Install the Node-RED credentials package.
  • Import the tutorial flow.

1. Getting set up

Running Node-RED locally

1. Install Node.js

If there is no version of Node.js already installed on your system, you need to install a version, preferably the latest.

• Go to Download Node.js to find the appropriate version for your system.

2. Install Node-RED

There are many options on how to install or run Node-RED.

• Go to Running Node-RED locally.

3. Start the Node-RED editor

After you have installed the necessary components, it is time to start the Node-RED editor:

1. Open a terminal like GitBash, PowerShell, or the like.
2. Type node-red and press Enter.

You should see an output similar to:

      
      
        Code copied
        
            
      
28 Aug 13:04:55 - [info]

Welcome to Node-RED
===================

28 Aug 13:04:56 - [info] Node-RED version: v1.1.1
28 Aug 13:04:56 - [info] Node.js  version: v12.18.2
28 Aug 13:04:56 - [info] Windows_NT 10.0.18363 x64 LE
28 Aug 13:04:57 - [info] Loading palette nodes
28 Aug 13:05:01 - [info] Settings file  : \Users\xxx\.node-red\settings.js
28 Aug 13:05:01 - [info] Context store  : 'default' [module=memory]
28 Aug 13:05:01 - [info] User directory : \Users\xxx\.node-red
28 Aug 13:05:01 - [warn] Projects disabled : editorTheme.projects.enabled=false
28 Aug 13:05:01 - [info] Flows file     : \Users\xxx\.node-red\flows_DESKTOP-NSQIT41.json
28 Aug 13:05:01 - [info] Server now running at http://127.0.0.1:1880/
28 Aug 13:05:01 - [warn]
28 Aug 13:05:01 - [info] Starting flows
28 Aug 13:05:01 - [info] Started flows

Now you can access the Node-RED editor at http://localhost:1880.

4. Install the credentials node

Install the node-red-contrib-credentials package to store your KPN Developer Portal credentials securely.

1. Once you have your Node-RED editor open, go to the Manage palette menu.
2. Search for the node-red-contrib-credentials package.
3. When you have found it, click Install.

Example: Import credentials node - local

5. Import the tutorial flow

Node-RED makes it easy to save, share and move flows between computers using the export and import features. Import a flow by using the Import nodes dialog.

1. Download the tutorial flow JSON code: Download from GitHub: Send_SMS_with_Node-RED_flow.json.
2. Right-click on the file and select Save link as.
3. Save the file on your machine.
4. In the Node-RED editor, click on the menu and select Import.
5. Click Select file to import.
6. Select the file you have downloaded from GitHub and click Open.
7. Click Import.

The imported flow is visible in a new tab called KPN-SMS. You can now go to the step Send the SMS.

Example: Import tutorial flow - local

Running Node-RED in the cloud

The cloud solution allows you to run Node-RED without any installation. Just sign up to a free demo account.

Note: This is an external solution and KPN is not responsible for its availability.

1. Set up the cloud solution

1. Create an account on FRED: Front End For Node-RED.
2. Select the free FRED Short plan and sign up.
3. Log into the account. The Node-RED online editor will start up and display example flows on the tab Sheet1. You can ignore that.

2. Install the credentials node

• Once you have your cloud Node-RED editor open, go to the Tools menu on the left.
• Select Add or Remove Nodes.
• In the field Search nodes search for Credentials.
• When you have found it, click Install.
• After the node has been installed, click Restart Instance.

Now you can import the tutorial flow (see the next step below).

Example: Import credentials node - cloud

3. Import the tutorial flow

Node-RED makes it easy to save, share and move flows between computers using the export and import feature. You can import a flow by using the Import nodes dialog.

1. Download the tutorial flow JSON code: Download from GitHub: Send_SMS_with_Node-RED_flow.json.
2. Right-click on the file and select Save link as.
3. Save the file on your machine.
4. In the Node-RED editor, click on the menu on the right and select Import.
5. Click Select file to import.
6. Select the file you have downloaded from GitHub and click Open.
7. Click Import.

The imported flow is visible in a new tab called KPN-SMS. You can now go to the step Send the SMS.

Example: Import tutorial flow - cloud

Flow description

The tutorial flow appears in a new tab. As you can see, the flow is divided into 3 parts:

• The first flow imitates a temperature sensor. It creates random numbers at intervals. As soon as the number is 40 or higher, the next flow is triggered.
• The second flow obtains the access token from the KPN Developer Portal by invoking an Authorization API using a POST method.
• The third flow is the actual Send SMS request that accesses the /send endpoint of the API using a POST method.

KPN SMS API flow

Have a look at the different nodes in the flow:

• Input nodes are used to input data into a Node-RED application or flow. They have at least one output endpoint, which is shown in the small grey square on their right side. Input nodes allow you to connect data from other services, such as Twitter or temperature sensors, to manually input data into a flow using the blue timestamp node.

• Output nodes are used to send data outside of a Node-RED flow. They have a single input endpoint on their left side. Output nodes allow you to send data to other services such as Twitter, or to send data to the debug messages window in the sidebar. You can use green debug nodes to display the success and error messages. Switch them off and on by clicking on the button on the right side.

• Processing nodes are used to process data. They have one input endpoint on their left side and one or more output endpoints on their right side. You can use them to do stuff, such as creating random numbers, and use the data to trigger a message and to write custom code as we do with the orange function nodes.

• Security nodes such as the red credentials node are used to store sensitive data that is passed on in the API request, such as API keys, telephone numbers, user credentials, and so on. If you copy or export the credentials node, the data stored in the node will not be copied or exported.

2. Send the SMS

This is the easy bit. Just add your KPN Developer Portal credentials, the telephone number you want to send the SMS to and the content of the SMS.

If you need more information about the API endpoints and request parameters please refer to the API reference on SwaggerHub.

Add your KPN Developer Portal credentials

In order to interact with the KPN SMS API, you’ll need to do a couple of things. Log into your KPN Developer Portal account, and go to the Sandbox to find your client ID and client secret. Copy them or make a note of them. Then add these credentials to the secure Set credentials node:

1. Double-click on the Set credentials node.
2. Copy and paste your client ID into the field on the right of az, above msg.client_id.
3. Copy and paste your client secret into the field on the right of az, above msg.client_secret.
4. Click Done.
5. Click Deploy to save the changes to the flow.

Note: Protect your KPN Developer Portal credentials like you protect your passwords.

Add the mobile phone number and content

1. Double-click the node Set SMS number and content.
2. Enter the mobile phone number of the recipient in the field on the right of az, above mobile_number.
3. Enter the content into the field on the right of az, above content. For example: "Caution! Temperature of device xxx is now higher than allowed!"
4. Click Done.
5. Now click Deploy to save the changes to the flow.

Trigger the SMS API request

1. Click the blue button on the left of the blue timestamp node to trigger a random number. You can see the number in the debug messages window.

2. As soon as the random number is 40 or higher, the KPN SMS API is triggered and an SMS is on its way to the recipient.

Note: Don't exceed your API request limit in demo mode. If the flow is working as expected, disconnect the Random temperature generator flow from the Obtain access token flow and click Deploy.

Send the API request

Success message

Congratulations

Congratulations, you have successfully sent an SMS with the KPN SMS API and Node-RED.

You have learnt how to import flows into Node-RED and how to add your credentials and the payload of the API call.

Get help

Don't hesitate to contact us if you have any questions about this tutorial.

What’s next?

Check out some of these tutorials:

• How to receive an SMS in a PHP application.
• Use the WeSeeDo API with Node-RED.