Build Two-Way SMS with MessageBird, Node.js & Express

Learn how to build a production-ready two-way SMS communication system using Node.js, Express, and the MessageBird API. This comprehensive tutorial walks you through creating an application that receives incoming SMS messages via webhooks, processes them in a ticketing system, and sends automated replies back to users.

Whether you're building customer support systems, SMS notifications, or interactive messaging services, this guide provides everything you need to implement reliable, scalable, and secure SMS communication. You'll master webhook configuration, message handling, database integration, and essential security practices for MessageBird SMS applications.

Note: This guide uses Express.js and MongoDB. The filename references Next.js and Supabase, but the implementation demonstrates core concepts applicable to any Node.js framework.

Project Overview and Goals

What You'll Build:

• An Express.js web server running on Node.js
• A webhook endpoint to receive incoming SMS messages from MessageBird
• Logic to process incoming messages, associate them with users (based on phone number), and store conversation history (in-memory initially, then database)
• Functionality to send outgoing SMS messages (replies) via the MessageBird API
• Basic security measures, including webhook signature verification
• Configuration management using environment variables

Technologies:

• Node.js: Asynchronous JavaScript runtime for building server-side applications
• Express.js: Minimalist Node.js web application framework for handling HTTP requests, routing, and middleware
• MessageBird: Communications Platform as a Service (CPaaS) for sending and receiving SMS via API and webhooks
• dotenv: Module to load environment variables from a .env file
• MongoDB & Mongoose (Optional but Recommended): For persistent data storage

System Architecture:

+-------------+       +------------------------+       +-----------------+       +---------------------+
| User's Phone| <---->| MessageBird Platform   | ----> | Your Express App| <---->| Database (Optional) |
| (SMS)       |       | (Number, Flow Builder) |       | (Webhook/API)   |       | (MongoDB)           |
+-------------+       +------------------------+       +-----------------+       +---------------------+
       ^                      |                                |
       |                      | (API Call: Send SMS)           | (Webhook POST)
       +----------------------+--------------------------------+

How It Works:

1. A user sends an SMS to your MessageBird virtual number
2. MessageBird receives the SMS and triggers your webhook via HTTP POST with message details (sender number, content)
3. Your Express app verifies the webhook signature, processes the message (creates or updates a ticket), interacts with the database, and sends a 200 OK response to MessageBird
4. To reply, your application makes an API call to MessageBird to send an SMS back to the user's phone

Prerequisites:

• Node.js and npm (or yarn) installed – Download Node.js
• A MessageBird account – Sign up for free
• A purchased MessageBird Virtual Mobile Number (VMN) with SMS capabilities
• A tool to expose your local server to the internet (e.g., ngrok) – Download ngrok
• Basic understanding of JavaScript, Node.js, and REST APIs

How to Set Up Your Node.js Project for SMS

Initialize your Node.js project and install the necessary dependencies.

1. Create Project Directory: Open your terminal, create a new directory for your project, and navigate into it.

   bashCopy

   mkdir messagebird-sms-app
   cd messagebird-sms-app

2. Initialize Node.js Project: Create a package.json file to manage dependencies and project metadata.

   bashCopy

   npm init -y

3. Install Dependencies: Install Express for the web server, the MessageBird SDK, dotenv for environment variables, and body-parser to handle incoming request bodies.

   bashCopy

   npm install express messagebird dotenv body-parser

4. Set Up Project Structure: Create the basic files and folders.

   bashCopy

   touch index.js .env .gitignore

   • index.js: Main entry point for your application
   • .env: Stores sensitive configuration like API keys (excluded from version control)
   • .gitignore: Specifies intentionally untracked files that Git should ignore

5. Configure .gitignore: Add node_modules and .env to prevent committing dependencies and sensitive credentials.

   textCopy

   # .gitignore
   node_modules/
   .env

