Build Two-Way SMS Messaging in RedwoodJS with MessageBird

Build production-ready two-way SMS functionality into your RedwoodJS application using the MessageBird API and Node.js SDK. Send outbound SMS messages and receive inbound messages via webhooks to enable powerful communication features.

This guide covers initial project setup, secure API key management, core logic implementation, webhook handling with signature verification, message logging, and deployment. You'll have a robust system for interacting with users via SMS.

Project Overview and Goals

What You'll Build:

A RedwoodJS application that:

1. Sends Outbound SMS: Trigger SMS messages to users programmatically via GraphQL mutation
2. Receives Inbound SMS: Handle incoming SMS messages sent to a dedicated MessageBird number using secure webhook endpoint
3. Logs Communication: Store records of inbound and outbound messages in the database

Problem Solved:

Enable direct, reliable SMS communication channels within your application for notifications, alerts, user verification, customer support interactions, or any feature requiring SMS messaging.

Technologies Used:

• RedwoodJS: Full-stack JavaScript/TypeScript framework for the web. Provides integrated API (GraphQL), database (Prisma), and deployment capabilities.
• Node.js: Runtime environment for the RedwoodJS API side.
• MessageBird: Communication platform that provides SMS API and virtual numbers.
• MessageBird Node.js SDK: Simplifies interaction with the MessageBird API.
• Prisma: ORM used by RedwoodJS for database interactions.
• ngrok (development): Exposes local development server to the internet for testing incoming webhooks.

Architecture:

_____________________      ________________________      ____________________
| RedwoodJS Web App |----->| RedwoodJS API (GraphQL)|----->|     Database     |
| (Frontend)        |      | (Node.js / Prisma)   |      |   (PostgreSQL)   |
|___________________|      |________________________|      |____________________|
       ^                             | |  ^                          |
       |                             | |  |__________________________| (Log Messages)
       | (GraphQL Mutation)          | | (MessageBird SDK)
       |                             | |
___________________________      |_______________|       ________________________
| User's Mobile Device    |<----->|  MessageBird  |<----->| RedwoodJS Function   |
| (Sends/Receives SMS)    |      | (API/Webhook) |       | (Webhook Endpoint)   |
|___________________________|      |_______________|       |________________________|
                                      | |
                                      | | (Webhook Config in Flow Builder)
                                      | |
                               _____________
                               | `ngrok`   | (Development Only)
                               |___________|

Prerequisites:

• Node.js (v18 or later recommended)
• Yarn (v1 or later)
• RedwoodJS CLI: yarn global add redwoodjs@latest
• MessageBird Account (sign up at messagebird.com)
• Provisioned virtual phone number from MessageBird capable of sending/receiving SMS
• ngrok or similar tunneling tool for local development webhook testing

Expected Outcome:

A functional RedwoodJS application demonstrating SMS sending via GraphQL mutation and receiving/logging incoming SMS via webhook, ready for further feature integration and deployment.

1. Setting up the Project

Let's initialize a new RedwoodJS project and install necessary dependencies.

1. Create RedwoodJS Project: Open your terminal and run:

   bash

   yarn create redwood-app ./redwood-messagebird-app --typescript
   cd redwood-messagebird-app
   

   Using TypeScript provides better type safety and developer experience, especially for larger applications.

2. Install MessageBird SDK: Navigate to the api directory and add the MessageBird Node.js SDK:

   bash

   cd api
   yarn add messagebird
   cd ..
   

3. Configure Environment Variables: Sensitive information like API keys must never be committed to version control. We'll use environment variables.

   • Create a .env file in the project root (redwood-messagebird-app/.env).

   • Add the following lines, replacing placeholders later:

     ini

     # .env
     # MessageBird API Keys
     MESSAGEBIRD_ACCESS_KEY=YOUR_LIVE_OR_TEST_ACCESS_KEY
     MESSAGEBIRD_SIGNING_KEY=YOUR_WEBHOOK_SIGNING_KEY
     
     # Your purchased MessageBird number (E.164 format)
     MESSAGEBIRD_ORIGINATOR_NUMBER=+12005550199
     
     # (Optional) Your test mobile number (E.164 format)
     TEST_RECIPIENT_NUMBER=+12005550100
     

   • Explanation:

     • MESSAGEBIRD_ACCESS_KEY: Your primary key for authenticating API requests to MessageBird. Found in your MessageBird Dashboard under Developer Settings -> API access. Use a live key for sending real messages, or a test key for simulation.
     • MESSAGEBIRD_SIGNING_KEY: Used to verify incoming webhook requests originate from MessageBird. Found in Developer Settings -> Webhook Signing. CRITICAL for security.
     • MESSAGEBIRD_ORIGINATOR_NUMBER: The MessageBird virtual number you purchased, which will be used as the sender ID for outbound messages and is the number users will text to for inbound messages. Must be in E.164 format (e.g., +14155552671).
     • TEST_RECIPIENT_NUMBER: Your personal mobile number for testing outbound messages.

   • Add .env to .gitignore: Ensure the root .gitignore file contains .env to prevent accidentally committing your keys. RedwoodJS's default .gitignore should already include it.

