Developer Guide: Sending SMS with Infobip in RedwoodJS

This guide provides a step-by-step walkthrough for integrating Infobip's SMS API into a RedwoodJS application to send basic text messages. We'll cover project setup, creating a dedicated service, building an API endpoint, handling configuration securely, and basic error handling.

By the end of this tutorial, you will have a functional RedwoodJS backend capable of sending SMS messages via Infobip triggered by an API call. This solves the common need to programmatically send notifications, alerts, or messages to users via a reliable channel.

Technologies Used:

• RedwoodJS: A full-stack JavaScript/TypeScript framework for the web. Chosen for its integrated structure (frontend, backend, database) and conventions that streamline development (like Services and Cells).
• Infobip: A global communications platform providing APIs for various channels, including SMS. Chosen for its robust API and developer tooling.
• Infobip Node.js SDK: Simplifies interaction with the Infobip API within a Node.js environment like RedwoodJS's backend.
• Node.js: The runtime environment for RedwoodJS's API side.
• Yarn: The package manager used by RedwoodJS.

System Architecture:

A simple diagram illustrating the flow:

[Client/User] -> [RedwoodJS API Function (/sendSms)] -> [RedwoodJS SMS Service] -> [Infobip Node.js SDK] -> [Infobip API] -> [Recipient's Phone]

Prerequisites:

• Node.js (Version specified by current RedwoodJS requirements, typically latest LTS)
• Yarn (Version 1.x)
• An active Infobip account (Sign up for free)
• Your Infobip API Key and Base URL.

Final Outcome:

A RedwoodJS application with a serverless function endpoint (/api/sendSms) that accepts a destination phone number and message text, and uses the Infobip API to send the SMS.

1. Setting up the RedwoodJS Project

We'll start by creating a fresh RedwoodJS project and installing the necessary dependency for Infobip.

1. Create a New RedwoodJS Project:

Open your terminal and run the following command. Replace redwood-infobip-sms with your desired project name.

yarn create redwood-app redwood-infobip-sms
cd redwood-infobip-sms

This command scaffolds a new RedwoodJS project with the standard directory structure (web side, api side, etc.).

2. Install Infobip Node.js SDK:

Navigate to the project directory if you haven't already, and install the Infobip SDK:

yarn workspace api add @infobip-api/sdk

We use yarn workspace api add to ensure the dependency is added specifically to the API side of our RedwoodJS project, where the SMS sending logic will reside.

3. Configure Environment Variables:

Sensitive credentials like API keys should never be hardcoded. RedwoodJS uses .env files for environment variables. Create a .env file in the root of your project:

touch .env

Add the following lines to your newly created .env file, replacing the placeholder values with your actual Infobip credentials:

# .env
# Infobip Configuration
INFOBIP_API_KEY='YOUR_INFOBIP_API_KEY'
INFOBIP_BASE_URL='YOUR_INFOBIP_BASE_URL'
# Your registered Infobip Sender ID (e.g., a phone number or alphanumeric ID)
INFOBIP_SENDER_ID='YourSenderID'

• INFOBIP_API_KEY: Your secret API key obtained from the Infobip portal.
• INFOBIP_BASE_URL: The base URL for the Infobip API specific to your account.
• INFOBIP_SENDER_ID: The sender identifier (phone number or alphanumeric name) approved in your Infobip account that will appear as the sender of the SMS.

Why Environment Variables? Using environment variables is crucial for security and configuration management. It prevents leaking sensitive keys into your version control (like Git) and allows different configurations for development, staging, and production environments. Remember to add .env to your .gitignore file (RedwoodJS usually does this by default).

2. Creating the RedwoodJS Service

RedwoodJS services encapsulate business logic on the API side. We'll create a service to handle interactions with the Infobip SDK.

1. Generate the SMS Service:

Use the RedwoodJS CLI to generate the service files:

yarn rw g service sms

This command creates:

• api/src/services/sms/sms.js: Where our SMS sending logic will live.
• api/src/services/sms/sms.scenarios.js: For defining seed data for testing.
• api/src/services/sms/sms.test.js: For writing unit tests for the service.

We will focus on api/src/services/sms/sms.js.

3. Implementing the SMS Sending Logic

Now, let's add the code to the sms service to actually send the message using the Infobip SDK.

1. Edit the Service File:

Open api/src/services/sms/sms.js and replace its contents with the following:

// api/src/services/sms/sms.js
import { Infobip, AuthType } from '@infobip-api/sdk'
import { logger } from 'src/lib/logger' // Redwood's built-in logger

// Initialize Infobip Client
// We instantiate it outside the function to potentially reuse the client instance
let infobipClient

const getInfobipClient = () => {
  if (!infobipClient) {
    if (!process.env.INFOBIP_API_KEY || !process.env.INFOBIP_BASE_URL) {
      logger.error(
        'Infobip API Key or Base URL not configured in environment variables.'
      )
      throw new Error(
        'Infobip configuration is missing. Check server logs.'
      )
    }

    infobipClient = new Infobip({
      baseUrl: process.env.INFOBIP_BASE_URL,
      apiKey: process.env.INFOBIP_API_KEY,
      authType: AuthType.ApiKey,
    })
    logger.info('Infobip client initialized.')
  }
  return infobipClient
}

/**
 * Sends an SMS message using the Infobip API.
 *
 * @param {object} input - The input object.
 * @param {string} input.to - The recipient's phone number in international format (e.g., 447123456789).
 * @param {string} input.text - The content of the SMS message.
 * @returns {Promise<object>} - The response object from the Infobip API.
 * @throws {Error} - Throws an error if sending fails or configuration is missing.
 */
export const sendSms = async ({ to, text }) => {
  logger.info(`Attempting to send SMS to: ${to}`)

  const client = getInfobipClient() // Get or initialize the client

  if (!process.env.INFOBIP_SENDER_ID) {
    logger.error('Infobip Sender ID not configured in environment variables.')
    throw new Error('Infobip Sender ID configuration is missing.')
  }

  // Basic validation
  if (!to || !text) {
    logger.error('Missing recipient phone number or message text.')
    throw new Error('Recipient phone number (to) and message (text) are required.')
  }

  // Construct the message payload according to Infobip SDK requirements
  const payload = {
    messages: [
      {
        destinations: [{ to: String(to) }], // Ensure 'to' is a string
        from: process.env.INFOBIP_SENDER_ID, // Use sender from env vars
        text: String(text), // Ensure 'text' is a string
      },
    ],
  }

  try {
    const response = await client.channels.sms.send(payload)
    logger.info(
      { infobipResponse: response.data }, // Log the actual response data
      `SMS sent successfully to ${to}. Bulk ID: ${response.data.bulkId}`
    )
    // Return the relevant part of the response
    // You might want to adapt this based on what your frontend needs
    return {
      success: true,
      bulkId: response.data.bulkId,
      messages: response.data.messages,
    }
  } catch (error) {
    logger.error(
      { error: error.response?.data || error.message, payload }, // Log Infobip error details if available
      `Failed to send SMS to ${to}`
    )

    // Re-throw a more generic error or handle specific Infobip errors
    throw new Error(`Failed to send SMS. Error: ${error.message}`)
  }
}

Code Explanation:

1. Import Dependencies: We import Infobip and AuthType from the SDK, and Redwood's logger.
2. Initialize Client (getInfobipClient):
   • We use a function to initialize the Infobip client lazily (only when first needed).
   • It checks if INFOBIP_API_KEY and INFOBIP_BASE_URL are present in process.env. RedwoodJS automatically loads variables from .env into process.env.
   • If credentials are missing, it logs an error and throws, preventing further execution.
   • It creates a new Infobip instance using the ApiKey authentication method.
3. sendSms Function:
   • This async function takes an object with to and text properties.
   • It calls getInfobipClient() to ensure the client is ready.
   • It checks for the INFOBIP_SENDER_ID.
   • It performs basic validation to ensure to and text are provided.
   • It constructs the payload exactly as required by the infobipClient.channels.sms.send method, referencing the environment variable for the from field. We ensure to and text are strings.
   • It calls client.channels.sms.send(payload) inside a try...catch block.
   • Success: Logs a success message including the bulkId returned by Infobip and returns a structured success object.
   • Error: Logs a detailed error message (including the Infobip API error response if available) and throws a new error to be caught by the caller (our API function).

4. Building the API Layer (RedwoodJS Function)

To make our sendSms service accessible from the outside (e.g., from our web frontend or other applications), we need to expose it via a RedwoodJS serverless function.

1. Generate the Function:

Use the RedwoodJS CLI:

yarn rw g function sendSms --no-auth

• We name the function sendSms.
• The --no-auth flag skips adding boilerplate for authentication, as we're keeping this example simple. In a real application, you would secure this endpoint.

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

2. Implement the Function Handler:

Open api/src/functions/sendSms.js and replace its contents with the following:

// api/src/functions/sendSms.js
import { logger } from 'src/lib/logger'
import { sendSms as sendSmsService } from 'src/services/sms/sms' // Import our service function

/**
 * The handler function is your serverless function's execution entry point.
 * It receives an ""event"" object containing details about the incoming request,
 * and a ""context"" object. The handler executes and returns the response.
 *
 * Important: Never expose sensitive data or services directly publicly.
 * Always add appropriate authentication and authorization checks.
 *
 * @param {object} event - The API Gateway event. Includes body, headers, etc.
 * @param {object} context - Contains information about the invocation, function, and execution environment.
 */
export const handler = async (event, context) => {
  logger.info('Received request to /api/sendSms function')

  // Basic security check: Ensure it's a POST request
  if (event.httpMethod !== 'POST') {
    logger.warn('Received non-POST request to sendSms function.')
    return {
      statusCode: 405, // Method Not Allowed
      headers: {
        'Content-Type': 'application/json',
        Allow: 'POST',
      },
      body: JSON.stringify({
        error: 'Method Not Allowed: Please use POST.',
      }),
    }
  }

  let requestBody

  try {
    requestBody = JSON.parse(event.body)
  } catch (error) {
    logger.error({ error }, 'Failed to parse request body JSON.')
    return {
      statusCode: 400, // Bad Request
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ error: 'Invalid JSON in request body.' }),
    }
  }

  // Extract data from the parsed body
  const { to, text } = requestBody

  // Basic input validation
  if (!to || typeof to !== 'string' || !text || typeof text !== 'string') {
    logger.error('Invalid input: Missing or invalid \""to\"" or \""text\"" fields.')
    return {
      statusCode: 400, // Bad Request
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        error:
          'Invalid input: \""to\"" (string) and \""text\"" (string) are required in the JSON body.',
      }),
    }
  }

  try {
    // Call the service function
    const result = await sendSmsService({ to, text })

    logger.info('SMS service executed successfully.')
    return {
      statusCode: 200,
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(result), // Send back the result from the service
    }
  } catch (error) {
    // Errors thrown by the service are caught here
    logger.error({ error }, 'Error executing sendSms service.')
    return {
      statusCode: 500, // Internal Server Error
      headers: { 'Content-Type': 'application/json' },
      // Avoid leaking detailed internal errors to the client
      body: JSON.stringify({
        error: 'An internal error occurred while trying to send the SMS.',
        // Optionally include a correlation ID here for support
      }),
    }
  }
}

Code Explanation:

1. Import Service: Imports the sendSms function (renamed locally to sendSmsService to avoid naming collision) from our service file.
2. Handler Function: This is the standard structure for AWS Lambda handlers (which RedwoodJS functions often deploy to).
3. Method Check: Ensures only POST requests are accepted.
4. Parse Body: Safely parses the JSON body of the incoming request. Handles potential parsing errors.
5. Input Validation: Extracts to and text from the parsed body and performs basic validation (presence and type). Returns a 400 Bad Request if validation fails. Note the escaped quotes (\"") around to and text in the error message string.
6. Call Service: Calls sendSmsService({ to, text }) within a try...catch block.
7. Success Response: If the service call succeeds, returns a 200 OK status with the result from the service stringified in the body.
8. Error Response: If the service call throws an error, it's caught here. It logs the internal error but returns a generic 500 Internal Server Error to the client, preventing potential information leakage.

5. Integrating with Infobip (Configuration Details)

We already added the environment variables, but let's clarify where to find these values.

1. Obtain Infobip API Key:

• Log in to your Infobip account.
• Navigate to the Developers section in the sidebar menu.
• Go to API Keys.
• Click Create API Key.
• Give your key a descriptive name (e.g., redwood-app-key).
• Ensure the key has the necessary permissions, primarily SMS > Send messages. You might restrict it further based on the principle of least privilege.
• Copy the generated API key immediately and store it securely (like in your .env file). You won't be able to see it again.

2. Obtain Infobip Base URL:

• Still in the Infobip portal, navigate to the Developers section.
• Go to API Reference or check the main Home / Dashboard area.
• Your personalized Base URL will be displayed prominently, usually in code examples or a dedicated section. It looks something like xyzabc.api.infobip.com. Copy this value.

3. Configure Sender ID:

• In the Infobip portal, navigate to Channels and Numbers -> Numbers (or similar, depending on portal layout changes).
• Here you can request or manage your sender IDs (phone numbers or alphanumeric senders).
• Make sure the sender ID you put in INFOBIP_SENDER_ID in your .env file is registered and approved in your Infobip account. Alphanumeric sender IDs often require registration, especially in certain countries. Free trial accounts might be restricted to using a test sender like ServiceSMS or only the number used for verification.

4. Secure Storage (.env):

• As mentioned, store these values only in your .env file.
• Crucially: Ensure .env is listed in your project's .gitignore file to prevent accidentally committing secrets to version control. RedwoodJS typically includes this by default.

6. Error Handling and Logging

We've already implemented basic error handling and logging:

• Service Level (api/src/services/sms/sms.js):
  • Checks for missing configuration (API_KEY, BASE_URL, SENDER_ID) and throws errors.
  • Wraps the client.channels.sms.send call in try...catch.
  • Logs detailed errors using logger.error, including the error response from Infobip (error.response?.data) if available.
  • Throws errors upwards to the function layer.