6. Set Up Environment Variables (.env): Open the .env file and add placeholders for your MessageBird API key, virtual number, and webhook signing key.

   dotenvCopy

   # .env
   
   # Obtain from MessageBird Dashboard (Developers -> API access)
   MESSAGEBIRD_API_KEY=YOUR_API_KEY
   
   # Your purchased MessageBird virtual number in E.164 format (e.g., +12025550135)
   MESSAGEBIRD_ORIGINATOR=YOUR_VIRTUAL_NUMBER
   
   # Obtain from MessageBird Dashboard (Developers -> Signed Requests)
   MESSAGEBIRD_WEBHOOK_SIGNING_KEY=YOUR_SIGNING_KEY
   
   # Port your application will run on
   PORT=8080

   • MESSAGEBIRD_API_KEY: Your Live API key from the MessageBird Dashboard (needed for sending messages)
   • MESSAGEBIRD_ORIGINATOR: Your MessageBird virtual number in E.164 format (e.g., +12223334444)
   • MESSAGEBIRD_WEBHOOK_SIGNING_KEY: Secret key to verify that incoming webhook requests originated from MessageBird (find or generate this in Dashboard under Developers -> API settings -> Signed Requests)
   • PORT: Local port your Express server will listen on

7. Basic Express Server (index.js): Create a minimal Express server to verify the setup.

   javascriptCopy

   // index.js
   'use strict';
   
   // Load environment variables from .env file
   require('dotenv').config();
   
   const express = require('express');
   const bodyParser = require('body-parser');
   
   // Initialize Express app
   const app = express();
   const port = process.env.PORT || 8080; // Use port from .env or default to 8080
   
   // --- Middleware ---
   // Use body-parser middleware to parse JSON request bodies
   // Important: Use raw body for signature verification BEFORE JSON parsing (See Section 7)
   app.use(bodyParser.json());
   
   // --- Basic Route ---
   app.get('/', (req, res) => {
     res.send('SMS Application is running!');
   });
   
   // --- Start Server ---
   app.listen(port, () => {
     console.log(`Server listening on port ${port}`);
   });
   
   // Export the app for potential testing
   module.exports = app;

8. Run the Server:

   bashCopy

   node index.js

   You should see Server listening on port 8080 (or your configured port). Open http://localhost:8080 in your browser to see "SMS Application is running!". Stop the server with Ctrl+C.

How to Receive SMS Messages with Webhooks

The core of receiving inbound SMS messages involves creating a webhook endpoint that MessageBird calls when an SMS arrives at your virtual mobile number. Webhooks are HTTP callbacks that enable real-time message delivery to your application.

1. Initialize MessageBird SDK: Import and initialize the SDK client using your API key from the environment variables.

   javascriptCopy

   // index.js (add near the top)
   const { initClient } = require('messagebird');
   
   // Initialize MessageBird client
   const messagebird = initClient(process.env.MESSAGEBIRD_API_KEY);
   
   // --- In-Memory Storage (Temporary) ---
   // We'll use a simple object to store conversations temporarily.
   // Replace this with a database in a production scenario (Section 6).
   const conversations = {}; // Key: User's phone number, Value: Array of messages

   • Why initClient? This function initializes the SDK with your credentials, making authenticated API calls possible.
   • Why In-Memory Storage (Initially)? It simplifies the initial setup and focuses on the webhook logic. We explicitly plan to replace it later for persistence.