4. Accessing Environment Variables in RedwoodJS: RedwoodJS automatically loads variables from .env into process.env. You can access them in your API-side code (services, functions) like process.env.MESSAGEBIRD_ACCESS_KEY.

2. Implementing Core Functionality (Outbound SMS)

Install the MessageBird SDK and create the core service for sending SMS messages.

Step 2.1: Install the MessageBird SDK

Navigate to your RedwoodJS project root directory and install the official MessageBird Node.js SDK:

cd your-redwoodjs-project
yarn workspace api add messagebird

Important: Use yarn workspace api add instead of yarn add to ensure the SDK installs into the API workspace (api/package.json), not the root package.json.

Step 2.2: Create the Outbound SMS Service

Generate a new service to encapsulate the outbound SMS logic:

yarn rw g service sms

This command creates api/src/services/sms/sms.js and api/src/services/sms/sms.test.js files.

Configure the sms.js service:

// api/src/services/sms/sms.js
import messagebird from 'messagebird';

// Initialize the MessageBird client using API key from environment variable
const client = messagebird(process.env.MESSAGEBIRD_API_KEY);

/**
 * Send an SMS message via MessageBird
 * @param {string} to - Recipient phone number in E.164 format (e.g., +1234567890)
 * @param {string} body - Message content (160 characters for single SMS)
 * @param {string} originator - Sender ID (phone number or alphanumeric, max 11 chars)
 * @returns {Promise<object&gt;} - MessageBird API response with message ID and status
 */
export const sendSMS = ({ to, body, originator }) =&gt; {
  return new Promise((resolve, reject) =&gt; {
    // Validate required parameters
    if (!to || !body || !originator) {
      return reject(new Error('Missing required parameters: to, body, and originator are required'));
    }

    const params = {
      originator,
      recipients: [to],
      body
    };

    client.messages.create(params, (err, response) =&gt; {
      if (err) {
        console.error('MessageBird API Error:', err);
        return reject(err);
      }
      console.log('SMS sent successfully:', response);
      resolve(response);
    });
  });
};

3. Building the API Layer (Inbound Webhook)

Handle incoming SMS messages through a webhook endpoint that receives and processes MessageBird notifications.

Step 3.1: Create the Webhook Handler Function

Generate a serverless function to handle incoming webhooks:

yarn rw g function webhook

This creates api/src/functions/webhook/webhook.js.

Implement the webhook handler:

// api/src/functions/webhook/webhook.js
import crypto from 'crypto';
import { db } from 'src/lib/db';

/**
 * Verify MessageBird webhook signature
 * Prevents unauthorized requests and ensures message authenticity
 */
const verifySignature = (request, body) => {
  const signature = request.headers['messagebird-signature'];
  const timestamp = request.headers['messagebird-request-timestamp'];
  
  if (!signature || !timestamp) {
    return false;
  }

  // Construct the signing payload
  const payload = `${timestamp}\n${body}`;
  
  // Calculate expected signature using your signing key
  const expectedSignature = crypto
    .createHmac('sha256', process.env.MESSAGEBIRD_SIGNING_KEY)
    .update(payload)
    .digest('hex');

  // Compare signatures using timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
};

/**
 * Handler for incoming webhook requests from MessageBird
 */
export const handler = async (event, context) => {
  // Only accept POST requests
  if (event.httpMethod !== 'POST') {
    return {
      statusCode: 405,
      body: JSON.stringify({ error: 'Method not allowed' })
    };
  }

  try {
    const body = event.body;
    
    // Verify the webhook signature
    if (!verifySignature(event, body)) {
      console.error('Invalid webhook signature');
      return {
        statusCode: 401,
        body: JSON.stringify({ error: 'Unauthorized' })
      };
    }

    const payload = JSON.parse(body);
    
    // Extract message data
    const { id, originator, body: messageBody, recipient, createdDatetime } = payload;

    // Store the incoming message in database
    await db.message.create({
      data: {
        messageBirdId: id,
        sender: originator,
        recipient: recipient,
        body: messageBody,
        direction: 'inbound',
        receivedAt: new Date(createdDatetime)
      }
    });

    console.log('Inbound message processed:', id);

    // Return 200 to acknowledge receipt
    return {
      statusCode: 200,
      body: JSON.stringify({ success: true })
    };

  } catch (error) {
    console.error('Webhook processing error:', error);
    return {
      statusCode: 500,
      body: JSON.stringify({ error: 'Internal server error' })
    };
  }
};

