Developer Guide: Implementing Vonage SMS in RedwoodJS with Node.js

Build SMS marketing campaigns and two-way messaging in your RedwoodJS application using the Vonage Messages API. Send outbound SMS messages for notifications or marketing campaigns and receive inbound messages via webhooks, leveraging RedwoodJS's full-stack architecture.

By completing this guide, you'll build a RedwoodJS application that:

• Sends SMS messages programmatically using the Vonage Node.js SDK
• Receives incoming SMS messages sent to your Vonage virtual number via secure webhooks
• Stores message logs in a database using Prisma
• Handles configuration securely using environment variables

This setup provides robust, scalable SMS communication for alerts, verification, and user engagement.

Prerequisites:

• Node.js: Version 20 or higher (check with node -v). Use nvm to manage Node versions.
• Yarn: Yarn Classic (v1.x) (check with yarn -v).
• Vonage API Account: Sign up free at Vonage API Dashboard. You'll need your API Key and Secret.
• Vonage Virtual Number: Purchase an SMS-capable virtual number through the Vonage Dashboard.
• ngrok: Expose your local development server to the internet for webhook testing. Download from ngrok.com.

Project Overview and Goals

Build a RedwoodJS application with these SMS components:

1. API Service: A RedwoodJS service on the API side to encapsulate Vonage interactions.
2. GraphQL Mutation: An endpoint to trigger sending an SMS message.
3. Webhook Handler: A RedwoodJS function to receive incoming SMS messages from Vonage.
4. Database Logging: Using Prisma to log basic details of sent and received messages.

Technologies:

• RedwoodJS: A full-stack JavaScript/TypeScript framework for the web. It provides structure, tooling (GraphQL, Prisma, Jest), and conventions for rapid development.
• Node.js: The JavaScript runtime environment RedwoodJS runs on.
• Vonage Messages API: Vonage's unified API for sending and receiving messages across various channels (we'll focus on SMS).
• @vonage/server-sdk: The official Vonage Node.js SDK for interacting with the API.
• Prisma: RedwoodJS's default ORM for database interactions.
• GraphQL: Used by RedwoodJS for API communication between the web and API sides.
• ngrok: For local webhook development and testing.

System Architecture:

[User] <--> [Redwood Web Frontend (React)] <--> [Redwood API (GraphQL)]
                                                      |
                                                      v
      +------------------------------------------<-- [Vonage Service (Node.js)] --> [Vonage API] --> [SMS Network] --> [Recipient Phone]
      |                                                 ^
      | (Webhook Trigger)                               | (API Call)
      v                                                 |
[Vonage Webhook Function (Node.js)]---------------------+
      |
      v
[Database (Prisma)]

How Do You Set Up a RedwoodJS Project for Vonage SMS?

Create a new RedwoodJS project and configure the necessary Vonage components.

1.1 Create RedwoodJS App:

Open your terminal and run the Create Redwood App command. Use TypeScript (default) and initialize a git repository.

# Choose a name for your project (e.g., redwood-vonage-sms)
yarn create redwood-app redwood-vonage-sms

# Follow the prompts:
# - Select your preferred language: TypeScript (press Enter for default)
# - Do you want to initialize a git repo?: yes (press Enter for default)
# - Enter a commit message: Initial commit (press Enter for default)
# - Do you want to run yarn install?: yes (press Enter for default)

# Navigate into your new project directory
cd redwood-vonage-sms

1.2 Environment Variables Setup:

Securely storing API keys and sensitive information is crucial. RedwoodJS uses .env files for this.

• Create a .env file in the root of your project:

  bash

  touch .env
  

• Add the following environment variables to your .env file. We'll get these values in the next steps.

  plaintext

  # .env
  VONAGE_API_KEY=YOUR_VONAGE_API_KEY
  VONAGE_API_SECRET=YOUR_VONAGE_API_SECRET
  VONAGE_APPLICATION_ID=YOUR_VONAGE_APPLICATION_ID
  VONAGE_PRIVATE_KEY_PATH=./private.key # Path to the private key file
  # Alternatively, provide the key content directly (useful for deployment)
  # VONAGE_PRIVATE_KEY_CONTENT=""-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n""
  VONAGE_VIRTUAL_NUMBER=YOUR_VONAGE_VIRTUAL_NUMBER # e.g., 14155551212
  

• Important: Add .env and private.key to your .gitignore file to prevent committing secrets. The default RedwoodJS .gitignore should already include .env, but double-check and add private.key.

  plaintext

  # .gitignore
  # ... other entries
  .env
  private.key
  *.private.key
  

1.3 Vonage Account Setup:

