How to build a public ClickSend SMS integration: Building the Auth Flow

Aug 11, 2024 • 7 minute read

Hey there, fellow JavaScript enthusiast! Ready to dive into the world of SMS integrations? Today, we're going to walk through building a public ClickSend SMS integration, with a special focus on nailing that authorization flow. Don't worry, I've got your back – we'll keep things concise and to the point, just the way we like it.

Introduction

So, you want to add SMS capabilities to your app? Smart move! ClickSend's SMS API is a great choice, but before we can start sending those messages, we need to set up a rock-solid authorization flow. This is crucial for keeping your users' data safe and ensuring smooth sailing with the API.

Prerequisites

Before we jump in, make sure you've got:

A ClickSend account with API credentials
Node.js and npm installed on your machine
A basic understanding of OAuth 2.0 (don't sweat it if you're a bit rusty)

Setting up the project

Let's get our project off the ground:

mkdir clicksend-sms-integration
cd clicksend-sms-integration
npm init -y
npm install express axios dotenv

Configuring environment variables

Create a .env file in your project root and add your ClickSend credentials:

CLICKSEND_CLIENT_ID=your_client_id
CLICKSEND_CLIENT_SECRET=your_client_secret
CLICKSEND_REDIRECT_URI=http://localhost:3000/callback

Creating the authorization endpoint

Now, let's set up our authorization endpoint:

require('dotenv').config();
const express = require('express');
const crypto = require('crypto');
const app = express();

const states = new Map();

app.get('/auth', (req, res) => {
  const state = crypto.randomBytes(16).toString('hex');
  states.set(state, Date.now());
  
  const authUrl = `https://auth.clicksend.com/authorize?` +
    `response_type=code&` +
    `client_id=${process.env.CLICKSEND_CLIENT_ID}&` +
    `redirect_uri=${encodeURIComponent(process.env.CLICKSEND_REDIRECT_URI)}&` +
    `state=${state}`;
  
  res.redirect(authUrl);
});

Handling the callback

Time to handle that callback:

const axios = require('axios');

app.get('/callback', async (req, res) => {
  const { code, state } = req.query;
  
  if (!states.has(state)) {
    return res.status(400).send('Invalid state parameter');
  }
  
  states.delete(state);
  
  try {
    const response = await axios.post('https://auth.clicksend.com/token', {
      grant_type: 'authorization_code',
      code,
      redirect_uri: process.env.CLICKSEND_REDIRECT_URI,
      client_id: process.env.CLICKSEND_CLIENT_ID,
      client_secret: process.env.CLICKSEND_CLIENT_SECRET
    });
    
    // Store tokens securely (more on this later)
    const { access_token, refresh_token } = response.data;
    
    res.send('Authorization successful!');
  } catch (error) {
    res.status(500).send('Error during token exchange');
  }
});

Storing and refreshing tokens

For the sake of this example, we'll use in-memory storage. In a real-world scenario, you'd want to use a secure database:

let tokens = {
  access_token: null,
  refresh_token: null,
  expires_at: null
};

function storeTokens(access_token, refresh_token, expires_in) {
  tokens = {
    access_token,
    refresh_token,
    expires_at: Date.now() + expires_in * 1000
  };
}

async function refreshTokenIfNeeded() {
  if (Date.now() >= tokens.expires_at) {
    try {
      const response = await axios.post('https://auth.clicksend.com/token', {
        grant_type: 'refresh_token',
        refresh_token: tokens.refresh_token,
        client_id: process.env.CLICKSEND_CLIENT_ID,
        client_secret: process.env.CLICKSEND_CLIENT_SECRET
      });
      
      storeTokens(response.data.access_token, response.data.refresh_token, response.data.expires_in);
    } catch (error) {
      console.error('Error refreshing token:', error);
      throw error;
    }
  }
}

Implementing a simple SMS sending endpoint

Let's put our auth flow to work:

app.post('/send-sms', async (req, res) => {
  try {
    await refreshTokenIfNeeded();
    
    const response = await axios.post('https://rest.clicksend.com/v3/sms/send', {
      messages: [
        {
          body: 'Hello from our ClickSend integration!',
          to: '+1234567890'
        }
      ]
    }, {
      headers: {
        'Authorization': `Bearer ${tokens.access_token}`,
        'Content-Type': 'application/json'
      }
    });
    
    res.json(response.data);
  } catch (error) {
    res.status(500).send('Error sending SMS');
  }
});

Error handling and edge cases

Always be prepared for the unexpected:

app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).send('Something broke!');
});

Testing the integration

Fire up your server and give it a whirl:

node app.js

Visit http://localhost:3000/auth in your browser and follow the flow. If all goes well, you should be able to send an SMS by hitting the /send-sms endpoint.

Conclusion

And there you have it! We've built a solid foundation for a ClickSend SMS integration with a secure authorization flow. Remember, this is just the beginning – you can expand on this to add more features, improve error handling, and make it production-ready.

Additional resources

Keep coding, stay curious, and happy SMS-ing!