Implement Phone Authentication and Integrate Twilio SMS

In this tutorial, you will learn how to implement phone number authentication in your Medusa application.

When you install a Medusa application, you get a fully-fledged commerce platform with a Framework for customization. The Medusa application's commerce features are built around Commerce Modules, which are available out-of-the-box. These features include authentication with custom providers and for custom user or actor types.

In this tutorial, you'll learn how to implement a custom authentication provider that allows customers to log in with their phone number. You'll also integrate Twilio to send SMS messages to those customers with the one-time password (OTP) for authentication.

Summary#

By following this tutorial, you will learn how to:

• Install and set up Medusa.
• Implement a custom phone authentication provider.
• Integrate Twilio to send OTPs by SMS.
• Customize the Next.js Starter Storefront to allow customers to log in with their phone numbers.

You can follow this tutorial whether you're new to Medusa or an advanced Medusa developer.

Step 1: Install a Medusa Application#

Start by installing the Medusa application on your machine with the following command:

Terminal
❯npx create-medusa-app@latest

You'll first be asked for the project's name. Then, when asked whether you want to install the Next.js Starter Storefront, choose Yes.

Afterward, the installation process will start, which will install the Medusa application in a directory with your project's name, and the Next.js Starter Storefront in a separate directory with the {project-name}-storefront name.

Once the installation finishes successfully, the Medusa Admin dashboard will open with a form to create a new user. Enter the user's credentials and submit the form. Afterward, you can log in with the new user and explore the dashboard.

Step 2: Implement Phone Authentication Module Provider#

In Medusa, you integrate custom authentication providers by creating an Authentication Module Provider. Then, you can use that provider to authenticate users using custom logic.

In this step, you'll create a Phone Authentication Module Provider that allows users to log in with their phone numbers and an OTP. Later, you'll integrate Twilio to send the OTPs to the users, and customize the storefront to allow customers to log in with their phone numbers.

Prerequisite: Install jsonwebtoken#

In the Phone Authentication Module Provider, you'll use the jsonwebtoken package to sign and verify the OTPs.

To install the package, run the following command in the Medusa application directory:

npm
yarn
pnpm

a. Create Module Directory#

Modules are created under the src/modules directory. So, start by creating the directory src/modules/phone-auth.

b. Create Auth Module Provider Service#

A module has a service that contains its logic. For Authentication Module Providers, the service implements the logic to authenticate users.

To create the service of the Phone Authentication Module Provider, create the file src/modules/phone-auth/service.ts with the following content:

src/modules/phone-auth/service.ts
1import { 2  AbstractAuthModuleProvider, 3  AbstractEventBusModuleService, 4} from "@medusajs/framework/utils"5import { 6  Logger, 7} from "@medusajs/types"8
9type InjectedDependencies = {10  logger: Logger11  event_bus: AbstractEventBusModuleService12}13
14type Options = {15  jwtSecret: string16}17
18class PhoneAuthService extends AbstractAuthModuleProvider {19  static DISPLAY_NAME = "Phone Auth"20  static identifier = "phone-auth"21  private options: Options22  private logger: Logger23  private event_bus: AbstractEventBusModuleService24
25  constructor(container: InjectedDependencies, options: Options) {26    // @ts-ignore27    super(...arguments)28
29    this.options = options30    this.logger = container.logger31    this.event_bus = container.event_bus32  }33}34
35export default PhoneAuthService

An Authentication Module Provider's service must extend the AbstractAuthModuleProvider class. You'll get a type error about implementing the abstract methods of that class, which you'll add in the next steps.

An Authentication Module Provider must also have the following static properties:

• identifier: A unique identifier for the provider.
• DISPLAY_NAME: A human-readable name for the provider. This name is used for display purposes.

A module provider's constructor receives two parameters:

• container: The module's container that contains Framework resources available to the module. You access the following resources:
  • logger: A Logger class to log debug messages.
  • event_bus: The Event Module's service to emit events.
• options: Options that are passed to the module provider when it's registered in Medusa's configurations. You define the following option:
  • jwtSecret: A secret used to sign and verify the OTPs.

In the constructor, you set the class's properties to the injected dependencies and options.

In the next sections, you'll implement the methods of the AbstractAuthModuleProvider class.

c. Implement validateOptions Method#