2. Create the Webhook Endpoint (/webhook): This route will handle the POST requests from MessageBird.

   javascriptCopy

   // index.js (add before app.listen)
   
   // --- Webhook Endpoint ---
   app.post('/webhook', (req, res) => {
     // Note: Signature verification should happen *before* this logic (See Section 7)
     console.log('Webhook received:', JSON.stringify(req.body, null, 2));
   
     const { originator, payload, createdDatetime } = req.body; // Destructure key fields
   
     // Basic validation
     if (!originator || !payload) {
       console.error('Webhook received invalid data:', req.body);
       return res.status(400).send('Bad Request: Missing originator or payload');
     }
   
     const timestamp = createdDatetime || new Date().toISOString();
     const message = {
       direction: 'in',
       content: payload,
       timestamp: timestamp,
     };
   
     // Store or update the conversation
     if (conversations[originator]) {
       // Add message to existing conversation
       conversations[originator].push(message);
       console.log(`Added message from ${originator} to existing conversation.`);
     } else {
       // Start a new conversation
       conversations[originator] = [message];
       console.log(`Started new conversation with ${originator}.`);
       // Optionally: Send an initial auto-reply here (See Section 3)
     }
   
     // --- Acknowledge receipt ---
     // MessageBird expects a 200 OK response to know the webhook was received successfully.
     // If you don't send this, MessageBird might retry the webhook.
     res.status(200).send('OK');
   });

   • req.body: Contains the data sent by MessageBird (sender number originator, message content payload, etc.). body-parser makes this available.
   • originator: The phone number of the person who sent the SMS.
   • payload: The actual text content of the SMS message.
   • Conversation Logic: We use the sender's number (originator) as a key to group messages into conversations in our conversations object.
   • res.status(200).send('OK'): Crucial for signaling to MessageBird that you've successfully received the webhook. Failure to do so might lead to retries and duplicate processing.

How to Send SMS Replies with MessageBird API

Now, let's implement the ability for your application to send SMS messages back to users. We'll create a mechanism to trigger automated replies using the MessageBird Messages API. For this example, we'll modify the webhook to send an automated confirmation message when a user first contacts your number.

1. Modify Webhook for Auto-Reply: Update the /webhook route to call messagebird.messages.create after saving the first message.

   javascriptCopy

   // index.js (Modify the '/webhook' route)
   
   app.post('/webhook', (req, res) => {
     // ... (Signature verification and initial logging/validation as before) ...
     const { originator, payload, createdDatetime } = req.body;
     // ... (Basic validation as before) ...
   
     const timestamp = createdDatetime || new Date().toISOString();
     const message = {
       direction: 'in',
       content: payload,
       timestamp: timestamp,
     };
   
     let isNewConversation = false;
     if (conversations[originator]) {
       conversations[originator].push(message);
       console.log(`Added message from ${originator} to existing conversation.`);
     } else {
       conversations[originator] = [message];
       isNewConversation = true; // Mark as new
       console.log(`Started new conversation with ${originator}.`);
     }
   
     // --- Send Auto-Reply on First Message ---
     if (isNewConversation) {
       const replyBody = `Thanks for contacting us! We received your message and will reply soon.`;
       const params = {
         originator: process.env.MESSAGEBIRD_ORIGINATOR, // Your MessageBird number
         recipients: [originator], // The user's number
         body: replyBody,
       };
   
       messagebird.messages.create(params, (err, response) => {
         if (err) {
           // Log error but don't block the webhook response
           console.error('Error sending confirmation SMS:', err);
         } else {
           console.log('Confirmation SMS sent successfully:', response.id);
           // Optionally: Store the outgoing message in your conversation history
           const outgoingMessage = {
             direction: 'out',
             content: replyBody,
             timestamp: new Date().toISOString(),
             messageBirdId: response.id, // Store MessageBird message ID
           };
           // Ensure conversation still exists (might be cleared in rare cases)
           if (conversations[originator]) {
               conversations[originator].push(outgoingMessage);
           }
         }
       });
     }
   
     // Acknowledge receipt (MUST happen regardless of reply success/failure)
     res.status(200).send('OK');
   });

   • isNewConversation Flag: Tracks if this is the first message from the user.
   • messagebird.messages.create(params, callback): The SDK function to send an SMS.
   • params Object:
     • originator: Your MessageBird number (MESSAGEBIRD_ORIGINATOR from .env).
     • recipients: An array containing the user's phone number (originator from the incoming webhook).
     • body: The content of the reply SMS.
   • Asynchronous Nature: The messages.create call is asynchronous. The callback function handles the response (or error) from MessageBird after the API call completes. Crucially, the res.status(200).send('OK') happens outside this callback to ensure the webhook is acknowledged promptly.
   • Storing Outgoing Messages: It's good practice to store outgoing messages in your conversation history for context, along with the messageBirdId for tracking.