• API Key & Secret: Log in to your Vonage API Dashboard. Your API Key and Secret are displayed on the main page. Copy these into your .env file.
• Virtual Number: Navigate to ""Numbers"" > ""Buy numbers"" to purchase an SMS-capable number if you don't have one. Copy this number (in E.164 format, e.g., 14155551212) into VONAGE_VIRTUAL_NUMBER in your .env file.
• Set Default SMS API: Go to your Account Settings in the Dashboard. Under ""API settings"" > ""SMS settings"", ensure that ""Default SMS Setting"" is set to Messages API. This is crucial for using the @vonage/server-sdk features correctly. Save the changes.

1.4 Create Vonage Application:

Vonage Applications group your numbers and configurations.

• In the Vonage Dashboard, navigate to ""Applications"" > ""Create a new application"".
• Give it a name (e.g., ""RedwoodJS SMS App"").
• Click ""Generate public and private key"". Immediately save the private.key file that downloads. Save it in the root of your RedwoodJS project (or update VONAGE_PRIVATE_KEY_PATH in .env if you save it elsewhere, or use VONAGE_PRIVATE_KEY_CONTENT).
• Enable the ""Messages"" capability.
• You'll need placeholder URLs for now. Enter temporary HTTPS URLs (like https://example.com/webhooks/inbound and https://example.com/webhooks/status). We will update these later with our ngrok URL during development.
  • Inbound URL: https://example.com/webhooks/inbound
  • Status URL: https://example.com/webhooks/status
• Click ""Generate new application"".
• Copy the generated Application ID into VONAGE_APPLICATION_ID in your .env file.
• Link Your Number: Go back to the ""Applications"" list, find your new application, and click ""Link"" under the ""Linked numbers"" column. Select your Vonage virtual number and link it.

1.5 Install Vonage SDK:

Install the Vonage Node.js SDK specifically in the api workspace.

yarn workspace api add @vonage/server-sdk

How Do You Implement SMS Sending with Vonage in RedwoodJS?

Create a RedwoodJS service to handle sending SMS messages via Vonage.

2.1 Create SMS Service:

Use the RedwoodJS CLI to generate the service files.

yarn rw g service sms

This creates api/src/services/sms/sms.ts and related test/scenario files.

2.2 Configure Vonage Client:

It's good practice to initialize the Vonage client centrally. We can create a utility file for this.

• Create api/src/lib/vonage.ts:

  typescript

  // api/src/lib/vonage.ts
  import { Vonage } from '@vonage/server-sdk'
  import { logger } from 'src/lib/logger' // Redwood's built-in logger
  import fs from 'fs' // Import Node.js filesystem module if reading key needed
  import path from 'path' // Import Node.js path module
  
  let vonageInstance: Vonage | null = null
  
  export const getVonageClient = (): Vonage => {
    if (!vonageInstance) {
      const apiKey = process.env.VONAGE_API_KEY
      const apiSecret = process.env.VONAGE_API_SECRET
      const applicationId = process.env.VONAGE_APPLICATION_ID
      const privateKeyContent = process.env.VONAGE_PRIVATE_KEY_CONTENT
      const privateKeyPath = process.env.VONAGE_PRIVATE_KEY_PATH
  
      if (!apiKey || !apiSecret || !applicationId) {
        logger.error('Missing Vonage API Key, Secret, or Application ID in environment variables.')
        throw new Error('Vonage client API credential configuration is incomplete.')
      }
  
      // Determine the private key source: prioritize content over path
      let privateKey: string | Buffer
      if (privateKeyContent) {
        logger.info('Using Vonage private key from VONAGE_PRIVATE_KEY_CONTENT.')
        privateKey = privateKeyContent.replace(/\\n/g, '\n') // Ensure newlines are correct if escaped in env var
      } else if (privateKeyPath) {
        logger.info(`Using Vonage private key from path: ${privateKeyPath}`)
        // Resolve the path relative to the project root (where Redwood usually runs)
        const absolutePath = path.resolve(process.cwd(), privateKeyPath)
        if (!fs.existsSync(absolutePath)) {
          logger.error(`Private key file not found at path: ${absolutePath}`)
          throw new Error(`Vonage private key file not found at specified path: ${privateKeyPath}`)
        }
        // The SDK can handle the path directly, or you could read it:
        // privateKey = fs.readFileSync(absolutePath);
        privateKey = absolutePath // Pass the path to the SDK
      } else {
        logger.error('Missing Vonage Private Key configuration (neither VONAGE_PRIVATE_KEY_CONTENT nor VONAGE_PRIVATE_KEY_PATH found).')
        throw new Error('Vonage private key configuration is incomplete.')
      }
  
      try {
        vonageInstance = new Vonage({
          apiKey,
          apiSecret,
          applicationId,
          privateKey, // SDK accepts path string or key content Buffer/string
        })
        logger.info('Vonage client initialized successfully.')
      } catch (error) {
        logger.error({ error }, 'Failed to initialize Vonage client')
        throw error // Re-throw to prevent using a non-functional client
      }
    }
    return vonageInstance
  }
  
  • Why: This creates a singleton pattern for the Vonage client, ensuring we don't re-initialize it unnecessarily on every request. It centralizes credential validation and error handling during initialization. It now prioritizes reading the private key content from VONAGE_PRIVATE_KEY_CONTENT if available, falling back to the path specified in VONAGE_PRIVATE_KEY_PATH. Redwood's logger provides structured logging.