The validateOptions method is used to validate the options passed to the module provider. If the method throws an error, the Medusa application won't start.

So, add the validateOptions method to the PhoneAuthService class:

src/modules/phone-auth/service.ts
1// other imports...2import { 3  MedusaError,4} from "@medusajs/framework/utils"5
6class PhoneAuthService extends AbstractAuthModuleProvider {7  // ...8  static validateOptions(options: Record<any, any>): void | never {9    if (!options.jwtSecret) {10      throw new MedusaError(11        MedusaError.Types.INVALID_DATA,12        "JWT secret is required"13      )14    }15  }16}

The validateOptions method receives the options passed to the module provider as a parameter.

In the method, you throw an error if the jwtSecret option is not set.

d. Implement register Method#

When a customer (or another actor type) registers in your application, they must also have an auth identity that allows them to login.

The register method of an auth provider uses custom logic to create the auth identity for the actor type (such as customer). In the method, you can perform custom validation and specify the custom authentication details to store for the user's auth identity.

Medusa uses the register method to create an auth identity that will be associated with the customer when they register. You can learn more in the Authentication Flows documentation.

So, add the register method to the PhoneAuthService class:

src/modules/phone-auth/service.ts
1// other imports...2import { 3  AuthenticationInput, 4  AuthIdentityProviderService, 5  AuthenticationResponse, 6} from "@medusajs/types"7
8class PhoneAuthService extends AbstractAuthModuleProvider {9  // ...10  async register(11    data: AuthenticationInput,12    authIdentityProviderService: AuthIdentityProviderService13  ): Promise<AuthenticationResponse> {14    const { phone } = data.body || {}15
16    if (!phone) {17      return {18        success: false,19        error: "Phone number is required",20      }21    }22
23    try {24      await authIdentityProviderService.retrieve({25        entity_id: phone,26      })27
28      return {29        success: false,30        error: "User with phone number already exists",31      }32    } catch (error) {33      const user = await authIdentityProviderService.create({34        entity_id: phone,35      })36
37      return {38        success: true,39        authIdentity: user,40      }41    }42  }43}

Parameters

The register method receives an object parameter with the following properties:

• data: An object containing properties like body that holds request-body parameters. Clients will pass relevant authentication data, such as the user's phone number, in the request body.
• authIdentityProviderService: A service injected by the Auth Module that allows you to manage auth identities.

Method Logic

In the method, you extract the phone property from the request body, and return an error if it's not provided. You also return an error if another user is using the same phone number.

Otherwise, you create a new auth identity for the user. You set the phone number as the entity_id of the auth identity, which is a unique identifier.

Return Value

Finally, you return an object with the following properties:

• success: A boolean indicating whether the registration was successful.
• authIdentity: The created auth identity of the user. This property is only set if the registration was successful.
• error: An error message if the registration failed.

e. Implement authenticate Method#

When a customer (or another actor type) logs in, the authenticate method of an auth provider is called. This method uses custom logic to authenticate the user.

Authentication providers may implement one of the following flows:

• Direct authentication, where the user is authenticated using this method only. For example, authenticating with an email and password.
• Authentication with callback verification, where the user is authenticated using this method and then a callback is used to verify additional information.

For the Phone Authentication Module Provider, you'll implement the second flow. The user will first be authenticated using the authenticate method to make sure the user exists and generate an OTP. Then, they need to supply the OTP to verify their identity.

So, add the authenticate method to the PhoneAuthService class:

