Implementing Inbound Two-Way SMS Messaging with MessageBird, Node.js, and Fastify

Introduction

Building a two-way SMS system? This comprehensive guide walks you through implementing inbound SMS messaging using MessageBird (now Bird), Node.js, and the Fastify web framework. You'll learn how to receive SMS messages via webhooks, verify their authenticity, and send automated replies—all essential for building interactive SMS applications like customer support bots, survey systems, or appointment reminders.

What you'll build: A production-ready Fastify server that receives inbound SMS messages through MessageBird webhooks, validates message authenticity using JWT signature verification, and sends automated responses. By the end of this tutorial, you'll have a complete two-way SMS messaging system ready for real-world deployment.

Note: MessageBird rebranded to Bird in early 2024. The SMS API and Node.js SDK functionality remain unchanged, though you may see both names in documentation and interfaces.

Prerequisites

Before you begin this tutorial, ensure you have:

• Node.js v20 LTS or v22 LTS installed on your development machine. (These are the current LTS versions as of October 2025. While older versions like v16 may work, using current LTS versions ensures the best security updates and performance.)
• MessageBird Account: Sign up at messagebird.com to obtain your API credentials.
• API Key: Generate a live API key from your MessageBird dashboard (found under Developers → API Access).
• Virtual Mobile Number: Purchase a phone number with SMS capabilities from MessageBird to receive inbound messages.
• Basic Knowledge: Familiarity with JavaScript, async/await patterns, and REST API concepts.
• Development Tools: A code editor (VS Code, Sublime Text, etc.) and terminal access.

What Is Two-Way SMS Messaging and Why Use It?

Two-way SMS messaging enables bidirectional communication between your application and mobile users. Unlike one-way SMS broadcasts, two-way messaging allows customers to respond to your messages, creating interactive conversations that drive engagement and automate customer service workflows.

Common use cases for two-way SMS:

• Customer support automation — Answer frequently asked questions instantly without human intervention
• Appointment confirmations — Allow customers to confirm, reschedule, or cancel appointments via SMS
• Survey and feedback collection — Gather customer opinions through conversational SMS interactions
• Order status updates — Enable customers to check order status by texting keywords to your number
• Opt-in and consent management — Handle subscription preferences and marketing consent requests
• Interactive marketing campaigns — Run contests, polls, and engagement campaigns through SMS

Why choose Fastify for SMS webhooks?

Fastify excels at webhook handling due to its high performance (up to 30,000 requests per second), low overhead, and built-in features like schema validation, logging, and plugin architecture. For production SMS systems handling thousands of inbound messages, Fastify's speed and developer experience make it an ideal choice.

Understanding Two-Way SMS Architecture

Two-way SMS messaging involves both sending and receiving messages. Here's how the system works:

1. Customer sends SMS to your MessageBird virtual number
2. MessageBird receives the message and triggers a webhook to your server
3. Your Fastify server receives the webhook, verifies its authenticity, and processes the message
4. Your application sends an automated response back through MessageBird's API
5. Customer receives your reply on their mobile device

This bidirectional flow enables interactive conversations, automated customer service, opt-in confirmations, and more.

How to Set Up Your MessageBird Fastify Project

Create a new directory for your project and initialize a Node.js application:

mkdir messagebird-fastify-inbound-sms
cd messagebird-fastify-inbound-sms
npm init -y

Install the required dependencies:

npm install fastify messagebird dotenv pino-pretty qs async-retry @fastify/rate-limit

Package purposes:

• fastify — Fast and low-overhead web framework for Node.js (Note: This tutorial uses Fastify v5.x. If you're using an older version, some APIs may differ.)
• messagebird — Official MessageBird Node.js SDK for sending SMS and accessing the API
• dotenv — Loads environment variables from .env file for secure credential management
• pino-pretty — Pretty-prints Fastify's JSON logs for easier development debugging
• qs — Parses URL-encoded webhook payloads from MessageBird
• async-retry — Implements retry logic for failed API calls
• @fastify/rate-limit — Protects your webhook endpoint from abuse

How to Configure Environment Variables for MessageBird

Create a .env file in your project root to store sensitive credentials securely:

# .env
MESSAGEBIRD_API_KEY=your_live_api_key_here
MESSAGEBIRD_WEBHOOK_SIGNING_KEY=your_webhook_signing_key_here
MESSAGEBIRD_ORIGINATOR=+1234567890
PORT=3000
NODE_ENV=development

Configuration details:

• MESSAGEBIRD_API_KEY — Your live API key from MessageBird dashboard
• MESSAGEBIRD_WEBHOOK_SIGNING_KEY — Signing key for webhook signature verification (found in webhook settings)
• MESSAGEBIRD_ORIGINATOR — Your MessageBird virtual number in E.164 format (e.g., +14155552671)
• PORT — Port number for your Fastify server (default: 3000)
• NODE_ENV — Environment indicator (development or production)

Security note: Add .env to your .gitignore file to prevent accidentally committing sensitive credentials to version control.

How to Create a Fastify Server for SMS Webhooks

Create a file named server.js and set up your basic Fastify server:

// server.js
'use strict';

require('dotenv').config();
const fastify = require('fastify');
const messagebird = require('messagebird');
const qs = require('qs');
const retry = require('async-retry');

// Initialize Fastify with logging
const app = fastify({
  logger: {
    transport: {
      target: 'pino-pretty',
      options: {
        translateTime: 'HH:MM:ss Z',
        ignore: 'pid,hostname',
        colorize: true
      }
    }
  },
  // Enable raw body for signature verification
  disableRequestLogging: false,
  bodyLimit: 1048576 // 1MB limit
});

// Initialize MessageBird client
const mbClient = messagebird.initClient(process.env.MESSAGEBIRD_API_KEY);

// ... webhook handlers will go here ...

// Start the server
const start = async () => {
  try {
    const port = process.env.PORT || 3000;
    await app.listen({ port, host: '0.0.0.0' });
    app.log.info(`Server listening on port ${port}`);
  } catch (err) {
    app.log.error(err);
    process.exit(1);
  }
};

start();

Code explanation:

• You initialize Fastify with pretty logging for development
• You create a MessageBird client using messagebird.initClient() with your API key
• You configure the server to listen on all network interfaces (0.0.0.0) for webhook access
• You implement graceful error handling in the startup function

How to Verify MessageBird Webhook Signatures with JWT

Verify incoming webhooks to ensure they originate from MessageBird. Add this verification function to your server.js:

/**
 * Verifies MessageBird webhook JWT signature
 * @param {FastifyRequest} request - The Fastify request object
 * @param {FastifyReply} reply - The Fastify reply object
 */
async function verifyMessageBirdSignature (request, reply) {
  const signatureJWT = request.headers['messagebird-signature-jwt'];
  const webhookSigningKey = process.env.MESSAGEBIRD_WEBHOOK_SIGNING_KEY;
  const rawBody = request.rawBodyString;

  if (!signatureJWT || !webhookSigningKey || typeof rawBody !== 'string') {
    request.log.warn({
        signatureJWT: !!signatureJWT,
        key: !!webhookSigningKey,
        rawBodyType: typeof rawBody
    }, 'Missing JWT signature header, signing key, or raw body.');
    reply.code(400).send({ error: 'Missing MessageBird signature JWT, key, or raw body' });
    return;
  }

  try {
    const isValid = messagebird.webhookSignatureJwt.verifySignature(
      signatureJWT,
      webhookSigningKey,
      request.raw.url,
      rawBody
    );

    if (!isValid) {
      request.log.error('Invalid webhook JWT signature received.');
      reply.code(401).send({ error: 'Invalid MessageBird signature' });
      return;
    }

    request.log.info('Webhook JWT signature verified successfully.');
  } catch (error) {
    request.log.error({ err: error }, 'Error during JWT signature verification.');
    reply.code(500).send({ error: 'Webhook signature verification failed internally' });
  }
}

Note: As of October 2025, MessageBird uses the MessageBird-Signature-JWT header for webhook authentication. This replaces older HMAC-based verification methods. Always use the SDK's built-in verification for security.

Security considerations:

• You validate the JWT signature using MessageBird's SDK verification method
• You reject requests with missing or invalid signatures to prevent spoofed webhooks
• You log all verification attempts for security auditing
• You use the raw request body (not parsed) for signature verification

How to Create a Webhook Endpoint for Inbound SMS

Add a custom content type parser for raw body access, then create your webhook endpoint:

// Add raw body parser before webhook route
app.addContentTypeParser('application/x-www-form-urlencoded', { parseAs: 'string' }, function (req, body, done) {
  req.rawBodyString = body;
  try {
    const parsed = qs.parse(body);
    done(null, parsed);
  } catch (err) {
    err.statusCode = 400;
    done(err, undefined);
  }
});

// Webhook endpoint for inbound SMS
app.post('/webhooks/inbound-sms', {
  preHandler: verifyMessageBirdSignature
}, async (request, reply) => {
  try {
    const payload = request.body;
    
    request.log.info({ payload }, 'Received inbound SMS webhook');

    // Extract message details
    const {
      id: messageId,
      originator: senderNumber,
      recipient: yourNumber,
      body: messageText,
      createdDatetime
    } = payload;

    // Validate required fields
    if (!senderNumber || !messageText) {
      request.log.error({ payload }, 'Webhook payload missing required fields');
      return reply.code(400).send({ error: 'Invalid payload' });
    }

    request.log.info({
      messageId,
      from: senderNumber,
      to: yourNumber,
      text: messageText,
      timestamp: createdDatetime
    }, 'Processing inbound message');

    // Process the message (send auto-reply)
    await sendAutoReply(senderNumber, messageText, request.log);

    // Acknowledge receipt to MessageBird
    reply.code(200).send({ status: 'received' });

  } catch (error) {
    request.log.error({ err: error }, 'Error processing webhook');
    reply.code(500).send({ error: 'Internal server error' });
  }
});

Webhook handling flow:

1. You parse the URL-encoded webhook payload from MessageBird
2. You extract essential message details (sender, recipient, content, timestamp)
3. You validate that required fields are present
4. You process the message and send an automated response
5. You return a 200 OK status to acknowledge successful receipt

How to Send Automated SMS Replies with MessageBird

Add a function to send automated SMS responses with retry logic:

/**
 * Sends an automated SMS reply
 * @param {string} recipient - Phone number to send reply to (E.164 format)
 * @param {string} originalMessage - Original message text received
 * @param {Object} logger - Pino logger instance
 */
async function sendAutoReply(recipient, originalMessage, logger) {
  // Generate dynamic reply based on message content
  const replyText = generateReplyMessage(originalMessage);

  const params = {
    originator: process.env.MESSAGEBIRD_ORIGINATOR,
    recipients: [recipient],
    body: replyText
  };

  try {
    // Use retry logic for resilient API calls
    const response = await retry(
      async (bail) => {
        return new Promise((resolve, reject) => {
          mbClient.messages.create(params, (err, response) => {
            if (err) {
              // Don't retry client errors (4xx)
              if (err.statusCode && err.statusCode < 500) {
                logger.error({ err_ recipient }_ 'Client error sending SMS - not retrying');
                bail(err);
                return;
              }
              reject(err);
            } else {
              resolve(response);
            }
          });
        });
      }_
      {
        retries: 3_
        minTimeout: 1000_
        maxTimeout: 5000_
        onRetry: (err_ attempt) => {
          logger.warn({ err, attempt, recipient }, 'Retrying SMS send');
        }
      }
    );

    logger.info({
      messageId: response.id,
      recipient,
      status: response.recipients.items[0].status
    }, 'Auto-reply sent successfully');

  } catch (error) {
    logger.error({ err: error, recipient }, 'Failed to send auto-reply after retries');
    throw error;
  }
}

/**
 * Generates contextual reply message
 * @param {string} incomingMessage - Original message from customer
 * @returns {string} Reply message text
 */
function generateReplyMessage(incomingMessage) {
  const message = incomingMessage.toLowerCase().trim();

  // Simple keyword-based responses
  if (message.includes('help') || message.includes('support')) {
    return 'Thanks for reaching out! Our support team will respond within 24 hours. For urgent issues, call 1-800-555-0123.';
  }

  if (message.includes('hours') || message.includes('open')) {
    return 'We\'re open Monday-Friday 9 AM-6 PM EST. Visit our website for more information: example.com/hours';
  }

  if (message.includes('price') || message.includes('cost')) {
    return 'For pricing information, visit example.com/pricing or reply with your email address for a detailed quote.';
  }

  // Default response
  return `Thanks for your message: "${incomingMessage}". We'll get back to you shortly!`;
}

Implementation highlights:

• You use retry logic with exponential backoff for API reliability
• You distinguish between client errors (don't retry) and server errors (retry up to 3 times)
• You generate contextual responses based on message keywords
• You log all send attempts for debugging and monitoring
• You handle failures gracefully with detailed error logging

How to Add Rate Limiting to Your SMS Webhook

Protect your webhook endpoint from abuse by adding rate limiting:

// Register rate limiting plugin (add near top of file, after Fastify initialization)
app.register(require('@fastify/rate-limit'), {
  max: 100, // Maximum requests per timeWindow
  timeWindow: '1 minute',
  cache: 10000,
  allowList: [], // Add trusted IPs here
  redis: null, // Use Redis for distributed rate limiting in production
  skipOnError: true,
  keyGenerator: (request) => {
    // Rate limit by IP address
    return request.ip;
  },
  errorResponseBuilder: (request, context) => {
    return {
      code: 429,
      error: 'Too Many Requests',
      message: `Rate limit exceeded, retry in ${context.after}`,
      expiresIn: context.after
    };
  }
});

Rate limiting configuration:

• You allow 100 requests per minute per IP address
• You cache rate limit data for 10,000 unique IPs
• You can whitelist MessageBird's webhook IPs for production
• You return clear error messages when limits are exceeded
• You can scale to distributed systems using Redis in production

How to Configure MessageBird Webhook Settings

Connect your Fastify server to MessageBird:

1. Deploy your server to a publicly accessible URL (use ngrok for local testing)
2. Navigate to MessageBird dashboard → Settings → Webhooks
3. Create new webhook with these settings:
   • Webhook URL: https://your-domain.com/webhooks/inbound-sms
   • Webhook Trigger: "Incoming SMS"
   • Signing Key: Copy this key to your .env file as MESSAGEBIRD_WEBHOOK_SIGNING_KEY
4. Test webhook using MessageBird's test feature
5. Activate webhook after successful testing

Local development with ngrok:

# Install ngrok
npm install -g ngrok

# Start your Fastify server
node server.js

# In another terminal, expose your local server
ngrok http 3000

# Use the ngrok HTTPS URL (e.g., https://abc123.ngrok.io) in MessageBird webhook settings

How to Test Your Two-Way SMS Implementation

Test your two-way SMS system:

1. Start your server:

   bash

   node server.js
   

2. Send a test SMS to your MessageBird virtual number from your mobile phone

3. Monitor server logs to verify:

   • Webhook received and signature verified
   • Message details extracted correctly
   • Auto-reply sent successfully

4. Check your phone for the automated response

Expected log output:

{
  "level": 30,
  "time": "14:23:45 EST",
  "msg": "Webhook JWT signature verified successfully."
}
{
  "level": 30,
  "time": "14:23:45 EST",
  "messageId": "abc123def456",
  "from": "+15551234567",
  "to": "+14155552671",
  "text": "help",
  "msg": "Processing inbound message"
}
{
  "level": 30,
  "time": "14:23:46 EST",
  "messageId": "xyz789ghi012",
  "recipient": "+15551234567",
  "status": "sent",
  "msg": "Auto-reply sent successfully"
}

Complete Code Example

Here's the full implementation with all components:

// server.js - Complete implementation
'use strict';

require('dotenv').config();
const fastify = require('fastify');
const messagebird = require('messagebird');
const qs = require('qs');
const retry = require('async-retry');

// Initialize Fastify with logging
const app = fastify({
  logger: {
    transport: {
      target: 'pino-pretty',
      options: {
        translateTime: 'HH:MM:ss Z',
        ignore: 'pid,hostname',
        colorize: true
      }
    }
  },
  disableRequestLogging: false,
  bodyLimit: 1048576
});

// Initialize MessageBird client
const mbClient = messagebird.initClient(process.env.MESSAGEBIRD_API_KEY);

// Register rate limiting
app.register(require('@fastify/rate-limit'), {
  max: 100,
  timeWindow: '1 minute',
  cache: 10000,
  skipOnError: true,
  keyGenerator: (request) => request.ip,
  errorResponseBuilder: (request, context) => ({
    code: 429,
    error: 'Too Many Requests',
    message: `Rate limit exceeded, retry in ${context.after}`,
    expiresIn: context.after
  })
});

// Parse raw body for signature verification
app.addContentTypeParser('application/x-www-form-urlencoded', { parseAs: 'string' }, function (req, body, done) {
  req.rawBodyString = body;
  try {
    const parsed = qs.parse(body);
    done(null, parsed);
  } catch (err) {
    err.statusCode = 400;
    done(err, undefined);
  }
});

/**
 * Verifies MessageBird webhook JWT signature
 */
async function verifyMessageBirdSignature (request, reply) {
  const signatureJWT = request.headers['messagebird-signature-jwt'];
  const webhookSigningKey = process.env.MESSAGEBIRD_WEBHOOK_SIGNING_KEY;
  const rawBody = request.rawBodyString;

  if (!signatureJWT || !webhookSigningKey || typeof rawBody !== 'string') {
    request.log.warn({
        signatureJWT: !!signatureJWT,
        key: !!webhookSigningKey,
        rawBodyType: typeof rawBody
    }, 'Missing JWT signature header, signing key, or raw body.');
    reply.code(400).send({ error: 'Missing MessageBird signature JWT, key, or raw body' });
    return;
  }

  try {
    const isValid = messagebird.webhookSignatureJwt.verifySignature(
      signatureJWT,
      webhookSigningKey,
      request.raw.url,
      rawBody
    );

    if (!isValid) {
      request.log.error('Invalid webhook JWT signature received.');
      reply.code(401).send({ error: 'Invalid MessageBird signature' });
      return;
    }

    request.log.info('Webhook JWT signature verified successfully.');
  } catch (error) {
    request.log.error({ err: error }, 'Error during JWT signature verification.');
    reply.code(500).send({ error: 'Webhook signature verification failed internally' });
  }
}

/**
 * Generates contextual reply message
 */
function generateReplyMessage(incomingMessage) {
  const message = incomingMessage.toLowerCase().trim();

  if (message.includes('help') || message.includes('support')) {
    return 'Thanks for reaching out! Our support team will respond within 24 hours. For urgent issues, call 1-800-555-0123.';
  }

  if (message.includes('hours') || message.includes('open')) {
    return 'We\'re open Monday-Friday 9 AM-6 PM EST. Visit our website for more information: example.com/hours';
  }

  if (message.includes('price') || message.includes('cost')) {
    return 'For pricing information, visit example.com/pricing or reply with your email address for a detailed quote.';
  }

  return `Thanks for your message: "${incomingMessage}". We'll get back to you shortly!`;
}

/**
 * Sends an automated SMS reply with retry logic
 */
async function sendAutoReply(recipient, originalMessage, logger) {
  const replyText = generateReplyMessage(originalMessage);

  const params = {
    originator: process.env.MESSAGEBIRD_ORIGINATOR,
    recipients: [recipient],
    body: replyText
  };

  try {
    const response = await retry(
      async (bail) => {
        return new Promise((resolve, reject) => {
          mbClient.messages.create(params, (err, response) => {
            if (err) {
              if (err.statusCode && err.statusCode < 500) {
                logger.error({ err_ recipient }_ 'Client error sending SMS - not retrying');
                bail(err);
                return;
              }
              reject(err);
            } else {
              resolve(response);
            }
          });
        });
      }_
      {
        retries: 3_
        minTimeout: 1000_
        maxTimeout: 5000_
        onRetry: (err_ attempt) => {
          logger.warn({ err, attempt, recipient }, 'Retrying SMS send');
        }
      }
    );

    logger.info({
      messageId: response.id,
      recipient,
      status: response.recipients.items[0].status
    }, 'Auto-reply sent successfully');

  } catch (error) {
    logger.error({ err: error, recipient }, 'Failed to send auto-reply after retries');
    throw error;
  }
}

// Webhook endpoint for inbound SMS
app.post('/webhooks/inbound-sms', {
  preHandler: verifyMessageBirdSignature
}, async (request, reply) => {
  try {
    const payload = request.body;
    
    request.log.info({ payload }, 'Received inbound SMS webhook');

    const {
      id: messageId,
      originator: senderNumber,
      recipient: yourNumber,
      body: messageText,
      createdDatetime
    } = payload;

    if (!senderNumber || !messageText) {
      request.log.error({ payload }, 'Webhook payload missing required fields');
      return reply.code(400).send({ error: 'Invalid payload' });
    }

    request.log.info({
      messageId,
      from: senderNumber,
      to: yourNumber,
      text: messageText,
      timestamp: createdDatetime
    }, 'Processing inbound message');

    await sendAutoReply(senderNumber, messageText, request.log);

    reply.code(200).send({ status: 'received' });

  } catch (error) {
    request.log.error({ err: error }, 'Error processing webhook');
    reply.code(500).send({ error: 'Internal server error' });
  }
});

// Health check endpoint
app.get('/health', async (request, reply) => {
  reply.send({ status: 'ok', timestamp: new Date().toISOString() });
});

// Start server
const start = async () => {
  try {
    const port = process.env.PORT || 3000;
    await app.listen({ port, host: '0.0.0.0' });
    app.log.info(`Server listening on port ${port}`);
  } catch (err) {
    app.log.error(err);
    process.exit(1);
  }
};

start();

Production Deployment Best Practices for SMS Webhooks

Before deploying to production, implement these best practices:

Security Enhancements

• Use HTTPS only — Never accept webhooks over unencrypted HTTP connections
• Implement IP whitelisting — Restrict webhook access to MessageBird's IP ranges
• Rotate signing keys regularly — Update your MESSAGEBIRD_WEBHOOK_SIGNING_KEY periodically
• Add request validation — Validate all webhook payload fields before processing
• Enable CORS properly — Configure cross-origin policies for your specific use case

Scalability Improvements

• Use Redis for rate limiting — Distribute rate limits across multiple server instances
• Implement message queues — Process webhooks asynchronously using Bull or RabbitMQ
• Add horizontal scaling — Deploy behind a load balancer for high-traffic scenarios
• Cache frequently used data — Reduce API calls by caching configuration and lookup data
• Monitor performance — Track response times, error rates, and throughput metrics

Reliability Features

• Add dead letter queues — Store failed webhook processing attempts for retry
• Implement circuit breakers — Protect against cascade failures from external dependencies
• Use health checks — Monitor server availability with /health endpoints
• Set up alerts — Notify your team of webhook failures, rate limit hits, or API errors
• Log aggregation — Centralize logs using services like LogDNA, Datadog, or ELK stack

Error Handling

// Add global error handler
app.setErrorHandler((error, request, reply) => {
  request.log.error({ err: error, url: request.url }, 'Unhandled error');
  
  if (error.statusCode) {
    reply.status(error.statusCode).send({ 
      error: error.message,
      statusCode: error.statusCode 
    });
  } else {
    reply.status(500).send({ 
      error: 'Internal Server Error',
      statusCode: 500
    });
  }
});

// Graceful shutdown
const closeGracefully = async (signal) => {
  app.log.info(`Received ${signal}, closing server gracefully`);
  await app.close();
  process.exit(0);
};

process.on('SIGTERM', closeGracefully);
process.on('SIGINT', closeGracefully);

How to Scale Your SMS Webhook System

• Use Redis for rate limiting — Distribute rate limits across multiple server instances
• Implement message queues — Process webhooks asynchronously using Bull or RabbitMQ
• Add horizontal scaling — Deploy behind a load balancer for high-traffic scenarios
• Cache frequently used data — Reduce API calls by caching configuration and lookup data
• Monitor performance — Track response times, error rates, and throughput metrics

Troubleshooting Common MessageBird Webhook Issues

Why Is My Webhook Not Receiving Messages?

• Verify URL accessibility — Ensure your webhook URL is publicly accessible via HTTPS
• Check MessageBird configuration — Confirm webhook is active and pointing to correct URL
• Review firewall settings — Allow inbound traffic on your server's webhook port
• Test with ngrok — Use ngrok to expose localhost for initial testing
• Check server logs — Look for incoming requests and any error messages

Why Is MessageBird Signature Verification Failing?

• Confirm signing key — Verify your .env file contains the correct MESSAGEBIRD_WEBHOOK_SIGNING_KEY
• Check header name — Ensure you're reading messagebird-signature-jwt header (lowercase)
• Verify raw body access — Signature verification requires the unparsed request body
• Update SDK version — Ensure you're using a current version of the MessageBird SDK
• Test with MessageBird tools — Use MessageBird's webhook testing feature to verify configuration

Why Aren't My Auto-Replies Sending?

• Validate API key — Confirm your MESSAGEBIRD_API_KEY has sending permissions
• Check originator format — Ensure your originator number is in E.164 format (e.g., +14155552671)
• Review account balance — Verify your MessageBird account has sufficient credits
• Monitor rate limits — Check if you're exceeding MessageBird's API rate limits
• Examine error logs — Review detailed error messages in your Fastify logs

How to Fix High Latency in SMS Processing

• Optimize reply generation — Cache static responses and minimize processing time
• Move to async processing — Use message queues for non-urgent replies
• Reduce retry timeouts — Adjust minTimeout and maxTimeout in retry configuration
• Check network latency — Test connectivity between your server and MessageBird's API
• Monitor server resources — Ensure adequate CPU, memory, and network bandwidth

Advanced Features for Two-Way SMS Systems

Build upon this foundation with advanced features:

How to Store SMS Messages in a Database

Store inbound messages for analytics and compliance:

// Example with PostgreSQL
const { Client } = require('pg');
const pgClient = new Client({ connectionString: process.env.DATABASE_URL });

async function storeInboundMessage(messageData) {
  await pgClient.query(
    'INSERT INTO inbound_sms (message_id, sender, recipient, body, received_at) VALUES ($1, $2, $3, $4, $5)',
    [messageData.id, messageData.originator, messageData.recipient, messageData.body, messageData.createdDatetime]
  );
}

How to Implement AI-Powered SMS Responses

Implement AI-powered responses or integrate with customer support systems:

async function generateAIReply(message, sender) {
  // Integrate with OpenAI, Dialogflow, or your custom NLP engine
  const aiResponse = await yourAIService.generateResponse(message);
  return aiResponse;
}

How to Track Multi-Step SMS Conversations

Track multi-step conversations using Redis:

const Redis = require('ioredis');
const redis = new Redis(process.env.REDIS_URL);

async function getConversationState(phoneNumber) {
  const state = await redis.get(`conversation:${phoneNumber}`);
  return JSON.parse(state) || { step: 0 };
}

async function updateConversationState(phoneNumber, state) {
  await redis.setex(`conversation:${phoneNumber}`, 3600, JSON.stringify(state));
}

How to Handle SMS Opt-Out Requests Automatically

Handle unsubscribe requests automatically:

function generateReplyMessage(incomingMessage) {
  const message = incomingMessage.toLowerCase().trim();
  
  if (message === 'stop' || message === 'unsubscribe') {
    // Add user to opt-out list
    addToOptOutList(senderNumber);
    return 'You have been unsubscribed. Reply START to resubscribe.';
  }
  
  // ... rest of your reply logic ...
}

How to MessageThroughput Limit

Fastify can handle thousands of requests per second. Your limiting factor will likely be MessageBird's API rate limits and your server's resources. Implement queuing for high-volume scenarios.

Optimize Message Processing

// Add global error handler
app.setErrorHandler((error, request, reply) => {
  request.log.error({ err: error, url: request.url }, 'Unhandled error');
  
  if (error.statusCode) {
    reply.status(error.statusCode).send({ 
      error: error.message,
      statusCode: error.statusCode 
    });
  } else {
    reply.status(500).send({ 
      error: 'Internal Server Error',
      statusCode: 500
    });
  }
});

// Graceful shutdown
const closeGracefully = async (signal) => {
  app.log.info(`Received ${signal}, closing server gracefully`);
  await app.close();
  process.exit(0);
};

process.on('SIGTERM', closeGracefully);
process.on('SIGINT', closeGracefully);

Frequently Asked Questions

How much does MessageBird SMS cost?

MessageBird pricing varies by destination country and message volume. Inbound SMS messages typically cost between $0.005-$0.01 per message, while outbound SMS pricing ranges from $0.01-$0.50+ depending on the destination country. Volume discounts are available for high-traffic applications. Check MessageBird's pricing page for current rates specific to your target countries.

Can I send MMS messages with this setup?

This tutorial focuses on SMS messaging. To add MMS support, you'll need to modify the sendAutoReply function to include media URLs using MessageBird's MMS API. Add a mediaUrls array parameter containing HTTPS URLs of images, videos, or audio files (up to 5MB per file). Note that MMS support and pricing vary by country—verify MMS availability for your target regions in the MessageBird dashboard.

How do I handle multiple virtual numbers in one application?

Store a mapping of phone numbers to response logic in your database or configuration file. In your webhook handler, read the recipient field from the webhook payload to identify which MessageBird number received the message, then route to the appropriate response logic. This approach allows you to manage multiple SMS campaigns, departments, or brands from a single Fastify application.

What's the maximum message throughput for this setup?

Fastify can handle 20,000-30,000 requests per second on modern hardware, far exceeding typical SMS webhook volumes. Your actual throughput will be limited by MessageBird's API rate limits (typically 1,000+ messages per second for enterprise accounts) and your server's resources. For high-volume scenarios exceeding 100 messages per second, implement message queuing with Redis or RabbitMQ to process webhooks asynchronously.

How do I test MessageBird webhooks locally?

Use ngrok to expose your local development server to the internet: ngrok http 3000. Copy the generated HTTPS URL (e.g., https://abc123.ngrok.io) and add your webhook path (/webhooks/inbound-sms) to create the full webhook URL for MessageBird's dashboard. Ngrok provides request inspection, making it easy to debug webhook payloads during development.

Can I use TypeScript with MessageBird and Fastify?

Yes! Both Fastify and MessageBird provide official TypeScript type definitions. Install @types/node and create a tsconfig.json file in your project root. The MessageBird SDK includes built-in TypeScript types, while Fastify offers comprehensive type support for routes, plugins, and request/reply objects. TypeScript enhances development experience with autocomplete, type checking, and better documentation.

How do I implement GDPR compliance for SMS messaging?

Store explicit opt-in consent records with timestamps and IP addresses, honor opt-out requests immediately (within minutes, not hours), provide clear unsubscribe instructions in every marketing message (e.g., "Reply STOP to unsubscribe"), maintain audit logs of all message activity, and implement data retention policies to delete conversation data after your legally required retention period. Consider using a consent management platform for complex compliance requirements.

What's the difference between MessageBird and Bird?

MessageBird rebranded to Bird in early 2024 as part of a broader platform consolidation. The SMS API, Node.js SDK (npm package messagebird), and webhook functionality remain unchanged. Existing MessageBird accounts continue to work without migration. The Bird platform adds enhanced CRM and marketing automation features, but the core SMS infrastructure documented in this tutorial remains fully supported and operational.

How do I monitor webhook health and uptime?

Implement a /health endpoint (as shown in the complete code example) for external monitoring services like UptimeRobot or Pingdom. Track key metrics including webhook response time (aim for <500ms), error rate (should be <1%), signature verification failures, and MessageBird API success rates. Use application performance monitoring (APM) tools like New Relic, Datadog, or Sentry for detailed insights into webhook processing performance.

Can I rate limit specific phone numbers that spam my webhook?

Yes. Extend the rate limiting configuration to track both IP addresses and phone numbers. Add a custom keyGenerator function that extracts the originator field from webhook payloads and implements per-number rate limits. Store rate limit violations in Redis to maintain state across server restarts and enable blocking of persistent spam numbers at the application level before processing messages.

Conclusion

You've built a production-ready two-way SMS messaging system using MessageBird, Node.js, and Fastify. Your implementation includes webhook signature verification, automated reply logic, rate limiting, and error handling—all essential components for reliable SMS applications.

Key takeaways:

• You receive inbound SMS messages through MessageBird webhooks with JWT signature verification
• You send automated responses based on message content using the MessageBird SDK
• You handle errors gracefully with retry logic and comprehensive logging
• You protect your endpoint with rate limiting and security best practices
• You can scale horizontally to handle high-volume SMS traffic

Next steps to enhance your SMS system:

• Deploy your application to a production environment (AWS, Google Cloud, Azure, Heroku, or Railway)
• Add database integration to store conversation history and enable analytics
• Implement advanced reply logic with natural language processing or AI models
• Set up monitoring and alerting for webhook failures and performance degradation
• Scale horizontally with load balancers and message queues for enterprise traffic volumes

For more advanced MessageBird features, explore their official documentation and SMS API reference. Check out related guides on bulk SMS campaigns, message scheduling, and WhatsApp Business API integration for multi-channel messaging strategies.