• Function Level (api/src/functions/sendSms.js):
  • Checks HTTP method and handles invalid methods (405 Method Not Allowed).
  • Safely parses JSON body and handles parsing errors (400 Bad Request).
  • Performs input validation (400 Bad Request).
  • Catches errors thrown by the service.
  • Logs internal errors using logger.error.
  • Returns generic 500 Internal Server Error responses to the client to avoid leaking details.

Testing Error Scenarios:

• Missing Credentials: Temporarily remove or comment out INFOBIP_API_KEY in .env and restart the dev server (yarn rw dev). Calling the API should result in a 500 error, and the server logs should show the ""Infobip configuration is missing"" message.
• Invalid Credentials: Put an incorrect value in INFOBIP_API_KEY. The API call should fail, likely resulting in a 500 error from our function, and the logs should show the error details from the Infobip SDK/API (e.g., authentication failure).
• Invalid Input: Send a POST request without a to or text field in the JSON body, or with incorrect types. This should result in a 400 Bad Request.
• Invalid Phone Number: Send a request with an incorrectly formatted phone number in the to field. Infobip's API should reject it. Our function will return a 500, and the logs should contain the specific error from Infobip.

Log Analysis:

When troubleshooting, check the output of the RedwoodJS development server (yarn rw dev) or your production logging system. Look for messages tagged with ERROR from api/src/services/sms/sms.js or api/src/functions/sendSms.js. The logged error objects often contain specific details from Infobip that pinpoint the problem (e.g., RECIPIENT_INVALID, EC_ABSENT_SUBSCRIBER, AUTHENTICATION_FAILED).

7. Security Considerations

While this is a basic guide, security is paramount:

1. API Key Security: Never commit your INFOBIP_API_KEY or other secrets to version control. Use .env files and ensure .env is in .gitignore. Use secure environment variable management in your deployment environment.
2. Endpoint Authentication/Authorization: The generated /api/sendSms function is currently public. In a real application, you must protect this endpoint. Use RedwoodJS's built-in authentication (yarn rw setup auth ...) or other mechanisms (e.g., API gateway keys, IP whitelisting) to ensure only authorized clients can trigger SMS sending. After setting up authentication (e.g., via yarn rw setup auth dbAuth), you can typically protect the function by importing requireAuth from src/lib/auth and calling it at the beginning of your handler: import { requireAuth } from 'src/lib/auth'; export const handler = async (event, context) => { requireAuth(); /* rest of the handler logic */ ... }; Consult the RedwoodJS authentication documentation for specifics based on your chosen provider.
3. Input Validation: We implemented basic validation (presence and type checking). Robust validation is critical.
   • Sanitize the text input to prevent potential injection attacks if the content is dynamic or user-provided (though less common for SMS APIs).
   • Validate the to phone number format more strictly, potentially using a library, to ensure it conforms to E.164 international format before sending it to Infobip.
4. Rate Limiting: To prevent abuse (accidental or malicious) and manage costs, implement rate limiting on your /api/sendSms endpoint. This can be done at the API gateway level (e.g., AWS API Gateway, Netlify) or within the function itself using libraries like rate-limiter-flexible.
5. Sender ID: Ensure your INFOBIP_SENDER_ID is securely configured and not easily changeable by unauthorized users.

8. Testing the Implementation

Now, let's test our API endpoint.

1. Start the Development Server:

Run the following command in your project root:

yarn rw dev

This starts both the web and api development servers. Look for the API server URL, usually http://localhost:8911. Our function will be available at http://localhost:8911/sendSms.

2. Send a Test Request (using curl):

Open a new terminal window (leave the dev server running). Replace YOUR_PHONE_NUMBER with a valid phone number (in international format, e.g., 15551234567) that you can receive SMS on. If using a free trial Infobip account, this must be the number you verified during signup.

curl -X POST http://localhost:8911/sendSms \
  -H ""Content-Type: application/json"" \
  -d '{
    ""to"": ""YOUR_PHONE_NUMBER"",
    ""text"": ""Hello from RedwoodJS and Infobip! This is a test.""
  }'

3. Verify the Response:

• Success: If successful, you should receive a 200 OK response similar to this in your curl terminal:

  jsonCopy

  {
    ""success"": true,
    ""bulkId"": ""some-unique-bulk-id"",
    ""messages"": [
      {
        ""to"": ""YOUR_PHONE_NUMBER"",
        ""status"": {
          ""groupId"": 1,
          ""groupName"": ""PENDING"",
          ""id"": 26,
          ""name"": ""PENDING_ACCEPTED"",
          ""description"": ""Message sent to next instance""
        },
        ""messageId"": ""some-unique-message-id""
        // Potentially other fields like smsCount depending on API version/response
      }
    ]
  }

  You should also receive the SMS on the destination phone shortly. Check the terminal running yarn rw dev for success logs.

• Failure: If something goes wrong (e.g., invalid API key, invalid phone number format, missing input), you'll likely receive a 4xx or 500 status code with a JSON error body:

  jsonCopy

  // Example: 400 Bad Request (invalid input)
  {
    ""error"": ""Invalid input: \""to\"" (string) and \""text\"" (string) are required in the JSON body.""
  }

  jsonCopy

  // Example: 500 Internal Server Error (e.g., bad API key)
  {
    ""error"": ""An internal error occurred while trying to send the SMS.""
  }

  Check the terminal running yarn rw dev for detailed error logs to diagnose the issue.

9. Troubleshooting and Caveats