src/modules/phone-auth/service.ts
1// other imports...2import { 3  AuthIdentityDTO,4} from "@medusajs/types"5import jwt from "jsonwebtoken"6
7class PhoneAuthService extends AbstractAuthModuleProvider {8  // ...9  async authenticate(10    data: AuthenticationInput,11    authIdentityProviderService: AuthIdentityProviderService12  ): Promise<AuthenticationResponse> {13    const { phone } = data.body || {}14
15    if (!phone) {16      return {17        success: false,18        error: "Phone number is required",19      }20    }21
22    try {23      await authIdentityProviderService.retrieve({24        entity_id: phone,25      })26    } catch (error) {27      return {28        success: false,29        error: "User with phone number does not exist",30      }31    }32
33    const { hashedOTP, otp } = await this.generateOTP()34
35    await authIdentityProviderService.update(phone, {36      provider_metadata: {37        otp: hashedOTP,38      },39    })40
41    await this.event_bus.emit({42      name: "phone-auth.otp.generated",43      data: {44        otp,45        phone,46      },47    }, {})48
49    return {50      success: true,51      location: "otp",52    }53  }54
55  async generateOTP(): Promise<{ hashedOTP: string, otp: string }> {56    // Generate a 6-digit OTP57    const otp = Math.floor(100000 + Math.random() * 900000).toString()58
59    // for debug60    this.logger.info(`Generated OTP: ${otp}`)61    62    const hashedOTP = jwt.sign({ otp }, this.options.jwtSecret, {63      expiresIn: "60s",64    })65    66    return { hashedOTP, otp }67  }68}

You add two methods: the authenticate method, and a helper generateOTP method.

authenticate Parameters

The authenticate method receives an object parameter with the following properties:

• data: An object containing properties like body that holds request-body parameters. Clients will pass relevant authentication data, such as the user's phone number, in the request body.
• authIdentityProviderService: A service injected by the Auth Module that allows you to manage auth identities.

authenticate Logic

In the method, you return an error if the phone property is not provided in the request body, or if a user with that phone number doesn't exist.

Next, you generate a 6-digit OTP using the generateOTP method. Notice that you currently log the OTP for debugging purposes. You can remove this line later once you integrate Twilio.

The OTP is hashed and stored in the provider_metadata property of the user's auth identity. The provider_metadata property is a JSON object that stores additional information about the auth identity.

Then, you emit an event with the generated OTP and the user's phone number. This allows you later to handle the event and send the OTP to the user using services like Twilio.

authenticate Return Value

Finally, you return an object with the following properties:

• success: A boolean indicating whether the authentication was successful.
• location: A string indicating a URL to perform additional actions in. In this case, you set the location to otp, indicating that the user should verify with the OTP.
• error: An error message if the authentication failed.

f. Implement validateCallback Method#

When an authentication provider requires a callback to verify the user, the Medusa application calls the validateCallback method.

You can use this method to verify the OTP that the user entered. If valid, you return the logged in user, and the Medusa application will return a JWT token that the user can use to authenticate in the application.

So, add the validateCallback method to the PhoneAuthService class:

src/modules/phone-auth/service.ts
1class PhoneAuthService extends AbstractAuthModuleProvider {2  // ...3  async validateCallback(4    data: AuthenticationInput,5    authIdentityProviderService: AuthIdentityProviderService6  ): Promise<AuthenticationResponse> {7    const { phone, otp } = data.query || {}8
9    if (!phone || !otp) {10      return {11        success: false,12        error: "Phone number and OTP are required",13      }14    }15
16    const user = await authIdentityProviderService.retrieve({17      entity_id: phone,18    })19
20    if (!user) {21      return {22        success: false,23        error: "User with phone number does not exist",24      }25    }26    27    // verify that OTP is correct28    const userProvider = user.provider_identities?.find((provider) => provider.provider === this.identifier)29    if (!userProvider || !userProvider.provider_metadata?.otp) {30      return {31        success: false,32        error: "User with phone number does not have a phone auth provider",33      }34    }35    36    try {37      const decodedOTP = jwt.verify(38        userProvider.provider_metadata.otp as string, 39        this.options.jwtSecret40      ) as { otp: string }41  42      if (decodedOTP.otp !== otp) {43        throw new Error("Invalid OTP")44      }45    } catch (error) {46      return {47        success: false,48        error: error.message || "Invalid OTP",49      }50    }51    52    const updatedUser = await authIdentityProviderService.update(phone, {53      provider_metadata: {54        otp: null,55      },56    })57
58    return {59      success: true,60      authIdentity: updatedUser,61    }62  }63}

Parameters

The validateCallback method receives an object parameter with the following properties:

• data: An object containing properties like query that holds query parameters. Clients will pass relevant authentication data, such as the user's phone number and OTP, in the request query.
• authIdentityProviderService: A service injected by the Auth Module that allows you to manage auth identities.

Method Logic

In the method, you return an error if the phone and otp aren't provided in the request query, or if a user with that phone number doesn't exist.

Next, you verify that the OTP provided by the user is correct. You retrieve the hashed OTP from the provider_metadata property of the user's auth identity. If the OTP is not valid, you return an error.