2.3 Implement sendSms Function:

Now, edit the generated service file (api/src/services/sms/sms.ts) to add the sending logic.

// api/src/services/sms/sms.ts
import type { MutationResolvers } from 'types/graphql'

import { logger } from 'src/lib/logger'
import { getVonageClient } from 'src/lib/vonage'
// Import db later when we add logging
// import { db } from 'src/lib/db'

interface SendSmsInput {
  to: string
  text: string
}

export const sendSms = async ({ to, text }: SendSmsInput): Promise<{ success: boolean; messageId?: string; error?: string }> => {
  logger.info({ to, textLength: text.length }, 'Attempting to send SMS')

  const vonage = getVonageClient() // Get initialized client
  const fromNumber = process.env.VONAGE_VIRTUAL_NUMBER

  if (!fromNumber) {
    logger.error('VONAGE_VIRTUAL_NUMBER is not set in environment variables.')
    return { success: false, error: 'Vonage sender number not configured.' }
  }

  // Basic validation (more robust validation is recommended)
  if (!to || !text) {
      logger.warn('Missing recipient (to) or text content.')
      return { success: false, error: 'Recipient phone number and text message are required.' }
  }
  // E.164 format validation recommended: ITU-T E.164 standard requires max 15 digits with + prefix
  // Example regex: /^\+?[1-9]\d{1,14}$/ validates: optional +, country code (1-3 digits), subscriber number
  // For production, consider using libphonenumber-js library for robust international validation

  try {
    const resp = await vonage.messages.send({
      message_type: 'text',
      to: to, // Recipient number
      from: fromNumber, // Your Vonage virtual number
      channel: 'sms',
      text: text, // The message content
    })

    logger.info({ messageId: resp.message_uuid }, 'SMS sent successfully via Vonage')

    // --- TODO: Add database logging here (Section 6) ---

    return { success: true, messageId: resp.message_uuid }
  } catch (error) {
    logger.error({ error, to }, 'Failed to send SMS via Vonage')
    // Attempt to provide a more specific error message if possible
    const errorMessage = error.response?.data?.title || error.message || 'Unknown error sending SMS.'
    return { success: false, error: errorMessage }
  }
}

// Note: We define the GraphQL Mutation in the SDL file next.
// The actual resolver function will be automatically picked up by Redwood
// based on the service function name matching the mutation name.

• Why: This service function encapsulates the logic for sending an SMS. It retrieves the Vonage client, performs basic validation, constructs the payload for the Vonage Messages API, calls the send method, and handles potential errors using try...catch. It returns a structured response indicating success or failure. Logging provides visibility into the process.

How Do You Build a GraphQL Mutation for SMS in RedwoodJS?

Define a GraphQL mutation to expose your sendSms service function.

3.1 Define GraphQL Schema (SDL):

Edit the schema definition file api/src/graphql/sms.sdl.ts.

// api/src/graphql/sms.sdl.ts
export const schema = gql`
  type SmsResponse {
    success: Boolean!
    messageId: String
    error: String
  }

  type Mutation {
    """"""Sends an SMS message using Vonage.""""""
    sendSms(to: String!, text: String!): SmsResponse! @skipAuth # Use @requireAuth in production!
  }
`

• Why: This defines the structure of our GraphQL API endpoint.
  • SmsResponse: Specifies the fields returned by the mutation.
  • Mutation: Defines the available mutations. sendSms takes to and text as non-nullable String arguments and returns an SmsResponse.
  • @skipAuth: For development only. This disables authentication. In a real application, you would replace this with @requireAuth to ensure only logged-in users can trigger the mutation, implementing RedwoodJS Authentication.

3.2 Test the Mutation:

1. Start the development server:

   bash

   yarn rw dev
   

2. Open your browser to the RedwoodJS GraphQL Playground: http://localhost:8911/graphql.

3. In the left panel, enter the following mutation (replace `YOUR_REAL_PHONE_NUMBER` with your actual phone number in E.164 format):

   graphql

   mutation SendTestSms {
     sendSms(to: ""`YOUR_REAL_PHONE_NUMBER`"", text: ""Hello from RedwoodJS and Vonage!"") {
       success
       messageId
       error
     }
   }
   

4. Click the ""Play"" button.

You should receive an SMS on your phone, and the GraphQL response should look like:

{
  ""data"": {
    ""sendSms"": {
      ""success"": true,
      ""messageId"": ""some-unique-message-uuid"",
      ""error"": null
    }
  }
}

If you get success: false, check the error message and review the terminal output where yarn rw dev is running for logs from api/src/services/sms/sms.ts. Common issues include incorrect API credentials, wrong phone number formats, or the private key file not being found/read correctly.

3.3 curl Example:

You can also test the GraphQL endpoint using curl:

curl http://localhost:8911/graphql \
  -H 'Content-Type: application/json' \
  --data-raw '{""query"":""mutation SendTestSms { sendSms(to: \""`YOUR_REAL_PHONE_NUMBER`\"", text: \""Hello via curl!\"") { success messageId error } }""}'

Replace `YOUR_REAL_PHONE_NUMBER` accordingly.

How Do You Receive SMS Messages via Webhooks in RedwoodJS?

Configure Vonage to send incoming SMS messages to your application via webhooks.

4.1 Expose Localhost with ngrok:

Since your RedwoodJS app is running locally, Vonage can't reach it directly. We use ngrok to create a secure tunnel.

• If yarn rw dev is running, stop it (Ctrl+C).

• Start ngrok to forward to Redwood's API port (usually 8911):

  bash

  # Make sure you've signed up and configured your ngrok authtoken
  ngrok http 8911
  

• ngrok will display a public ""Forwarding"" URL (e.g., https://<unique-id&gt;.ngrok-free.app). Copy the HTTPS version of this URL.

4.2 Update Vonage Application Webhook URLs:

• Go back to your Vonage Application settings in the Dashboard (""Applications"" > Your App Name > Edit).
• Update the Messages capability URLs:
  • Inbound URL: YOUR_NGROK_HTTPS_URL/webhooks/inbound
  • Status URL: YOUR_NGROK_HTTPS_URL/webhooks/status
  • (Replace YOUR_NGROK_HTTPS_URL with the URL you copied from ngrok).
• Make sure the method for both is POST.
• Save the changes.

4.3 Create RedwoodJS Webhook Handler:

RedwoodJS functions are perfect for webhooks. Generate a function:

yarn rw g function vonageWebhook

This creates api/src/functions/vonageWebhook.ts.

4.4 Implement Webhook Logic:

Modify api/src/functions/vonageWebhook.ts to handle incoming messages and status updates. This version includes logic to handle both JSON and form-urlencoded payloads.

// api/src/functions/vonageWebhook.ts
import type { APIGatewayEvent, Context } from 'aws-lambda'
import { logger } from 'src/lib/logger'
import querystring from 'node:querystring' // Use Node's built-in querystring parser
// Import db later when we add logging
// import { db } from 'src/lib/db'

/**
 * Parses the request body based on Content-Type header.
 * Handles JSON and form-urlencoded data.
 */
const parseRequestBody = (event: APIGatewayEvent): Record<string_ any&gt; =&gt; {
  const contentType = event.headers['content-type'] || event.headers['Content-Type'] || ''
  const body = event.body || ''

  if (!body) {
    return {}
  }

  try {
    if (contentType.includes('application/json')) {
      return JSON.parse(body)
    } else if (contentType.includes('application/x-www-form-urlencoded')) {
      return querystring.parse(body)
    } else {
      // Attempt JSON parse as a fallback, or handle other types if needed
      logger.warn(`Unexpected Content-Type: ${contentType}. Attempting JSON parse.`)
      return JSON.parse(body)
    }
  } catch (error) {
    logger.error({ error, body, contentType }, 'Failed to parse webhook request body')
    // Return empty object or throw, depending on how you want to handle parse failures
    return {}
  }
}


/**
 * The handler function is your serverless function's execution entry point.
 * You have access to the request context like headers, path, query parameters, and body.
 *
 * @see https://redwoodjs.com/docs/functions
 */
export const handler = async (event: APIGatewayEvent, _context: Context) =&gt; {
  logger.info({ path: event.path }, 'Received request on Vonage webhook handler')

  // Vonage expects a 200 OK response quickly, otherwise it will retry.
  // Respond immediately and process asynchronously if needed, though for logging it's usually fast enough.

  try {
    // Parse the body based on content type
    const body = parseRequestBody(event)
    logger.debug({ body }, 'Webhook payload received and parsed')

    // Check if parsing failed (returned empty object from our helper)
    if (Object.keys(body).length === 0 && event.body) {
       logger.error('Webhook body parsing resulted in empty object, check parseRequestBody logic and logs.')
       // Consider returning 400 Bad Request if parsing is essential
       // return { statusCode: 400, body: JSON.stringify({ error: 'Invalid request body' }) }
    }


    // Differentiate based on the path Vonage hits
    if (event.path.endsWith('/webhooks/inbound')) {
      // --- Handle Incoming SMS Message ---
      logger.info('Processing inbound SMS webhook')
      // Extract fields carefully, accounting for potential differences between JSON/form data key names if any
      const { msisdn, to, messageId, text, type, 'message-timestamp': timestamp } = body

      if (type === 'text' && msisdn && to && messageId && text) {
        logger.info(
          { from: msisdn, to, messageId, textLength: text.length },
          'Received valid inbound SMS'
        )
        // --- TODO: Add database logging here (Section 6) ---
        // --- TODO: Add business logic here (e.g., auto-reply, trigger action) ---

      } else {
        logger.warn({ body }, 'Received inbound webhook with unexpected format or missing fields')
      }

    } else if (event.path.endsWith('/webhooks/status')) {
      // --- Handle Message Status Update ---
      logger.info('Processing message status webhook')
      // Status webhooks often use snake_case keys
      const { message_uuid, status, timestamp, to, from, error } = body

      if (message_uuid) { // Check if the primary identifier exists
          logger.info({ message_uuid, status, to }, 'Received message status update')
          // --- TODO: Update message status in the database (Section 6) ---
          if (error) {
            logger.error({ message_uuid, error }, 'Message delivery failed')
          }
      } else {
          logger.warn({ body }, 'Received status webhook without message_uuid')
      }

    } else {
      logger.warn(`Webhook called on unexpected path: ${event.path}`)
    }

    // Always return 200 OK to Vonage to prevent retries
    return {
      statusCode: 200,
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ message: 'Webhook received successfully' }),
    }
  } catch (error) {
    logger.error({ error, requestBody: event.body }, 'Error processing Vonage webhook') // Log raw body on error
    // Still return 200 to Vonage if possible, but log the error thoroughly
    // If the error is critical (e.g., unhandled exception during processing), a 500 might be necessary, but Vonage will retry.
    return {
      statusCode: 200, // Or 500 if absolutely necessary
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ error: 'Failed to process webhook' }),
    }
  }
}

• Why: This function acts as the endpoint for Vonage. It now includes a parseRequestBody helper to handle both application/json and application/x-www-form-urlencoded content types, making it more robust. It uses the event.path to determine if it's an inbound message or a status update. It parses the payload, logs relevant information, and importantly, returns a 200 OK status code promptly to acknowledge receipt to Vonage. Error handling ensures issues are logged without causing Vonage to endlessly retry (unless a 500 is returned).

4.5 Test Receiving SMS:

1. Ensure ngrok is running and pointing to port 8911.
2. Start the RedwoodJS dev server: yarn rw dev.
3. Send an SMS from your physical phone to your Vonage virtual number.
4. Check the logs: Look at the terminal running yarn rw dev. You should see log entries from api/src/functions/vonageWebhook.ts indicating an ""inbound SMS"" was received, along with details like the sender number (msisdn) and the message text. Check for any parsing warnings or errors.
5. Check ngrok console: You can also inspect the request details in the ngrok web interface (usually http://127.0.0.1:4040), including the Content-Type header sent by Vonage.

How Do You Implement Error Handling and Logging for SMS?

• Error Handling: We've implemented basic try...catch blocks in the service (sendSms) and the webhook handler. In sendSms, we catch errors from the Vonage SDK and return a { success: false, error: '...' } object. In the webhook, we catch errors during processing but still try to return 200 OK to Vonage, logging the error internally. The webhook now also handles potential body parsing errors. More specific error types could be handled (e.g., distinguishing network errors from API errors from Vonage).
• Logging: RedwoodJS's built-in Pino logger (src/lib/logger) is used. We log key events: attempts to send, success/failure of sending, reception of webhooks, specific details from payloads, and errors. logger.info, logger.warn, logger.error, and logger.debug are used appropriately. For production, configure log levels and destinations (e.g., sending logs to a service like Datadog or Logflare).
• Retry Mechanisms:
  • Sending: The current sendSms doesn't implement retries. For critical messages, you could wrap the vonage.messages.send call in a retry loop with exponential backoff (using libraries like async-retry or p-retry) for transient network errors or temporary Vonage API issues.
  • Receiving: Vonage handles retries automatically if your webhook endpoint doesn't return a 200 OK status within a reasonable time (a few seconds). Our handler is designed to return 200 quickly, even if background processing fails, to prevent unnecessary Vonage retries.

Example: Testing Error Scenario (Send SMS)

Modify the sendSms service temporarily to force an error, e.g., provide an invalid to number format known to cause Vonage API errors, or temporarily change the API key in .env to something invalid. Then trigger the sendSms mutation and observe the logged error and the { success: false, ... } response.

How Do You Create a Database Schema for SMS Logging?

Let's log sent and received messages to the database using Prisma.

6.1 Define Prisma Schema:

Edit api/db/schema.prisma. Add a SmsLog model.

// api/db/schema.prisma

datasource db {
  provider = ""sqlite"" // Or ""postgresql"", ""mysql""
  url      = env(""DATABASE_URL"")
}

generator client {
  provider      = ""prisma-client-js""
  binaryTargets = ""native""
}

// Define your database tables here.
// See https://redwoodjs.com/docs/schema-migrations for more info.

model SmsLog {
  id           String    @id @default(cuid())
  direction    String    // ""OUTBOUND"" or ""INBOUND""
  vonageId     String    @unique // message_uuid from Vonage, or a generated unique ID for failures
  fromNumber   String
  toNumber     String
  body         String?   // The message text
  status       String?   // e.g., ""SUBMITTED"", ""DELIVERED"", ""FAILED"", ""RECEIVED""
  vonageStatus String?   // Raw status from Vonage status webhook
  error        String?   // Error message if sending/processing failed
  createdAt    DateTime  @default(now())
  updatedAt    DateTime  @updatedAt
}

• Why: This schema defines a table to store essential information about each SMS message, including its direction, unique Vonage ID, sender/recipient, content, status, and timestamps. The vonageId is unique to prevent duplicate entries from retried webhooks (though upsert logic is better) and uses a CUID as a fallback if the Vonage ID isn't obtained.

6.2 Create and Run Migration:

Apply the schema changes to your database.

# Create a new migration file based on schema changes
yarn rw prisma migrate dev --name add-sms-log

# This command also applies the migration

6.3 Update Service and Webhook to Log Data:

Modify the sendSms service and the vonageWebhook function to interact with the database. You might need to add the cuid package: yarn workspace api add cuid.

• api/src/services/sms/sms.ts (sendSms):

  typescript

  // api/src/services/sms/sms.ts
  import type { MutationResolvers } from 'types/graphql'
  import { logger } from 'src/lib/logger'
  import { getVonageClient } from 'src/lib/vonage'
  import { db } from 'src/lib/db' // Import db
  import cuid from 'cuid' // Import cuid for generating unique IDs
  
  interface SendSmsInput {
    to: string
    text: string
  }
  
  export const sendSms = async ({ to, text }: SendSmsInput): Promise<{ success: boolean; messageId?: string; error?: string }> => {
    logger.info({ to, textLength: text.length }, 'Attempting to send SMS')
  
    const vonage = getVonageClient()
    const fromNumber = process.env.VONAGE_VIRTUAL_NUMBER
  
    if (!fromNumber) {
      logger.error('VONAGE_VIRTUAL_NUMBER is not set in environment variables.')
      return { success: false, error: 'Vonage sender number not configured.' }
    }
  
    if (!to || !text) {
      logger.warn('Missing recipient (to) or text content.')
      return { success: false, error: 'Recipient phone number and text message are required.' }
    }
  
    let messageId: string | undefined = undefined;
    let success = false;
    let errorMessage: string | undefined = undefined;
    // Generate a placeholder ID in case the send fails before we get one from Vonage
    const placeholderId = `failed-${cuid()}`
  
    try {
      const resp = await vonage.messages.send({
          message_type: 'text',
          to: to,
          from: fromNumber,
          channel: 'sms',
          text: text,
      });
      messageId = resp.message_uuid;
      success = true;
      logger.info({ messageId }, 'SMS sent successfully via Vonage');
    } catch (error) {
      logger.error({ error, to }, 'Failed to send SMS via Vonage');
      errorMessage = error.response?.data?.title || error.message || 'Unknown error sending SMS.';
      success = false;
      // Keep messageId as undefined, we'll use the placeholder in the log
    }
  
    // --- Log to Database ---
    const finalVonageId = messageId || placeholderId;
    try {
      await db.smsLog.create({
        data: {
          direction: 'OUTBOUND',
          // Use actual ID if available, otherwise use the generated unique placeholder
          vonageId: finalVonageId,
          fromNumber: fromNumber, // Checked non-null earlier
          toNumber: to,
          body: text,
          status: success ? 'SUBMITTED' : 'FAILED', // Initial status
          error: errorMessage,
        },
      });
      logger.debug({ vonageId: finalVonageId }, 'Logged outbound SMS attempt to database');
    } catch (dbError) {
      logger.error({ dbError, vonageId: finalVonageId }, 'Failed to log outbound SMS to database');
      // Decide if this failure should impact the overall success status returned to the user
    }
    // --- End Log to Database ---
  
    // Return the actual messageId if successful, otherwise it remains undefined
    return { success, messageId, error: errorMessage };
  }
  

• api/src/functions/vonageWebhook.ts (handler):

  typescript

  // api/src/functions/vonageWebhook.ts
  import type { APIGatewayEvent, Context } from 'aws-lambda'
  import { logger } from 'src/lib/logger'
  import { db } from 'src/lib/db' // Import db
  import querystring from 'node:querystring'
  
  // (Keep the parseRequestBody helper function from section 4.4 here)
  const parseRequestBody = (event: APIGatewayEvent): Record<string_ any&gt; =&gt; {
    const contentType = event.headers['content-type'] || event.headers['Content-Type'] || ''
    const body = event.body || ''
  
    if (!body) {
      return {}
    }
  
    try {
      if (contentType.includes('application/json')) {
        return JSON.parse(body)
      } else if (contentType.includes('application/x-www-form-urlencoded')) {
        return querystring.parse(body)
      } else {
        logger.warn(`Unexpected Content-Type: ${contentType}. Attempting JSON parse.`)
        return JSON.parse(body)
      }
    } catch (error) {
      logger.error({ error, body, contentType }, 'Failed to parse webhook request body')
      return {}
    }
  }
  
  
  export const handler = async (event: APIGatewayEvent, _context: Context) =&gt; {
    logger.info({ path: event.path }, 'Received request on Vonage webhook handler')
  
    try {
      const body = parseRequestBody(event)
      logger.debug({ body }, 'Webhook payload received and parsed')
  
      if (Object.keys(body).length === 0 && event.body) {
         logger.error('Webhook body parsing resulted in empty object, check parseRequestBody logic and logs.')
         // Potentially return 400 here if needed
      }
  
      if (event.path.endsWith('/webhooks/inbound')) {
        logger.info('Processing inbound SMS webhook')
        const { msisdn, to, messageId, text, type } = body
  
        if (type === 'text' && msisdn && to && messageId && text) {
          logger.info({ from: msisdn, to, messageId, textLength: text.length }, 'Received valid inbound SMS')
          try {
            await db.smsLog.create({
              data: {
                direction: 'INBOUND',
                vonageId: messageId,
                fromNumber: msisdn,
                toNumber: to,
                body: text,
                status: 'RECEIVED', // Status for inbound messages
              },
            })
            logger.debug({ vonageId: messageId }, 'Logged inbound SMS to database')
          } catch (dbError) {
            // Handle potential duplicate messageId errors if Vonage retries
            if (dbError.code === 'P2002' && dbError.meta?.target?.includes('vonageId')) {
               logger.warn({ vonageId: messageId }, 'Attempted to log duplicate inbound SMS (vonageId exists). Ignoring.')
            } else {
               logger.error({ dbError, vonageId: messageId }, 'Failed to log inbound SMS to database')
            }
          }
          // Add business logic here
        } else {
          logger.warn({ body }, 'Received inbound webhook with unexpected format or missing fields')
        }
  
      } else if (event.path.endsWith('/webhooks/status')) {
        logger.info('Processing message status webhook')
        const { message_uuid, status, timestamp, to, from, error } = body
  
        if (message_uuid) {
          logger.info({ message_uuid, status, to }, 'Received message status update')
          try {
            await db.smsLog.update({
              where: { vonageId: message_uuid },
              data: {
                status: status?.toUpperCase(), // Normalize status (e.g., 'delivered' -&gt; 'DELIVERED')
                vonageStatus: status, // Store raw status from Vonage
                error: error ? JSON.stringify(error) : undefined, // Store error details if present
                updatedAt: timestamp ? new Date(timestamp) : new Date(), // Use Vonage timestamp if available
              },
            })
            logger.debug({ vonageId: message_uuid, status }, 'Updated SMS status in database')
          } catch (dbError) {
            // Log error if update fails (e.g., record not found)
            logger.error({ dbError, vonageId: message_uuid }, 'Failed to update SMS status in database')
          }
          if (error) {
            logger.error({ message_uuid, error }, 'Message delivery failed according to status update')
          }
        } else {
          logger.warn({ body }, 'Received status webhook without message_uuid')
        }
      } else {
        logger.warn(`Webhook called on unexpected path: ${event.path}`)
      }
  
      return {
        statusCode: 200,
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ message: 'Webhook received successfully' }),
      }
    } catch (error) {
      logger.error({ error, requestBody: event.body }, 'Error processing Vonage webhook')
      return {
        statusCode: 200, // Still return 200 to prevent Vonage retries unless absolutely necessary
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ error: 'Failed to process webhook' }),
      }
    }
  }
  

• Why: The sendSms service now logs the attempt to the SmsLog table, recording whether it was initially submitted or failed. The vonageWebhook handler logs incoming messages (INBOUND) and updates the status of existing outbound messages based on status webhooks (OUTBOUND). It uses upsert or update logic (here update for status, create for inbound with duplicate check) to handle message states correctly, including potential retries from Vonage for inbound messages. Error handling for database operations is included.

Frequently Asked Questions About Vonage SMS in RedwoodJS

What Node.js version does RedwoodJS require for Vonage integration?

RedwoodJS requires Node.js version 20 or higher as of 2025. Check your version with node -v and use nvm (Node Version Manager) to switch versions if needed. Vonage's @vonage/server-sdk works seamlessly with Node.js 20 LTS. Avoid Node.js 21+ for production deployments, as it may cause compatibility issues with certain deployment targets like AWS Lambda.

How do I get Vonage API credentials for RedwoodJS?

Log into the Vonage API Dashboard and locate your API Key and Secret on the main page. Create a new Application under "Applications" > "Create a new application", enable the Messages capability, and generate a private key file. Download the private.key file immediately and store it in your project root. Copy the Application ID into your .env file. Purchase an SMS-capable virtual number from "Numbers" > "Buy numbers" and link it to your application.

What is E.164 phone number format and why does Vonage require it?