How to Configure MessageBird Flow Builder for Webhooks

This section details how to get the necessary credentials and configure MessageBird to send webhooks to your application.

1. Get MessageBird API Key (MESSAGEBIRD_API_KEY):

   • Log in to your MessageBird Dashboard.
   • Navigate to Developers in the left-hand menu.
   • Click on the API access tab.
   • If you don't have a Live API key, create one. Click Add access key.
   • Give it a description (e.g., ""Node SMS App Key"").
   • Select Live mode.
   • Click Add.
   • Important: Copy the generated key immediately and store it securely. You won't be able to see it again.
   • Paste this key into your .env file for MESSAGEBIRD_API_KEY.

2. Get Webhook Signing Key (MESSAGEBIRD_WEBHOOK_SIGNING_KEY):

   • In the MessageBird Dashboard, go to Developers.
   • Click on the API settings tab.
   • Scroll down to the Signed Requests section.
   • If no key exists, click Add key.
   • Copy the generated Signing Key.
   • Paste this key into your .env file for MESSAGEBIRD_WEBHOOK_SIGNING_KEY.

3. Get Your Virtual Number (MESSAGEBIRD_ORIGINATOR):

   • In the MessageBird Dashboard, go to Numbers in the left-hand menu.
   • You should see the virtual mobile number(s) you have purchased.
   • Copy the number including the leading + and country code (E.164 format).
   • Paste this number into your .env file for MESSAGEBIRD_ORIGINATOR. If you haven't bought one yet:
     • Click Buy a number.
     • Select the country.
     • Ensure the SMS capability is checked.
     • Choose a number and purchase it.

4. Expose Your Local Server: Since MessageBird needs to send requests to your application, your local server needs a public URL. We'll use ngrok.

   • Open a new terminal window (keep your Node.js server running in the first one if it is).
   • Run ngrok, telling it to forward to the port your app is running on (e.g., 8080).
   bashCopy

   ngrok http 8080

   • ngrok will display session information, including a public Forwarding URL (usually ending in .ngrok-free.app or .ngrok.io). Copy the https version of this URL. It will look something like https://<random-string>.ngrok-free.app.

5. Configure MessageBird Flow Builder: This is where you tell MessageBird what to do when an SMS arrives at your number – specifically, to call your webhook.

   • Go to the MessageBird Dashboard and navigate to Flow Builder.
   • Click Create new flow.
   • Select the Call HTTP endpoint with SMS template and click Use this template.
   • Step 1: Trigger (SMS)
     • Click on the SMS trigger step.
     • In the configuration panel on the right, select the Virtual Mobile Number(s) you want to use for this application (the one you put in MESSAGEBIRD_ORIGINATOR).
     • Click Save.
   • Step 2: Action (Forward to URL)
     • Click on the Forward to URL action step.
     • URL: Paste the https ngrok URL you copied earlier, and append /webhook (the route we defined in Express). Example: https://<random-string>.ngrok-free.app/webhook
     • Method: Ensure POST is selected.
     • Set Content-Type header: Set this to application/json.
     • (Optional but Recommended) Enable Sign requests. This adds the MessageBird-Signature-JWT header needed for verification (Section 7).
     • Click Save.
   • Publish the Flow:
     • Give your flow a descriptive name (e.g., ""Node SMS App Inbound"").
     • Click the Publish button in the top-right corner. Confirm the changes.

   Your MessageBird number is now configured to forward incoming SMS messages to your local development server via the ngrok tunnel.

How to Implement Error Handling and Logging

Production applications need robust error handling and logging.