4. Securing Your Implementation

Protect your webhook endpoint from unauthorized access and ensure message authenticity through signature verification.

Webhook Signature Verification

Verify every incoming webhook request using MessageBird's signing key. This prevents unauthorized requests and confirms message authenticity.

How signature verification works:

1. MessageBird signs each webhook request using your signing key
2. The signature arrives in the messagebird-signature header
3. Calculate the expected signature using the request timestamp and body
4. Compare signatures using timing-safe comparison to prevent timing attacks

Implementation (already shown in webhook handler):

const verifySignature = (request, body) => {
  const signature = request.headers['messagebird-signature'];
  const timestamp = request.headers['messagebird-request-timestamp'];
  
  if (!signature || !timestamp) {
    return false;
  }

  const payload = `${timestamp}\n${body}`;
  
  const expectedSignature = crypto
    .createHmac('sha256', process.env.MESSAGEBIRD_SIGNING_KEY)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
};

Best practices:

• Reject requests with invalid signatures (return 401 Unauthorized)
• Log signature verification failures for security monitoring
• Rotate signing keys periodically (obtain new keys from MessageBird dashboard)
• Store signing keys in environment variables, never in code
• Use timing-safe comparison to prevent timing attacks

Environment Variable Security

Protect sensitive credentials by storing them as environment variables:

# .env
MESSAGEBIRD_API_KEY=your_api_key_here
MESSAGEBIRD_SIGNING_KEY=your_signing_key_here
MESSAGEBIRD_FROM_NUMBER=+1234567890

Security checklist:

• Add .env to .gitignore to prevent committing secrets
• Use different keys for development, staging, and production
• Rotate API keys regularly
• Monitor API key usage in MessageBird dashboard
• Implement rate limiting on webhook endpoints
• Use HTTPS only for webhook URLs
• Validate and sanitize all incoming data

5. Database Schema and Message Logging

Store incoming and outgoing SMS messages in your database for tracking, analytics, and conversation history.

Step 5.1: Create the Prisma Schema

Define a Message model in your Prisma schema to store SMS data:

// api/db/schema.prisma

model Message {
  id              String   @id @default(cuid())
  messageBirdId   String   @unique // MessageBird's message ID
  sender          String   // Phone number in E.164 format
  recipient       String   // Phone number in E.164 format
  body            String   // Message content
  direction       String   // "inbound" or "outbound"
  status          String?  // Delivery status (for outbound messages)
  receivedAt      DateTime @default(now())
  sentAt          DateTime?
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}

Step 5.2: Apply Database Migrations

Run Prisma migrations to create the database table:

yarn rw prisma migrate dev --name add_message_model

This command:

1. Creates a new migration file in api/db/migrations/
2. Applies the migration to your development database
3. Regenerates the Prisma Client with the new model

Step 5.3: Query Messages

Use Prisma Client to query message history:

// Get all messages for a specific phone number
const messages = await db.message.findMany({
  where: {
    OR: [
      { sender: '+1234567890' },
      { recipient: '+1234567890' }
    ]
  },
  orderBy: {
    receivedAt: 'desc'
  }
});

// Get conversation between two numbers
const conversation = await db.message.findMany({
  where: {
    OR: [
      { sender: '+1234567890', recipient: '+0987654321' },
      { sender: '+0987654321', recipient: '+1234567890' }
    ]
  },
  orderBy: {
    receivedAt: 'asc'
  }
});

6. Testing Your Implementation

Validate your SMS integration thoroughly before deploying to production.

Testing Outbound SMS

Test the SMS sending functionality through your GraphQL API:

mutation SendTestSMS {
  sendSMS(
    to: "+1234567890"
    body: "Test message from RedwoodJS"
    originator: "+0987654321"
  ) {
    success
    messageId
    error
  }
}

Verification steps:

1. Check your phone for the received SMS
2. Verify the message appears in MessageBird dashboard
3. Confirm the message saves to your database
4. Check logs for any errors

Testing Inbound Webhooks Locally

Use ngrok to expose your local development server for webhook testing:

Step 1: Install and start ngrok:

# Install ngrok (if not already installed)
brew install ngrok  # macOS
# or download from https://ngrok.com/download

# Start ngrok tunnel
ngrok http 8911

Step 2: Configure MessageBird webhook:

1. Copy the HTTPS URL from ngrok (e.g., https://abc123.ngrok.io)
2. Go to MessageBird dashboard → Numbers → Select your number
3. Set webhook URL to: https://abc123.ngrok.io/.redwood/functions/webhook
4. Save the configuration

Step 3: Send test SMS:

Send an SMS from your phone to your MessageBird number. Monitor:

• ngrok console for incoming requests
• RedwoodJS logs for webhook processing
• Database for stored message records

Simulating Webhook Requests

Test webhook handling without sending actual SMS messages using curl:

curl -X POST http://localhost:8911/.redwood/functions/webhook \
  -H "Content-Type: application/json" \
  -H "messagebird-signature: test_signature" \
  -H "messagebird-request-timestamp: $(date +%s)" \
  -d '{
    "id": "test123",
    "originator": "+1234567890",
    "body": "Test inbound message",
    "recipient": "+0987654321",
    "createdDatetime": "2024-01-15T10:30:00Z"
  }'

Note: This request will fail signature verification unless you calculate a valid signature. Temporarily disable signature verification for local testing only.

Common Testing Issues

Problem: Webhook receives requests but returns 401

• Solution: Verify your signing key matches the MessageBird dashboard
• Check timestamp format in signature calculation

Problem: Messages don't appear in database

• Solution: Check Prisma Client is properly initialized
• Verify database connection string in .env
• Run migrations: yarn rw prisma migrate dev

Problem: Outbound SMS fails with 401

• Solution: Verify API key in environment variables
• Check API key has correct permissions in MessageBird dashboard

Problem: ngrok tunnel disconnects

• Solution: Free ngrok tunnels expire after 2 hours
• Restart ngrok and update webhook URL in MessageBird dashboard

7. Deployment Considerations

Deploy your RedwoodJS SMS application with proper configuration for production environments.

Environment Variables

Configure production environment variables in your hosting platform:

MESSAGEBIRD_API_KEY=live_your_production_key
MESSAGEBIRD_SIGNING_KEY=your_production_signing_key
MESSAGEBIRD_FROM_NUMBER=+1234567890
DATABASE_URL=postgresql://user:password@host:5432/database

Platform-specific configuration:

• Vercel: Add variables in Project Settings → Environment Variables
• Netlify: Configure in Site Settings → Build & Deploy → Environment
• AWS/Render: Use platform-specific environment variable management
• Railway: Add variables in project dashboard

Webhook URL Configuration

Update your MessageBird webhook URL to point to your production domain:

1. Deploy your application to get the production URL
2. Navigate to MessageBird dashboard → Numbers
3. Select your virtual number
4. Set webhook URL to: https://your-domain.com/.redwood/functions/webhook
5. Test the webhook with a real SMS to verify connectivity

HTTPS Requirements

Use HTTPS for all webhook endpoints. MessageBird requires secure connections for webhook delivery.

Automatic HTTPS support:

• Vercel, Netlify, and Railway provide automatic HTTPS
• Custom domains require SSL certificate configuration
• Use Let's Encrypt for free SSL certificates on self-hosted deployments

Database Migrations

Apply database migrations before deploying new code:

# Production migration command
yarn rw prisma migrate deploy

Configure your CI/CD pipeline to run migrations automatically:

# Example: GitHub Actions workflow
- name: Run database migrations
  run: yarn rw prisma migrate deploy
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}

Monitoring and Logging

Implement monitoring to track SMS delivery and webhook processing:

Log critical events:

• Outbound SMS failures
• Webhook signature verification failures
• Database write errors
• MessageBird API errors

Recommended monitoring tools:

• Sentry: Error tracking and performance monitoring
• LogRocket: Session replay and error tracking
• Datadog: Application performance monitoring
• CloudWatch/Stackdriver: Cloud platform native monitoring

RedwoodJS logging configuration:

// api/src/lib/logger.js
import { createLogger } from '@redwoodjs/api/logger'

export const logger = createLogger({
  options: {
    level: process.env.LOG_LEVEL || 'info',
    redact: ['MESSAGEBIRD_API_KEY', 'MESSAGEBIRD_SIGNING_KEY']
  }
})

Rate Limiting

Implement rate limiting to prevent API abuse:

// api/src/functions/webhook/webhook.js
import { RateLimiter } from 'limiter'

const limiter = new RateLimiter({
  tokensPerInterval: 100,
  interval: 'minute'
})

export const handler = async (event, context) => {
  // Check rate limit
  const remainingRequests = await limiter.removeTokens(1)
  
  if (remainingRequests < 0) {
    return {
      statusCode: 429,
      body: JSON.stringify({ error: 'Too many requests' })
    }
  }
  
  // ... existing code ...
}

Conclusion

You have now successfully integrated two-way SMS messaging into your RedwoodJS application using MessageBird. You can send messages via a GraphQL mutation and receive incoming messages through a secure webhook function, with all communication logged to your database.

This foundation allows you to build various SMS-based features. Remember to prioritize security (especially webhook verification), handle errors gracefully, and consider the nuances of SMS communication like character limits and keyword handling.