E.164 is the ITU-T international telephone numbering standard that ensures globally unique phone numbers. The format starts with a + sign, followed by the country code (1-3 digits) and subscriber number, with a maximum of 15 digits total (e.g., +14155551234). Vonage requires E.164 format to eliminate routing ambiguity across international SMS networks. Use the regex pattern /^\+?[1-9]\d{1,14}$/ for basic validation, or implement libphonenumber-js for production-grade validation.

How do I secure Vonage webhooks in RedwoodJS?

Vonage webhooks in RedwoodJS functions handle incoming SMS and status updates. Secure them by validating the webhook signature using Vonage's JWT verification (check the Authorization header), implementing IP whitelist restrictions for Vonage's webhook IPs, using HTTPS endpoints only (required by Vonage), and storing webhook URLs as environment variables. Always return HTTP 200 status within a few seconds to prevent Vonage from retrying failed webhook deliveries.

What are SMS character limits with Vonage Messages API?

SMS messages use two encoding types: GSM-7 encoding supports 160 characters per segment (standard Latin characters), while UCS-2 encoding supports 70 characters per segment (required for emojis, Arabic, Chinese, Korean, Japanese, or Cyrillic scripts). Messages exceeding these limits split into multiple segments automatically, with each segment consuming additional credits. Special characters like | ^ € { } [ ] ~ \ require escape codes in GSM-7, consuming two character positions each.