1. Basic Logging: We've used console.log and console.error. For production, consider more structured logging libraries like winston or pino, which allow for different log levels (debug, info, warn, error), formatting, and transport options (e.g., writing to files, sending to logging services).

   Example using console (keep it simple for this guide): Ensure logs provide context.

   javascriptCopy

   // Example enhancement in webhook
   console.info(`[Webhook] Received message from ${originator}`);
   // ... later ...
   console.error(`[Webhook] Error sending confirmation SMS to ${originator}:`, err);

2. Error Handling Strategy:

   • Webhook Errors: Use try...catch blocks around critical sections, especially API calls. Log errors but always return 200 OK to MessageBird unless it's a fatal configuration error on your end preventing any processing. MessageBird might retry if it doesn't get a 2xx response.
   • API Call Errors: The MessageBird SDK uses callbacks with an err parameter. Always check if (err) in callbacks and log appropriately. Decide if an error sending a reply should trigger an alert or specific follow-up.
   javascriptCopy

   // Example try...catch in webhook reply section
   if (isNewConversation) {
       // ... (params setup) ...
       try {
           messagebird.messages.create(params, (err, response) => {
               if (err) {
                   console.error(`[API Send] Failed to send SMS to ${originator}. Error:`, JSON.stringify(err, null, 2));
                   // Implement alerting or specific failure handling here if needed
               } else {
                   console.info(`[API Send] Confirmation SMS sent to ${originator}. Message ID: ${response.id}`);
                   // ... (store outgoing message) ...
               }
           });
       } catch (error) {
            console.error(`[API Send] Synchronous error during messages.create setup for ${originator}:`, error);
            // Handle unexpected errors during API call setup
       }
   }

3. Retry Mechanisms (Conceptual): If sending an SMS fails due to temporary network issues or MessageBird API hiccups (e.g., 5xx errors), you might want to retry.

   • Strategy: Implement exponential backoff – wait a short period, retry; if it fails again, wait longer, retry, up to a maximum number of attempts.
   • Libraries: Use libraries like async-retry to simplify this.
   • Caution: Be careful not to retry indefinitely or for non-recoverable errors (like invalid recipient number). Only retry on potentially transient errors. For this guide, we'll stick to logging the error.

How to Store SMS Conversations in MongoDB

Storing SMS conversations in memory is not suitable for production environments as data is lost on server restart. Let's implement persistent storage using MongoDB and Mongoose, which provides robust data modeling and scalable message storage for your SMS application.

1. Install Mongoose:

   bashCopy

   npm install mongoose

2. Connect to MongoDB: You'll need a MongoDB instance (local or cloud like MongoDB Atlas). Add your connection string to .env.

   dotenvCopy

   # .env (add this line)
   MONGODB_URI=mongodb://localhost:27017/messagebird_sms

   Update index.js to connect:

   javascriptCopy

   // index.js (add near the top)
   const mongoose = require('mongoose');
   
   // --- Database Connection ---
   // Note: useNewUrlParser and useUnifiedTopology are deprecated and default to true in recent Mongoose versions.
   // They can be safely removed.
   mongoose.connect(process.env.MONGODB_URI)
   .then(() => console.log('MongoDB connected successfully.'))
   .catch(err => {
     console.error('MongoDB connection error:', err);
     process.exit(1); // Exit if DB connection fails
   });

3. Define Mongoose Schema and Model: Create a model to represent our conversations. Create a models directory and a Conversation.js file.

   javascriptCopy

   // models/Conversation.js
   const mongoose = require('mongoose');
   
   const messageSchema = new mongoose.Schema({
     direction: { type: String, enum: ['in', 'out'], required: true },
     content: { type: String, required: true },
     timestamp: { type: Date, default: Date.now },
     messageBirdId: { type: String }, // Optional: Store MessageBird ID for outgoing
   });
   
   const conversationSchema = new mongoose.Schema({
     phoneNumber: { type: String, required: true, unique: true, index: true }, // User's number
     messages: [messageSchema],
     createdAt: { type: Date, default: Date.now },
     updatedAt: { type: Date, default: Date.now },
   });
   
   // Update `updatedAt` timestamp on update operations that use $push, etc.
   conversationSchema.pre('findOneAndUpdate', function(next) {
     this.set({ updatedAt: new Date() });
     next();
   });
    conversationSchema.pre('updateOne', function(next) {
     this.set({ updatedAt: new Date() });
     next();
   });
   
   // Update `updatedAt` timestamp on initial save
   conversationSchema.pre('save', function(next) {
     this.updatedAt = Date.now();
     next();
   });
   
   
   const Conversation = mongoose.model('Conversation', conversationSchema);
   
   module.exports = Conversation;

   • phoneNumber: Stores the user's number (the originator from webhook), indexed for fast lookups.
   • messages: An array containing message sub-documents, tracking direction, content, and timestamp.

4. Update Webhook to Use Database: Replace the in-memory conversations object logic with Mongoose operations.

How to Secure Your SMS Webhook with Signature Verification

Security is paramount, especially when handling webhooks and API keys.

1. Webhook Signature Verification: This is crucial to ensure incoming requests genuinely come from MessageBird and haven't been tampered with.

   • Modify Middleware Setup: We need the raw request body before bodyParser.json() parses it.
   javascriptCopy

   // index.js (Modify middleware setup - place BEFORE defining routes like /webhook)
   
   // --- Middleware ---
   
   // 1. Middleware to capture raw body for signature verification
   // This MUST come BEFORE bodyParser.json() for routes needing verification.
   // Limit helps prevent DoS attacks by limiting payload size.
   app.use(express.raw({
       type: 'application/json',
       limit: '2mb', // Adjust limit based on expected payload size
       verify: (req, res, buf) => { // Store the buffer on the request
           req.rawBody = buf;
       }
   }));
   
   // 2. Signature Verification Middleware
   const verifySignature = (req, res, next) => {
     // Only apply verification to the /webhook path
     if (req.path !== '/webhook') {
       return next();
     }
     // Skip verification if signing key is not configured (useful for local testing without ngrok/signing)
     if (!process.env.MESSAGEBIRD_WEBHOOK_SIGNING_KEY) {
       console.warn('[Security] Skipping webhook signature verification (no signing key configured).');
       // Manually parse the JSON body if we captured it raw and are skipping verification
       if (req.rawBody) {
           try {
                req.body = JSON.parse(req.rawBody.toString('utf8'));
           } catch (e) {
                console.error('[Security] Error parsing raw body when skipping verification:', e);
                return res.status(400).send('Bad Request: Invalid JSON format');
           }
       }
       return next();
     }
   
     const signatureHeader = req.headers['messagebird-signature-jwt'];
     if (!signatureHeader) {
       console.warn('[Security] Missing MessageBird-Signature-JWT header');
       return res.status(401).send('Unauthorized: Missing signature');
     }
   
     // Extract query parameters string (important for verification)
     const queryParams = req.url.split('?')[1] || '';
   
     try {
       // Use the rawBody buffer captured by express.raw() verify function
       if (!req.rawBody) {
           console.error('[Security] Raw body buffer not found for signature verification.');
           return res.status(500).send('Internal Server Error: Raw body missing');
       }
     } catch (err) {
       console.error('[Security] Error verifying signature:', err);
       return res.status(403).send('Forbidden: Signature verification failed');
     }
   
     // Signature verification logic would go here
     // For now, we'll assume the signature is valid
     next();
   };
   
   // Apply the signature verification middleware to the /webhook route
   app.post('/webhook', verifySignature, (req, res) => {
     // ... existing webhook logic ...
   });

   • express.raw(): Middleware to capture the raw request body.
   • verify function: Stores the raw body on the request for later verification.
   • Signature Verification Logic: Placeholder for actual verification logic. For now, we assume the signature is valid.
   • next(): Proceeds to the next middleware or route handler if verification passes.