In this blog post, we will use Node.js to build a simple library (Node.js) package that will enable us to send SMS messages over Infobip API using a single function call. The developed library can then be used in any number of projects to send any number of basic SMS text messages, with a minimum amount of configuration needed.<\/p>\n\n\n\n
We also have a Node.js SDK<\/a> which should get you up and running in no time. Note that the example below creates a Node.js project from scratch with no packages or libraries.<\/p>\n\n\n\n This post assumes basic knowledge of JavaScript, Node.js, and HTTP.<\/p>\n\n\n\n We will begin by setting up an empty Node.js project.\nInside an empty directory (let’s call it Our project will be very simple – we will only need one dependency. We’ll add a popular open-source HTTP client library called Axios<\/a>.\nInside your project directory, run<\/p>\n\n\n\n You’ll notice that Our goal is to create a function with a signature.<\/p>\n\n\n\n Which we could use to send a single SMS message at a time.<\/p>\n\n\n\n The parameters to use:<\/p>\n\n\n\n The function will need to do the appropriate HTTP POST call to Infobip Send SMS API<\/a> in order to send the SMS message. To implement it, we will split the work into three parts: constructing the URL, constructing request headers, and constructing the request body.<\/p>\n\n\n\n The URL will always look like this: The request to Infobip API needs to contain appropriate HTTP headers for authentication purposes, as described in the documentation<\/a>. We will use the “API Key Header” authentication method, placing the API key into the The Once the HTTP request is executed, the response body will differ depending on whether the request was a success or a failure. Here, we’ll parse the response from the Axios HTTP client to a simple object containing a We’ll add two more helper functions. One is to serve as a validation helper, to ensure that the Finally, we have everything needed to put together for the To test out the code, we can put all the functions described so far in a single file called Now, create a file Replace the placeholders with your actual API key, domain, and phone number, and that’s it, you can now run Note:<\/strong> You can also download the completed project source files here<\/a>).<\/p>\n\n\n\n Here is an example output in case of success, indicating that the message was accepted and is pending delivery:<\/p>\n\n\n\n Here, is an example response returned in the case that the provided API key is invalid:<\/p>\n\n\n\n For more details on status and error codes, visit documentation<\/a>.<\/p>\n\n\n\nPrerequisites<\/h2>\n\n\n\n
\n
Difficulty level<\/h2>\n\n\n\n
Set up an empty Node.js project<\/h2>\n\n\n\n
sendsms<\/code>), run the npm init<\/code> command to initialize a new Node.js project. You will need to answer a few questions that will be asked by npm<\/code>, like the name and the version of the project. You can accept all the defaults suggested by npm<\/code>, or fill out some information according to your preferences. In the end, npm<\/code> will generate a package.json<\/code> file containing something like:<\/p>\n\n\n\n{\n "name": "sendsms",\n "version": "1.0.0",\n "description": "a simple Node.js project to send SMS messages",\n "main": "index.js",\n "scripts": {\n "test": "echo \\"Error: no test specified\\" && exit 1"\n },\n "author": "",\n "license": "ISC"\n}<\/code><\/pre><\/div>\n\n\n\nAdd dependencies<\/h2>\n\n\n\n
npm install axios<\/code><\/pre><\/div>\n\n\n\naxios<\/code> was added under dependencies<\/code> inside your package.json<\/code> file.<\/p>\n\n\n\nAdd the Send SMS API call<\/h2>\n\n\n\n
sendSms(config, destinationNumber, message)<\/code><\/pre><\/div>\n\n\n\n\n
config<\/code> is an object with data, needed to execute the actual HTTP request against Infobip API.\\<\/li>\n\n\n\nbaseUrl<\/code> (e.g. 8935q9.api.infobip.com<\/code>) and your Infobip APIkey<\/code> that you can access from within your Infobip account. You would typically store such information somewhere in your application’s configuration.\\<\/li>\n\n\n\ndestinationNumber<\/code> is the phone number (MSISDN) of the handset to which you want to send an SMS message. It must be in international format – that is, prefixed with the country and network prefix.<\/li>\n\n\n\nmessage<\/code> is the actual text of the SMS message that you want to send.<\/li>\n<\/ul>\n\n\n\nConstruct a URL<\/h3>\n\n\n\n
https:\/\/<your-custom-domain>\/sms\/2\/text\/advanced<\/code>. We can create a helper function that will use the custom domain from the configuration to build the correct URL:<\/p>\n\n\n\nconst buildUrl = (domain) => { \n return `https:\/\/${domain}\/sms\/2\/text\/advanced`; \n }<\/code><\/pre><\/div>\n\n\n\nConstruct request headers<\/h3>\n\n\n\n
Authentication<\/code> header. We’ll also provide a header for the content type – we’ll be using JSON<\/code>.<\/p>\n\n\n\nconst buildHeaders = (apiKey) => { \n return { \n 'Content-Type': 'application\/json', \n 'Authorization': `App ${apiKey}` \n }; \n }<\/code><\/pre><\/div>\n\n\n\nConstruct a request body<\/h3>\n\n\n\n
\/sms\/2\/text\/advanced<\/code> endpoint expects SMS message properties to be provided in the HTTP request body. We only need two properties for the basic case, the destination phone number and the message text. Following the format for the message body provided in the documentation<\/a>, we can make a helper function for that, too:<\/p>\n\n\n\nconst buildRequestBody = (destinationNumber, message) => { \n const destinationObject = { \n to: destinationNumber \n }; \n const messageObject = { \n destinations: [destinationObject], \n text: message \n }; \n return { \n messages: [messageObject] \n } \n }<\/code><\/pre><\/div>\n\n\n\nHandling API responses<\/h3>\n\n\n\n
success<\/code> boolean flag and message status information in case of success, or the error message in case of failure.<\/p>\n\n\n\nconst parseSuccessResponse = (axiosResponse) => { \n const responseBody = axiosResponse.data; \n const singleMessageResponse = responseBody.messages[0]; \n return { \n success: true, \n messageId: singleMessageResponse.messageId, \n status: singleMessageResponse.status.name, \n category: singleMessageResponse.status.groupName \n }; \n } \n \n const parseFailedResponse = (axiosError) => { \n if (axiosError.response) { \n const responseBody = axiosError.response.data; \n return { \n success: false, \n errorMessage: responseBody.requestError.serviceException.text, \n errorDetails: responseBody \n }; \n } \n return { \n success: false, \n errorMessage: axiosError.message \n }; \n } <\/code><\/pre><\/div>\n\n\n\nAdd helper functions<\/h3>\n\n\n\n
sendSms<\/code> function is called with the correct arguments. The other one is a helper function that wraps HTTP headers in an object as required by Axios’s POST<\/code> function.<\/p>\n\n\n\n const validateNotEmpty = (value, fieldName) => {\n if (!value) {\n throw `${fieldName} parameter is mandatory`;\n }\n }\n\n const buildAxiosConfig = (apiKey) => {\n return {\n headers: buildHeaders(apiKey)\n };\n }<\/code><\/pre><\/div>\n\n\n\nSend an SMS message<\/h2>\n\n\n\n
sendSms<\/code> function. The code itself is very straightforward:<\/p>\n\n\n\nconst sendSms = (config, destinationNumber, message) => {\n validateNotEmpty(config.domain, 'config.domain');\n validateNotEmpty(config.apiKey, 'config.apiKey');\n validateNotEmpty(destinationNumber, 'destinationNumber');\n validateNotEmpty(message, 'message');\n \n const url = buildUrl(config.domain);\n const requestBody = buildRequestBody(destinationNumber, message);\n const axiosConfig = buildAxiosConfig(config.apiKey);\n\n return axios.post(url, requestBody, axiosConfig)\n .then(res => parseSuccessResponse(res))\n .catch(err => parseFailedResponse(err));\n }<\/code><\/pre><\/div>\n\n\n\nsend.js<\/code> in the root of our project. \nWe want to export the sendSms()<\/code> function to use it elsewhere, so place the export at the end of the file:<\/p>\n\n\n\n module.exports = sendSms;<\/code><\/pre><\/div>\n\n\n\nindex.js<\/code> inside the same directory (project root). We can import the send<\/code> module and use it to send an SMS. We’ll just log the results to the console. Remember that if your Infobip account is in free trial mode, you can only send SMS to the phone number you used to create your Infobip account.<\/p>\n\n\n\nconst sendSms = require('.\/send.js'); \n const config = { \n domain: '<your-domain-here>', \n apiKey: '<your-api-key-here>'\n };\n sendSms(config,'<your-phone-number-here>', `hello world` ).then(result => console.log(result));<\/code><\/pre><\/div>\n\n\n\nnode index.js<\/code> to send an SMS message!<\/p>\n\n\n\n{\n "messages": [\n {\n "messageId": "3818998573364335793292",\n "status": {\n "description": "Message sent to next instance",\n "groupId": 1,\n "groupName": "PENDING",\n "id": 26,\n "name": "PENDING_ACCEPTED"\n },\n "to": "447515774433"\n }\n ]\n}<\/code><\/pre><\/div>\n\n\n\nCommon errors<\/h2>\n\n\n\n
{\n "requestError": {\n "serviceException": {\n "messageId": "UNAUTHORIZED",\n "text": "Invalid login details"\n }\n }\n}<\/code><\/pre><\/div>\n\n\n\n