How do I implement SMS marketing campaigns with rate limiting in RedwoodJS?

For marketing campaigns, create a batch processing service that reads recipient lists from your Prisma database and sends messages with controlled rate limiting. Implement exponential backoff using libraries like p-retry or async-retry to handle Vonage API rate limits (typically 10-20 messages per second). Store campaign status in your database to track delivery states. Use Vonage's status webhooks to update delivery receipts and handle failures. Always comply with TCPA (US), GDPR (Europe), and local SMS marketing regulations requiring user opt-in.

Can I send bulk SMS messages to multiple recipients with this RedwoodJS setup?

Yes, extend the sendSms service to accept an array of recipients and implement batch processing with rate limiting. Create a GraphQL mutation that queues messages in your database, then use RedwoodJS background jobs (via @redwoodjs/jobs) to process the queue asynchronously. This prevents timeout issues with large campaigns. Monitor Vonage API rate limits and implement exponential backoff for failed messages. Track campaign progress using Prisma database queries and provide real-time updates via GraphQL subscriptions.

How do I handle SMS delivery failures and retries in production?

Vonage sends delivery status updates to your status webhook endpoint. Update the SmsLog database record with the status (DELIVERED, FAILED, etc.) when receiving status webhooks. For failed messages, implement a retry strategy: store failed messages in a separate queue, implement exponential backoff (1 minute, 5 minutes, 30 minutes), and limit total retry attempts to 3-5. Log all failures with error details from Vonage's response. Consider implementing dead letter queues for permanently failed messages that require manual review.

What security best practices should I follow for Vonage credentials in RedwoodJS?

Never commit .env files or private.key files to version control – add them to .gitignore. Use environment variables for all sensitive credentials (API Key, Secret, Application ID, Private Key). For production, use secrets management services like AWS Secrets Manager, HashiCorp Vault, or Vercel Environment Variables. Rotate credentials every 90 days and audit API usage through the Vonage Dashboard. Set file permissions to 600 for private key files (chmod 600 private.key on Unix systems). Use VONAGE_PRIVATE_KEY_CONTENT environment variable for containerized deployments to avoid file system dependencies.