• Authentication Failed: Check your INFOBIP_API_KEY and INFOBIP_BASE_URL in .env and ensure the .env file is being loaded correctly (restart yarn rw dev after changes). Verify the key has sms:message:send permissions in the Infobip portal.
• Invalid Destination Address: Ensure the to number is in the full international E.164 format (e.g., country code + number like 447123456789 for the UK or 14155552671 for the US). Remove any leading +, spaces, or dashes if curl or your client adds them incorrectly before JSON stringification.
• Unknown Sender ID / Sender Not Registered: Your INFOBIP_SENDER_ID must be approved and configured in your Infobip account for the destination country. Check Channels and Numbers in the Infobip portal. Free trial accounts often have restrictions.
• Free Trial Limitations: Infobip free trial accounts can typically only send SMS to the phone number used during registration and verification. Sending to other numbers will fail.
• Rate Limits: If sending many messages quickly, you might hit Infobip's API rate limits. The SDK might throw an error indicating this (e.g., 429 Too Many Requests). Implement delays or contact Infobip for higher limits if needed.
• Character Limits & Encoding: Standard SMS messages have character limits (160 for GSM-7 encoding, fewer for Unicode). Longer messages are split into multiple parts, potentially incurring higher costs. The basic sending method used here doesn't explicitly handle encoding or splitting previews – use Infobip's preview endpoint or more advanced features if needed.
• Delivery Reports: This guide only covers sending. To confirm actual delivery to the handset, you need to implement handling for Delivery Reports, either by polling Infobip's reports endpoint (/sms/3/reports using the messageId) or setting up a webhook (notifyUrl in the Infobip request) to receive status updates pushed from Infobip. This is a crucial next step for production systems.

10. Deployment

Deploying a RedwoodJS app involves deploying the frontend (web side) and backend (api side).

• Environment Variables: The most critical part for this integration is ensuring your INFOBIP_API_KEY, INFOBIP_BASE_URL, and INFOBIP_SENDER_ID environment variables are correctly configured in your deployment provider's settings (e.g., Netlify, Vercel, Render, AWS). Do not commit your .env file. Use the provider's UI or CLI to set these secure environment variables for your deployed functions.
• Build Command: yarn rw deploy <provider> (e.g., yarn rw deploy netlify) will typically build both sides and configure them correctly.
• Provider Specifics: Consult the RedwoodJS deployment documentation for your chosen provider (Netlify, Vercel, etc.) for detailed instructions.

11. Verification and Testing Checklist

Before considering this production-ready:

• Project Setup: RedwoodJS project created, Infobip SDK installed.
• Configuration: .env file created, added to .gitignore, populated with correct INFOBIP_API_KEY, INFOBIP_BASE_URL, INFOBIP_SENDER_ID.
• Service Logic: api/src/services/sms/sms.js implemented with SDK initialization, payload construction, and try...catch error handling. Logging added.
• API Function: api/src/functions/sendSms.js created, handles POST requests, parses body, validates input, calls service, returns appropriate JSON responses (200, 4xx, 500). Logging added.
• Basic Send Test: Successfully sent an SMS to a valid, verified number using curl against the local dev server (yarn rw dev). Received 200 OK response and the SMS message.
• Error Handling Tests:
  • Tested with invalid API key (expect 500, check logs).
  • Tested with invalid to number format (expect 500, check logs for Infobip error).
  • Tested with missing to/text in request body (expect 400).
  • Tested with non-POST request (expect 405).
• Security: Endpoint (/api/sendSms) secured with appropriate authentication/authorization (outside the scope of this basic guide, but essential for production).
• Deployment: Successfully deployed to a hosting provider. Environment variables configured correctly in the provider's settings. Tested sending an SMS from the deployed endpoint.
• (Recommended Next Step) Delivery Reports: Implement logic to track final delivery status via webhooks or polling.
• (Recommended Next Step) Unit/Integration Tests: Write tests for the service (sms.test.js) and potentially integration tests for the function using RedwoodJS testing utilities.

Conclusion

You have successfully integrated Infobip's basic SMS sending capabilities into your RedwoodJS application. You created a reusable service, exposed it via a serverless API function, handled configuration securely using environment variables, and implemented basic error handling and logging.

This provides a solid foundation for leveraging SMS communication. For production environments, remember to enhance security by adding authentication to the API endpoint, implement robust input validation, and consider handling delivery reports for reliable status tracking.

Further Exploration:

• Implement Delivery Report Webhooks from Infobip.
• Explore sending fully featured SMS messages with options like scheduling, validity periods, etc.
• Add unit tests for your sms service.
• Integrate this API call into your RedwoodJS web frontend using Cells or standard fetch requests.