Next.js

Welcome to the ReSMS Next.js integration guide.

This guide explains how you can quickly and securely send SMS messages using the ReSMS API in your Next.js applications.

Features

Send SMS: Send text messages to phone numbers.
Send OTP: Generate and send one-time passwords (OTP) for user verification.
Verify OTP: Validate OTP codes entered by users.

Installation

First, install our official ReSMS SDK:


npm install @resms/sdk
# or
yarn add @resms/sdk
# or
bun add @resms/sdk

Setup

You need to get an API key on ReSMS Dashboard . Then import the package and create a new instance of the ReSMS class with your API key.


import { NextRequest, NextResponse } from "next/server";
import { ReSMS } from "@resms/sdk";
 
const resms = new ReSMS("re_12345"); // Replace with your actual API key

Send SMS

Here’s a minimal example to send an SMS in an API route:


import { NextRequest, NextResponse } from "next/server";
import { ReSMS } from "@resms/sdk";
 
const resms = new ReSMS("re_12345");
 
export async function POST(req: NextRequest) {
  const { to, message } = await req.json();
 
  try {
    const response = await resms.sms.send({
      to: to || "+33612345678",
      message: message || "Welcome to ReSMS!"
    });
    return NextResponse.json({ success: true, data: response.data });
  } catch (error) {
    return NextResponse.json({ error: error.message }, { status: 400 });
  }
}

Parameters

Possible parameters for sending an SMS:

Field	Type	Required	Description
`to`	String	✅	The phone number of the recipient, in international format (E.164)
`message`	String	✅	The SMS content (160 characters max)
`senderId`	String	❌	The alphanumeric sender name displayed

Here is the parameter type in TypeScript:


export type SendSmsOptions = {
  to: string;
  message: string;
  senderId: string | undefined;
};

Response

Success Response

The sms.send() method returns a promise that resolves when the SMS has been successfully sent. The response type is:


export type SendSmsResponse = {
  data: {
    messageId: string;
  };
};

Error Response

In case of an error, the response type is:


export type ErrorResponse = {
  message: string,
  name: string,
};

The sms.send() method may return the following errors:

Name	Message
COUNTRY_DETECTION_FAILED	Unable to detect country code from phone number
PHONE_NUMBER_PARSING_FAILED	Invalid phone number
INSUFFICIENT_SMS_QUOTA	Failed to update message status
MESSAGE_STATUS_UPDATE_FAILED	Failed to update message status

Send OTP

Here is a minimal example to send an OTP verification code to a phone number:


import { NextRequest, NextResponse } from "next/server";
import { ReSMS } from "@resms/sdk";
 
const resms = new ReSMS("re_12345");
 
export async function POST(req: NextRequest) {
  const { to, message } = await req.json();
 
  try {
    const response = await resms.otp.send({
      to: to || "+33612345678",
      message: message || "Your OTP code is {CODE}"
    });
    return NextResponse.json({ success: true, data: response.data });
  } catch (error) {
    return NextResponse.json({ error: error.message }, { status: 400 });
  }
}

Parameters

Possible parameters for sending an OTP:

Field	Type	Required	Description	Default Value
`to`	String	✅	The phone number of the recipient, in international format (E.164)
`message`	String	✅	The SMS content (160 characters max). It must contain `{CODE}`.
`senderId`	String	❌	The alphanumeric sender name displayed
`codeType`	OtpCode (`"numeric"`\| `"alpha"`)	❌	The type of OTP code to generate	`"numeric"`
`codeLength`	number	❌	The length of the OTP code	6
`validityMinutes`	number	❌	The validity period of the OTP in minutes.	5

Response

Success Response

The otp.send() method returns a promise that resolves when the OTP has been successfully sent. The response type is:


export type SendOtpResponse = {
  data: {
    phoneNumber: string;
    expiresAt: string;
  };
};

Error Response

In case of an error, the response type is:


export type ErrorResponse = {
  message: string;
  name: string;
};

The otp.send() method may return the following errors:

Code	HTTP Status	Message
`INVALID_MESSAGE_TEMPLATE`	400	Message template must contain `{CODE}` placeholder
`INVALID_CODE_LENGTH`	400	Code length must be between 4 and 16
`INVALID_VALIDITY_DURATION`	400	Validity duration must be between 1 minute and 1440 minutes (24 hours)
`TOO_MANY_OTP_REQUESTS`	429	Too many OTP requests for this phone number

Verify OTP

To verify an OTP code entered by the user:


import { NextRequest, NextResponse } from "next/server";
import { ReSMS } from "@resms/sdk";
 
const resms = new ReSMS("re_12345");
 
export async function POST(req: NextRequest) {
  const { to, code } = await req.json();
 
  try {
    const response = await resms.otp.verify({
      to: to || "+33612345678",
      code: code || "123456"
    });
    return NextResponse.json({
      success: true,
      verified: true,
      data: response.data
    });
  } catch (error) {
    return NextResponse.json({ error: error.message }, { status: 400 });
  }
}

Parameters

Possible parameters for verifying an OTP:

Field	Type	Required	Description
`to`	String	✅	The phone number the OTP was sent to, in international format (E.164)
`code`	String	✅	The verification code entered by the user

Response

Success Response

The otp.verify() method returns a promise that resolves with the verification data. The response type is:


export type VerifyOtpResponse = {
  data: {
    otpId: string;
    phoneNumber: string;
    verifiedAt: string;
  };
};

Error Response

In case of an error, the response type is:


export type ErrorResponse = {
  message: string;
  name: string;
};

The otp.verify() method may return the following errors:

Code	HTTP Status	Message
`OTP_NOT_FOUND`	404	OTP not found
`OTP_INVALID`	400	OTP is invalid
`OTP_EXPIRED`	400	OTP has expired
`OTP_ALREADY_VERIFIED`	400	OTP already verified
`INVALID_OTP_CODE`	400	Invalid OTP code

Have feedback, found a bug, or want to suggest a feature?

Open an issue on GitHub
Or chat with us directly on Discord — we’re happy to help!