After that, you update the user's auth identity to remove the OTP from the provider_metadata property.

Return Value

Finally, you return an object with the following properties:

• success: A boolean indicating whether the authentication was successful.
• authIdentity: The user's auth identity. This property is only set if the authentication was successful.
• error: An error message if the authentication failed.

g. Export Module Definition#

You've now finished implementing the necessary methods for the Phone Authentication Module Provider.

The final piece to a module is its definition, which you export in an index.ts file at the module's root directory. This definition tells Medusa the name of the module, its service, and optionally its loaders.

To create the module's definition, create the file src/modules/phone-auth/index.ts with the following content:

src/modules/phone-auth/index.ts
1import PhoneAuthService from "./service"2import { 3  ModuleProvider, 4  Modules,5} from "@medusajs/framework/utils"6
7export default ModuleProvider(Modules.AUTH, {8  services: [PhoneAuthService],9})

You use ModuleProvider from the Modules SDK to create the module provider's definition. It accepts two parameters:

1. The name of the module that this provider belongs to, which is Modules.AUTH in this case.
2. An object with a required property services indicating the module provider's services. Each of these services will be registered as authentication providers in Medusa.

h. Add Module Provider to Medusa's Configurations#

Once you finish building the module, add it to Medusa's configurations to start using it.

In medusa-config.ts, add a modules property:

medusa-config.ts
1// other imports...2import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"3
4module.exports = defineConfig({5  // ...6  modules: [7    {8      resolve: "@medusajs/medusa/auth",9      dependencies: [10        Modules.CACHE, 11        ContainerRegistrationKeys.LOGGER, 12        Modules.EVENT_BUS,13      ],14      options: {15        providers: [16          // default provider17          {18            resolve: "@medusajs/medusa/auth-emailpass",19            id: "emailpass",20          },21          {22            resolve: "./src/modules/phone-auth",23            id: "phone-auth",24            options: {25              jwtSecret: process.env.PHONE_AUTH_JWT_SECRET || "supersecret",26            },27          },28        ],29      },30    },31  ],32})

To pass an Auth Module Provider to the Auth Module, you add the modules property to the Medusa configuration and pass the Auth Module in its value.

The Auth Module accepts a dependencies option, allowing you to inject dependencies into the containers of the module and its providers. The Auth Module requires passing the Cache Module and Logger, but you also inject the event_bus dependency to use the Event Module's service in the Phone Authentication Module Provider.

The Auth Module also accepts a providers option, which is an array of Auth Module Providers to register. You register the emailpass provider, which is registered by default when you don't provide any other providers.

To register the Phone Authentication Module Provider, you add an object to the providers array with the following properties:

• resolve: The NPM package or path to the module provider. In this case, it's the path to the src/modules/phone-auth directory.
• id: The ID of the module provider. The auth provider is then registered with the ID au_{id}.
• options: The options to pass to the module provider. These are the options you defined in the Options interface of the module provider's service.

i. Enable Phone Authentication for Customers#

By default, customers and admin users can be authenticated using the emailpass provider. When you add a new provider, you need to specify which actor types can use it.

In medusa-config.ts, add to projectConfig.http a new authMethodsPerActor property:

medusa-config.ts
1module.exports = defineConfig({2  projectConfig: {3    // ...4    http: {5      // ...6      authMethodsPerActor: {7        user: ["emailpass"],8        customer: ["emailpass", "phone-auth"],9      },10    },11  },12  // ...13})

The authMethodsPerActor property is an object whose keys are actor types. The values are arrays of authentication method IDs that can be used for that actor type.

In this case, you enable the phone-auth provider for customers. You can also enable it for other actor types, such as admin users or vendors.

Test Out Phone Authentication#

In this section, you'll test out the Phone Authentication Module Provider using Medusa's API routes. You can, instead, test it out later using the Next.js Starter Storefront.

First, start the Medusa application with the following command:

npm
yarn
pnpm

Prerequisite: Retrieve Publishable API Key

Before you start testing the authentication provider using the API routes, you need to retrieve your application's publishable API key. This key is necessary to send requests to API routes starting with /store.

To retrieve the publishable API key:

1. Open the Medusa Admin dashboard at http://localhost:9000/admin and log in.
2. Go to Settings -> Publishable API Keys.
3. Click on the API key in the table.
4. In its details page, click on the API key to copy it.

a. Retrieve Registration Token

The first step is to retrieve a registration token for a new customer. This token will allow them to register in the application.

To retrieve the registration token, send a POST request to /auth/customer/phone-auth/register:

Code
1curl -X POST 'http://localhost:9000/auth/customer/phone-auth/register' \2--header 'Content-Type: application/json' \3--data '{4    "phone": "+19077890116"5}'

Make sure to replace the phone number with the one you want to use.

This will return a token in the response:

Example Response
1{2  "token": "123..."3}

b. Register Customer

Next, you'll register the customer using the Register Customer API route. You'll pass the registration token you received in the previous step in the header of this request.

So, send a POST request to /store/customers:

Code
1curl -X POST 'http://localhost:9000/store/customers' \2--header 'x-publishable-api-key: {publishable_api_key}' \3--header 'Content-Type: application/json' \4--header 'Authorization: Bearer {reg_token}' \5--data-raw '{6    "email": "+19077890116@gmail.com",7    "phone": "19077890116",8    "first_name": "John",9    "last_name": "Smith"10}'

Make sure to replace:

• {publishable_api_key} with the publishable API key you retrieved from the Medusa Admin dashboard.
• {reg_token} with the registration token you received in the previous step.
• The customer details in the request body with the ones you want to use. Use the same phone number you used in the previous step.
  • You pass the email because it's required by the Register Customer API route. You set it to the phone number with a gmail.com domain.

The request will return the created customer's details:

Example Response
1{2  "customer": {3    "id": "cus_01JVPESW5SM1MSVPNM2MSC0ZEC",4    "email": "+19077890116@gmail.com",5    "company_name": null,6    "first_name": "John",7    "last_name": "Smith",8    "phone": "19077890116",9    "metadata": null,10    "has_account": true,11    "deleted_at": null,12    "created_at": "2025-05-20T09:01:13.273Z",13    "updated_at": "2025-05-20T09:01:13.273Z",14    "addresses": []15  }16}

The customer can now authenticate using the phone number and OTP.

c. Authenticate Customer

Next, you'll authenticate the customer using the Authenticate Customer API route. This would send the customer an OTP to their phone number (which you'll implement in the next step).

So, send a POST request to /auth/customer/phone-auth:

Code
1curl -X POST 'http://localhost:9000/auth/customer/phone-auth' \2--header 'Content-Type: application/json' \3--data '{4    "phone": "+19077890116"5}'

Make sure to replace the phone number with the one you used to register the customer.

This will return a location in the response:

Example Response
1{2  "location": "otp"3}

Indicating that the user should verify their OTP.

d. Verify OTP

If you check the logs of the Medusa application, you'll see that the OTP was generated and logged:

Terminal
❯info:    Generated OTP: 576794

As mentioned before, this is only for debugging purposes. In the next step, you'll implement the logic to send the OTP to the user using Twilio.

So, to verify the OTP, you'll send a request to the Verify Callback API route:

Code
curl -X POST 'http://localhost:9000/auth/customer/phone-auth/callback?phone=%2B19077890116&otp=476588'

You pass the following query parameters:

• phone: The phone number of the customer. Make sure to use the same phone number you used to register the customer, and to encode it. For example, the + sign should be encoded as %2B.
• otp: The OTP that the customer received. Make sure to use the same OTP shown in the logs.

If the OTP is valid, you'll receive a JWT token in the response:

Example Response
1{2  "token": "123..."3}

You can use this token to authenticate the customer in the application. For example, you can use the token to retrieve the customer's details.

Step 3: Integrate Twilio SMS#

Similar to the Auth Module, the Notification Module allows registering custom providers to send notifications, such as SMS or email.

In this step, you'll create a Twilio Notification Module Provider, then use it to send the OTP to the customer.

a. Install Twilio SDK#

Before you start implementing the Twilio Notification Module Provider, install the Twilio SDK to interact with the Twilio API.

Run the following command in the Medusa application directory:

npm
yarn
pnpm

You'll use the Twilio SDK in the Notification Module Provider's service.

b. Create Module Directory#

Create the directory src/modules/twilio-sms to create the Twilio Notification Module Provider.

c. Create Notification Module Provider Service#

A Notification Module Provider has a service that contains the sending logic. The service must extend the AbstractNotificationProviderService class.

So, create the file src/modules/twilio-sms/service.ts with the following content:

src/modules/twilio-sms/service.ts
1import { 2  AbstractNotificationProviderService,3} from "@medusajs/framework/utils"4import { Twilio } from "twilio"5
6type InjectedDependencies = {}7
8type TwilioSmsServiceOptions = {9  accountSid: string10  authToken: string11  from: string12}13
14class TwilioSmsService extends AbstractNotificationProviderService {15  static readonly identifier = "twilio-sms"16  private readonly client: Twilio17  private readonly from: string18
19  constructor(container: InjectedDependencies, options: TwilioSmsServiceOptions) {20    super()21
22    this.client = new Twilio(options.accountSid, options.authToken)23    this.from = options.from24  }25}

You'll get a type error about implementing the abstract methods of the AbstractNotificationProviderService class, which you'll add in the next steps.

A Notification Module Provider must have an identifier static property, which is a unique identifier for the module. This identifier is used to register the module in the Medusa application.

A module provider's constructor receives two parameters:

• container: The module's container that contains Framework resources available to the module. You don't need to access any resources for this provider.
• options: Options that are passed to the module provider when it's registered in Medusa's configurations. You define the following option:
  • accountSid: The Twilio account SID.
  • authToken: The Twilio auth token.
  • from: The Twilio phone number to send the SMS from.

In the constructor, you set the class's properties to the injected dependencies and options.

In the next sections, you'll implement the methods of the AbstractNotificationProviderService class.

d. Implement validateOptions Method#

The validateOptions method is used to validate the options passed to the module provider. If the method throws an error, the Medusa application won't start.

So, add the validateOptions method to the TwilioSmsService class:

src/modules/twilio-sms/service.ts
1class TwilioSmsService extends AbstractNotificationProviderService {2  // ...3  static validateOptions(options: Record<any, any>): void | never {4    if (!options.accountSid) {5      throw new Error("Account SID is required")6    }7    if (!options.authToken) {8      throw new Error("Auth token is required")9    }10    if (!options.from) {11      throw new Error("From is required")12    }13  }14}

The validateOptions method receives the options passed to the module provider as a parameter.

In the method, you throw an error if any of the options are not set.

e. Implement send Method#

The only required method for a Notification Module Provider is the send method. When the Medusa application needs to send a notification using the provider's channel (such as SMS), it calls this method of the registered provider.

So, add the send method to the TwilioSmsService class:

src/modules/twilio-sms/service.ts
1// other imports...2import { 3  ProviderSendNotificationDTO, 4  ProviderSendNotificationResultsDTO,5} from "@medusajs/types"6
7class TwilioSmsService extends AbstractNotificationProviderService {8  // ...9  async send(10    notification: ProviderSendNotificationDTO11  ): Promise<ProviderSendNotificationResultsDTO> {12    const { to, content, template, data } = notification13    const contentText = content?.text || await this.getTemplateContent(14      template, data15    )16
17    const message = await this.client.messages.create({18      body: contentText,19      from: this.from,20      to,21    })22
23    return {24      id: message.sid,25    }26  }27
28  async getTemplateContent(29    template: string, 30    data?: Record<string, unknown> | null31  ): Promise<string> {32    switch (template) {33      case "otp-template":34        if (!data?.otp) {35          throw new Error("OTP is required for OTP template")36        }37
38        return `Your OTP is ${data.otp}`39      default:40        throw new Error(`Template ${template} not found`)41    }42  }43}

You implement the send method and a helper getTemplateContent method.

send Parameters

The send method receives an object parameter with the following properties:

• to: The phone number to send the SMS to.
• content: An object containing the content of the SMS. The text property is the text to send.
• template: The template to use for the SMS. This is used to retrieve the fallback content of the SMS if content.text is not provided.
• data: An object containing the data to use in the template. This is used to replace placeholders in the template with actual values.

send Method Logic

In the method, you set the SMS content either to the text property of the content object or to the template content. You define a getTemplateContent method that retrieves the content for a template.

Then, you use the messages.create method of the Twilio client to send the SMS. You pass the following parameters:

• body: The content of the SMS.
• from: The Twilio phone number to send the SMS from.
• to: The phone number to send the SMS to.

send Return Value

Finally, you return an object that has an id property with the ID of the sent SMS. This ID is stored in the notification record in the database.

f. Export Module Definition#

You've now finished implementing the necessary methods for the Twilio Notification Module Provider. You only need to export its definition.

To create the module's definition, create the file src/modules/twilio-sms/index.ts with the following content:

src/modules/twilio-sms/index.ts
1import { 2  ModuleProvider, 3  Modules,4} from "@medusajs/framework/utils"5import TwilioSMSNotificationService from "./service"6
7export default ModuleProvider(Modules.NOTIFICATION, {8  services: [TwilioSMSNotificationService],9})

You use ModuleProvider from the Modules SDK to create the module provider's definition passing it two parameters:

1. The name of the module that this provider belongs to, which is Modules.NOTIFICATION in this case.
2. An object with a required property services indicating the module provider's services. Each of these services will be registered as notification providers in Medusa.

g. Add Module Provider to Medusa's Configurations#

You'll now add the Twilio Notification Module Provider to Medusa's configurations to start using it.

In medusa-config.ts, add the following to the modules property:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  modules: [4    // ...5    {6      resolve: "@medusajs/medusa/notification",7      options: {8        providers: [9          // default provider10          {11            resolve: "@medusajs/medusa/notification-local",12            id: "local",13            options: {14              name: "Local Notification Provider",15              channels: ["feed"],16            },17          },18          {19            resolve: "./src/modules/twilio-sms",20            id: "twilio-sms",21            options: {22              channels: ["sms"],23              accountSid: process.env.TWILIO_ACCOUNT_SID,24              authToken: process.env.TWILIO_AUTH_TOKEN,25              from: process.env.TWILIO_FROM,26            },27          },28        ],29      },30    },31  ],32})

You pass the Notification Module in the modules property to register the Twilio Notification Module Provider.

The Notification Module accepts a providers option, which is an array of Notification Module Providers to register. You register the local provider, which is registered by default when you don't provide any other providers.

To register the Twilio Notification Module Provider, you add an object with the following properties:

• resolve: The path to the module provider.
• id: The ID of the module provider. The notification provider is then registered with the ID np_{identifier}_{id}.
• options: The options to pass to the module provider. These include the options you defined in the Options interface of the module provider's service.
  • channels: The channels that the notification provider supports. In this case, you set it to sms, which is the channel used to send SMS notifications.
  • accountSid: The Twilio account SID.
  • authToken: The Twilio auth token.
  • from: The Twilio phone number to send the SMS from.

h. Add Environment Variables#

To set the value of the Twilio options, add the following environment variables to your .env file:

.env
1TWILIO_ACCOUNT_SID=AC...2TWILIO_AUTH_TOKEN=05...3TWILIO_FROM=+1...

Where:

• TWILIO_ACCOUNT_SID: The Twilio account SID.
• TWILIO_AUTH_TOKEN: The Twilio auth token.
• TWILIO_FROM: The Twilio phone number to send the SMS from. Make sure to use the phone number you purchased from Twilio.

You can retrieve these information from the Twilio Console homepage.

i. Handle OTP Generated Event#

Now that you have integrated Twilio into Medusa, you can use it to send the OTP to the customer. To do that, you need to handle the phone-auth.otp.generated event that you emitted in the authenticate method of the Phone Authentication Module Provider.

You can listen to events in a subscriber. A subscriber is an asynchronous function that listens to events to perform actions when the event is emitted.

In this step, you'll create a subscriber that listens to the phone-auth.otp.generated event and sends an SMS to the customer with the OTP.

Subscribers are created in a TypeScript or JavaScript file under the src/subscribers directory. So, to create a subscriber, create the file src/subscribers/send-otp.ts with the following content:

src/subscribers/send-otp.ts
1import {2  SubscriberArgs,3  type SubscriberConfig,4} from "@medusajs/medusa"5import { Modules } from "@medusajs/framework/utils"6
7export default async function sendOtpHandler({8  event: { data: {9    phone,10    otp,11  } },12  container,13}: SubscriberArgs<{ phone: string, otp: string }>) {14  const notificationModuleService = container.resolve(15    Modules.NOTIFICATION16  )17
18  await notificationModuleService.createNotifications({19    to: phone,20    channel: "sms",21    template: "otp-template",22    data: {23      otp,24    },25  })26}27
28export const config: SubscriberConfig = {29  event: "phone-auth.otp.generated",30}

The subscriber file must export:

• An asynchronous subscriber function that's executed whenever the associated event is triggered.
• A configuration object with an event property whose value is the event the subscriber is listening to, which is phone-auth.otp.generated.

The subscriber function accepts an object with the following properties:

• event: An object with the event's data payload. In the authenticate method, you emitted the event with the following data:
  • phone: The phone number of the user.
  • otp: The OTP that was generated.
• container: The Medusa container, which you can use to resolve Framework and commerce resources.

In the subscriber function, you resolve the Notification Module's service from the Medusa container. Then, you use its createNotifications method to send the OTP to the user.

Under the hood, the Notification Module's service delegates the sending to the Notification Module Provider of the sms channel, which is the Twilio Notification Module Provider in this case.

The createNotifications method accepts an object with the following properties:

• to: The phone number to send the notification to. You use the phone number from the event's data payload.
• channel: The channel to use to send the notification, which is sms.
• template: The template to use for the notification content, which is otp-template.
• data: An object containing the data to use in the template. You pass the OTP to the template.

j. Test it Out#

To test out the Twilio Notification Module Provider, you can follow the steps in the Test Out Phone Authentication section.

After you authenticate the customer, the OTP will be sent to the customer's phone number using Twilio. Then, you can use the OTP to verify the authentication and receive a JWT token.

Alternatively, you can also test it out after customizing the Next.js Starter Storefront, which you'll do in the next step.

Step 4: Use Phone Authentication in the Next.js Starter Storefront#

In this step, you'll customize the Next.js Starter Storefront to allow customers to authenticate using their phone number and OTP.

By default, the Next.js Starter Storefront supports email and password authentication. You'll replace it with phone authentication, but you can also keep both authentication methods if you want to.

Terminal
❯cd ../medusa-phone-auth-storefront # change based on your project name

a. Install Phone Input Package#

To easily show a phone input where the user can enter their phone number, install the react-phone-number-input package:

npm
yarn
pnpm

You'll use it in the login and registration forms to show a phone input.

b. Add Authenticate Function#

Before adding the forms, you'll add the functions that send requests to the Medusa API to authenticate the customer.

The first one you'll add is the authenticateWithPhone function, which sends a request to the /auth/customer/phone-auth API route to authenticate the customer using their phone number.

In src/lib/data/customer.ts, add the following function:

Storefront
src/lib/data/customer.ts
1export const authenticateWithPhone = async (phone: string) => {2  try {3    const response = await sdk.auth.login("customer", "phone-auth", {4      phone,5    })6
7    if (8      typeof response === "string" || 9      !response.location || 10      response.location !== "otp"11    ) {12      throw new Error("Failed to login")13    }14
15    return true16  } catch (error: any) {17    return error.toString()18  }19}

The function accepts the phone number as a parameter.

In the function, you use the JS SDK, which is configured within the Next.js Starter Storefront, to send a request to the /auth/customer/phone-auth API route. You pass the phone number in the request body.

If the request doesn't return a location property set to otp, you throw an error. Otherwise, you return true to indicate that the request was successful.

c. add Verify OTP Function#

Next, you'll add the verifyOTP function, which sends a request to the /auth/customer/phone-auth/callback API route to verify the OTP.

In src/lib/data/customer.ts, add the following function:

Storefront
src/lib/data/customer.ts
1export const verifyOtp = async ({2  otp,3  phone,4}: {5  otp: string6  phone: string7}) => {8  try {9    const token = await sdk.auth.callback("customer", "phone-auth", {10      phone,11      otp,12    })13
14    await setAuthToken(token)15
16    const customerCacheTag = await getCacheTag("customers")17    revalidateTag(customerCacheTag)18
19    await transferCart()20
21    return true22  } catch (e: any) {23    return e.toString()24  }  25}

The function accepts an object with the following properties:

• otp: The OTP to verify.
• phone: The phone number of the customer.

In the function, you use the JS SDK to send a request to the /auth/customer/phone-auth/callback API route. You pass the phone number and OTP in the request body.

If the request is successful and you receive a token, you set the token in the cookies and refresh the customer cache. This ensures that all customer-related UI is updated after logging in, such as showing the customer's profile when accessing the /account page.

Then, you call the transferCart function to transfer the cart from the guest user to the authenticated customer.