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.
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:
- Open a terminal like GitBash, PowerShell, or the like.
- Type
node-red
and pressEnter
.
You should see an output similar to:
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.
- Once you have your Node-RED editor open, go to the
Manage palette
menu. - Search for the
node-red-contrib-credentials
package. - 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.
- Download the tutorial flow JSON code: Download from GitHub:
Send_SMS_with_Node-RED_flow.json
. - Right-click on the file and select
Save link as
. - Save the file on your machine.
- In the Node-RED editor, click on the menu and select
Import
. - Click
Select file to import
. - Select the file you have downloaded from GitHub and click
Open
. - 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
- Create an account on FRED: Front End For Node-RED.
- Select the free
FRED Short plan
and sign up. - 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 forCredentials
. - 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.
- Download the tutorial flow JSON code: Download from GitHub:
Send_SMS_with_Node-RED_flow.json
. - Right-click on the file and select
Save link as
. - Save the file on your machine.
- In the Node-RED editor, click on the menu on the right and select
Import
. - Click
Select file to import
. - Select the file you have downloaded from GitHub and click
Open
. - 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 aPOST
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 thecredentials
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:
- Double-click on the
Set credentials
node. - Copy and paste your client ID into the field on the right of
az
, abovemsg.client_id
. - Copy and paste your client secret into the field on the right of
az
, abovemsg.client_secret
. - Click
Done
. - 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
- Double-click the node
Set SMS number and content
. - Enter the mobile phone number of the recipient in the field on the right of
az
, abovemobile_number
. - Enter the content into the field on the right of
az
, abovecontent
. For example: "Caution! Temperature of device xxx is now higher than allowed!" - Click
Done
. - Now click
Deploy
to save the changes to the flow.
Trigger the SMS API request
-
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. -
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: