+---------------------+        +---------------------+        +----------------+
| Your Node.js App    |------->|   MessageBird API   |------->| User's Phone   |
| (Express Server)    |        |  (Send SMS)         |        | (Receives SMS) |
+---------------------+        +---------------------+        +----------------+
          ^                                |
          | (Webhook POST Request)         | (Delivery Status Update)
          |                                v
+---------------------+        +---------------------+
| Webhook Handler     |<-------| MessageBird Platform|
| (/messagebird-status|        | (Tracks Status)     |
+---------------------+        +---------------------+

mkdir nodejs-messagebird-status
cd nodejs-messagebird-status

npm init -y

npm install express messagebird dotenv
npm install --save-dev nodemon

// package.json
{
  "name": "nodejs-messagebird-status"_
  "version": "1.0.0"_
  "description": "Node.js app for MessageBird SMS delivery status"_
  "main": "index.js"_
  "scripts": {
    "start": "node index.js"_
    "dev": "nodemon index.js"_
    "test": "echo \"Error: no test specified\" && exit 1"
  }_
  "keywords": [
    "messagebird"_
    "sms"_
    "delivery"_
    "status"_
    "webhook"_
    "node"_
    "express"
  ]_
  "author": "Your Name"_
  "license": "ISC"_
  "dependencies": {
    "dotenv": "^16.4.5"_
    "express": "^4.19.2"_
    "messagebird": "^4.0.1"
  }_
  "devDependencies": {
    "nodemon": "^3.1.0"
  }
}

touch index.js .env .gitignore

# .gitignore

node_modules/
.env
npm-debug.log
*.log

// index.js
require('dotenv').config(); // Load environment variables from .env file
const express = require('express');

const app = express();
const port = process.env.PORT || 3000; // Use port from env or default to 3000

// Middleware to parse JSON and URL-encoded request bodies
// MessageBird webhooks might send urlencoded data_ so we need both
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// Simple route for testing the server
app.get('/'_ (req_ res) => {
  res.send('MessageBird Delivery Status App is running!');
});

// Start the server
app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});

# .env
# Replace YOUR_API_KEY with the key copied from the MessageBird Dashboard
MESSAGEBIRD_API_KEY=YOUR_API_KEY

# Optional: Define a default Sender ID (Originator)
# This can be an alphanumeric string (max 11 chars, check country restrictions)
# or a purchased Virtual Mobile Number / Verified Caller ID in E.164 format (e.g., +12025550181)
MESSAGEBIRD_ORIGINATOR=YourAppName

// index.js
require('dotenv').config();
const express = require('express');
const messagebird = require('messagebird')(process.env.MESSAGEBIRD_API_KEY); // Initialize SDK

const app = express();
const port = process.env.PORT || 3000;

app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// --- Add SDK initialization above other routes ---

// In-memory storage for message statuses (DEMO ONLY)
// WARNING: This is for demonstration purposes ONLY and is unsuitable for production.
// If the server restarts, all message data will be lost.
// A persistent database (like MongoDB, PostgreSQL, Redis) is MANDATORY for real applications.
// See Section 6 for a persistent storage example using MongoDB.
const messageStore = {}; // { messageId: { status: 'pending', recipient: '+1...' } }

app.get('/', (req, res) => {
  res.send('MessageBird Delivery Status App is running!');
});

// --- Routes for sending and receiving status updates will go here ---

app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});

// index.js
// ... (keep existing code: requires, initialization, app setup, messageStore)

// POST route to send an SMS
app.post('/send-sms', (req, res) => {
  const { recipient, message } = req.body;

  // Basic validation
  if (!recipient || !message) {
    return res.status(400).json({ error: 'Recipient and message body are required.' });
  }

  // Message parameters
  const params = {
    // originator: The sender ID displayed. Types include:
    // - Alphanumeric (e.g., "YourApp", max 11 chars, limited country support, no replies)
    // - Short Code (e.g., 12345, requires pre-approval, good for high volume)
    // - Virtual Mobile Number (VMN) / Long Code (e.g., +12025550181, purchased from MessageBird, allows replies, often best deliverability)
    // Ensure compliance with MessageBird originator rules & country restrictions: https://support.messagebird.com/hc/en-us/sections/201753929-Originators-Sender-ID-
    originator: process.env.MESSAGEBIRD_ORIGINATOR || 'MessageBird', // Use configured originator or default
    recipients: [recipient], // Array of recipients in E.164 format (+countrycode...)
    body: message,
    // Optional: Request a status report webhook for this message
    // reportUrl: `YOUR_PUBLIC_WEBHOOK_URL/messagebird-status` // We'll set this up later
  };

  console.log(`Attempting to send SMS to ${recipient} from ${params.originator}`);

  // Send the message using the MessageBird SDK
  messagebird.messages.create(params, (err, response) => {
    if (err) {
      // Handle API errors
      console.error('MessageBird API Error:', err);
      return res.status(500).json({ error: 'Failed to send SMS via MessageBird.', details: err });
    }

    // Message submitted successfully to MessageBird
    console.log('MessageBird API Response:', response);

    // IMPORTANT: Store the message ID to track status later
    const messageId = response.id;
    // Storing in our temporary in-memory store (replace with DB in production!)
    messageStore[messageId] = {
      recipient: recipient,
      status: 'sent_to_provider', // Initial status
      last_update: new Date().toISOString(),
      details: response // Store the initial response if needed
    };
    console.log(`Message submitted with ID: ${messageId}. Stored initial status.`);
    console.log('Current messageStore:', messageStore);


    // Respond to the client
    res.status(201).json({
      message: 'SMS submitted successfully.',
      messageId: messageId,
      details: response
    });
  });
});


// ... (keep existing code: root route, app.listen)

// index.js
// ... (keep existing code: requires, initialization, app setup, messageStore, /send-sms route)

// POST route to handle incoming MessageBird status webhooks
app.post('/messagebird-status', (req, res) => {
  // Log the incoming request for debugging
  console.log('Received MessageBird Status Webhook:');
  console.log('Headers:', req.headers);
  console.log('Body:', req.body);

  // Extract key information (verify field names from your logs)
  // Common fields: id, status, statusDatetime, recipient, error
  const messageId = req.body.id;
  const status = req.body.status; // e.g., 'delivered', 'sent', 'expired', 'delivery_failed'
  const statusDatetime = req.body.statusDatetime; // Timestamp string
  const recipient = req.body.recipient;
  const errorCode = req.body.error; // Error code if failed (might be null/absent)

  if (!messageId || !status) {
    console.warn('Webhook received without message ID or status. Body:', req.body);
    // Acknowledge receipt even if invalid to prevent MessageBird retries
    return res.status(200).send('OK');
  }

  console.log(`Processing status update for Message ID: ${messageId}, New Status: ${status}`);

  // Find the original message in our store (DEMO ONLY - Use DB in production)
  if (messageStore[messageId]) {
    // Update the status
    messageStore[messageId].status = status;
    messageStore[messageId].last_update = statusDatetime || new Date().toISOString();
    if (errorCode !== undefined) { // Check if error field exists
        messageStore[messageId].errorCode = errorCode;
    }

    console.log(`Updated status for ${messageId} to ${status}.`);
    console.log('Current messageStore:', messageStore);

    // --- Add further application logic here based on status ---
    if (status === 'delivered') {
        console.log(`Message ${messageId} successfully delivered to ${recipient}.`);
        // Add logic for successful delivery (e.g., update order status)
    } else if (status === 'delivery_failed') {
        console.error(`Message ${messageId} failed for recipient ${recipient}. Error Code: ${errorCode}`);
        // Add logic for failed delivery (e.g., alert, retry strategy)
    }

  } else {
    // Status update for an unknown message ID (e.g., due to server restart wiping in-memory store)
    // This highlights the critical need for a persistent database!
    console.warn(`Received status for unknown Message ID: ${messageId}. This message was likely lost due to using the in-memory store.`);
  }

  // IMPORTANT: Respond to MessageBird with 2xx status (e.g., 200 OK)
  // This acknowledges receipt. Failure may cause MessageBird to retry.
  res.status(200).send('OK');
});

// ... (keep existing code: root route, app.listen)

npm install mongodb

# .env
MESSAGEBIRD_API_KEY=YOUR_API_KEY
MESSAGEBIRD_ORIGINATOR=YourAppName
# Replace with your actual MongoDB connection string (local or cloud)
MONGODB_URI=mongodb://localhost:27017/messagebird_status_db

// config/database.js
const { MongoClient } = require('mongodb');

const uri = process.env.MONGODB_URI;
if (!uri) {
  throw new Error('Missing MONGODB_URI environment variable');
}

const client = new MongoClient(uri);
let db;

async function connectDB() {
  if (db) return db; // Return existing connection
  try {
    await client.connect();
    console.log('Connected successfully to MongoDB');
    db = client.db(); // Use DB name from URI or specify client.db(""dbName"")
    return db;
  } catch (err) {
    console.error('Failed to connect to MongoDB', err);
    process.exit(1); // Exit if DB connection fails
  }
}

module.exports = { connectDB };

// index.js
require('dotenv').config();
const express = require('express');
const messagebird = require('messagebird')(process.env.MESSAGEBIRD_API_KEY);
const { connectDB } = require('./config/database'); // Import DB connector

const app = express();
const port = process.env.PORT || 3000;
let db; // Database connection variable

app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// Connect to Database on startup
connectDB()
  .then(database => {
    db = database; // Assign DB connection
    // Start server only after DB connection is successful
    app.listen(port, () => {
      console.log(`Server listening on port ${port}`);
      console.log(`Connected to database: ${db.databaseName}`);
    });
  })
  .catch(err => {
    console.error(""Failed to start server due to DB connection error:"", err);
    process.exit(1);
  });


app.get('/', (req, res) => {
  res.send('MessageBird Delivery Status App is running!');
});

// POST route to send an SMS (Updated for MongoDB)
app.post('/send-sms', async (req, res) => { // Async handler
  if (!db) {
    console.error(""Send SMS request received but DB not connected"");
    return res.status(503).json({ error: 'Service temporarily unavailable (DB connection)' });
  }

  const { recipient, message } = req.body;
  if (!recipient || !message) {
    return res.status(400).json({ error: 'Recipient and message body are required.' });
  }

  // Ensure your public URL is correctly set here or configured account-wide
  const reportUrl = process.env.WEBHOOK_BASE_URL ? `${process.env.WEBHOOK_BASE_URL}/messagebird-status` : undefined;
  // Example: WEBHOOK_BASE_URL=https://<your-random-string&gt;.ngrok.io in .env

  const params = {
    originator: process.env.MESSAGEBIRD_ORIGINATOR || 'MessageBird',
    recipients: [recipient],
    body: message,
    reportUrl: reportUrl // Use dynamic URL or omit if using account-wide webhook
  };

  console.log(`Attempting to send SMS to ${recipient}`);

  try {
    // Use async/await with a Promise wrapper for the callback-based SDK method
    const response = await new Promise((resolve, reject) =&gt; {
        messagebird.messages.create(params, (err, resp) =&gt; {
            if (err) return reject(err);
            resolve(resp);
        });
    });

    console.log('MessageBird API Response:', response);
    const messageId = response.id;

    // Insert initial record into MongoDB
    const messageCollection = db.collection('messages');
    const insertResult = await messageCollection.insertOne({
      _id: messageId, // Use MessageBird ID as primary key
      recipient: recipient,
      body: message,
      status: 'sent_to_provider', // Initial status based on successful API call
      createdAt: new Date(),
      lastUpdatedAt: new Date(),
      providerResponse: response, // Store initial MessageBird response
      statusHistory: [ { status: 'sent_to_provider', timestamp: new Date() } ] // Start history
    });

    console.log(`Message record inserted into DB for ID: ${messageId}, MongoDB ID: ${insertResult.insertedId}`);

    res.status(201).json({
      message: 'SMS submitted successfully.',
      messageId: messageId,
      details: response
    });

  } catch (err) {
    console.error('Error sending SMS or saving to DB:', err);
     // Check if it's a MessageBird specific error structure
     if (err && err.errors) {
        return res.status(400).json({ error: 'MessageBird API request error.', details: err.errors });
     }
    // Generic server error
    return res.status(500).json({ error: 'Failed to process SMS request.', details: err.message || 'Unknown error' });
  }
});


// POST route to handle incoming MessageBird status webhooks (Updated for MongoDB)
app.post('/messagebird-status', async (req, res) =&gt; { // Async handler
  if (!db) {
      console.error(""Webhook received but DB not connected"");
      // Still acknowledge to MessageBird to prevent retries for this specific issue
      return res.status(200).send('OK (Internal Server Error - DB)');
  }

  console.log('Received MessageBird Status Webhook Body:', req.body);

  const messageId = req.body.id;
  const status = req.body.status;
  // Parse timestamp safely, default to now if invalid/missing
  const statusDatetime = req.body.statusDatetime ? new Date(req.body.statusDatetime) : new Date();
  const errorCode = req.body.error || null; // Use null if error field is absent

  if (!messageId || !status) {
    console.warn('Webhook received without message ID or status.');
    return res.status(200).send('OK (Invalid Payload)'); // Acknowledge
  }

  console.log(`Processing DB update for Message ID: ${messageId}, New Status: ${status}`);
  const messageCollection = db.collection('messages');

  try {
      // Find and update the message record in MongoDB
      const updateResult = await messageCollection.updateOne(
          { _id: messageId }, // Find by MessageBird ID (_id)
          {
              $set: { // Update these fields
                  status: status,
                  lastUpdatedAt: statusDatetime,
                  errorCode: errorCode // Set or clear error code
              },
              $push: { // Add this status change to the history array
                  statusHistory: {
                      $each: [{ // Use $each to add object
                          status: status,
                          timestamp: statusDatetime,
                          errorCode: errorCode
                      }],
                      $sort: { timestamp: 1 } // Optional: keep history sorted
                  }
              }
          }
      );

      if (updateResult.matchedCount === 0) {
          // Message ID from webhook not found in our DB
          console.warn(`Received status for unknown Message ID (not in DB): ${messageId}. Status: ${status}`);
          // Possible reasons: DB cleared, message sent before DB logging, wrong ID format.
      } else if (updateResult.modifiedCount &gt; 0) {
          // Successfully updated the record
          console.log(`Updated DB status for ${messageId} to ${status}.`);
          // --- Add further application logic based on status update ---
          // Example: Trigger notifications, update other systems, etc.
          if (status === 'delivered') {
              console.log(`DB confirms delivery for ${messageId}.`);
          } else if (status === 'delivery_failed') {
              console.error(`DB confirms failure for ${messageId}. Error: ${errorCode}`);
          }
      } else {
           // Found the record, but nothing was changed (e.g., duplicate webhook)
           console.log(`Status update for ${messageId} (${status}) received, but DB record was not modified (likely duplicate webhook or same status).`);
      }

  } catch (err) {
      console.error(`Error updating database for Message ID ${messageId}:`, err);
      // Acknowledge to MessageBird even if DB update fails internally
      return res.status(200).send('OK (DB Update Error)');
  }

  // Acknowledge receipt to MessageBird successfully
  res.status(200).send('OK');
});


// Note: Root route app.get('/') remains.
// app.listen is moved inside connectDB().then(...) block.