Skip to main content

Twilio SMS

In this document, you’ll learn about the Twilio SMS Plugin, what it does, and how to use it in Medusa.

Overview​

Twilio’s SMS API can be used to send users SMS messages instantly. It has a lot of additional features such as Whatsapp messaging and conversations.

By integrating Twilio SMS into Medusa, you’ll have easy access to Twilio’s SMS API to send SMS messages to your users and customers. You can use it to send Order confirmations, verification codes, reset password messages, and more.

This plugin only gives you access to the Twilio SMS API but does not implement sending messages at any given point. You’ll have to add this yourself where you need it. You can look at the example later in this tutorial to check how you can send an SMS for a new order.

Prerequisites​

Before going further with this guide make sure you have a Medusa server set up. You can follow the Quickstart guide if you don’t.

You also must have a Twilio account created so if you don’t already please go ahead and create one.

Retrieve Credentials​

For the Twilio SMS plugin, you need three credentials from your Twilio account: Account SID, Auth Token, and a Twilio phone number to send from. You can find these three from your Twilio Console’s homepage.

Install Plugin​

In the directory of your Medusa server, run the following command to install Twilio SMS plugin:

yarn add medusa-plugin-twilio-sms
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

Then, you’ll need to add your credentials in .envCopy to Clipboard:

TWILIO_SMS_ACCOUNT_SID=<YOUR_ACCOUNT_SID>
TWILIO_SMS_AUTH_TOKEN=<YOUR_AUTH_TOKEN>
TWILIO_SMS_FROM_NUMBER=<YOUR_TWILIO_NUMBER>
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

Make sure to replace <YOUR_ACCOUNT_SID>Copy to Clipboard, <YOUR_AUTH_TOKEN>Copy to Clipboard, and <YOUR_TWILIO_NUMBER>Copy to Clipboard with the credentials you obtained from your Twilio Console.

Finally, add the plugin and its options in the medusa-config.jsCopy to Clipboard file to the pluginsCopy to Clipboard array:

medusa-config.js
const plugins = [
  // ...
  {
    resolve: `medusa-plugin-twilio-sms`,
    options: {
      account_sid: process.env.TWILIO_SMS_ACCOUNT_SID,
      auth_token: process.env.TWILIO_SMS_AUTH_TOKEN,
      from_number: process.env.TWILIO_SMS_FROM_NUMBER,
    },
  },
]
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

Example Usage of the Plugin​

This plugin adds the service twilioSmsServiceCopy to Clipboard to your Medusa server. To send SMS using it, all you have to do is resolve it in your file as explained in the Services documentation.

In this example, you’ll create a subscriber that listens to the order.placedCopy to Clipboard event and sends an SMS to the customer to confirm their order.

For this example to work, you’ll need to install and configure Redis on your server. You can refer to the development guide to learn how to do that.

Create the file src/services/sms.jsCopy to Clipboard in your Medusa server with the following content:

src/services/sms.js
class SmsSubscriber {
  constructor({ twilioSmsService, orderService, eventBusService }) {
    this.twilioSmsService_ = twilioSmsService
    this.orderService = orderService

    eventBusService.subscribe("order.placed", this.sendSMS)
  }

  sendSMS = async (data) => {
    const order = await this.orderService.retrieve(data.id, {
      relations: ["shipping_address"],
    })

    if (order.shipping_address.phone) {
      this.twilioSmsService_.sendSms({
        to: order.shipping_address.phone,
        body: "We have received your order #" + data.id,
      })
    }
  }
}

export default SmsSubscriber
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

In the constructorCopy to Clipboard, you resolve the twilioSmsServiceCopy to Clipboard and orderServiceCopy to Clipboard using dependency injection to use it later in the sendSMSCopy to Clipboard method.

You also subscribe to the event order.placedCopy to Clipboard and sets the event handler to be sendSMSCopy to Clipboard.

In sendSMSCopy to Clipboard, you first retrieve the order with its relation to shipping_addressCopy to Clipboard which contains a phoneCopy to Clipboard field. If the phone is set, you send an SMS to the customer using the method sendSmsCopy to Clipboard in the twilioSmsServiceCopy to Clipboard.

This method accepts an object of parameters. These parameters are based on Twilio’s SMS APIs. You can check their API documentation for more fields that you can add.

If you create an order now on your storefront, you should receive a message from Twilio on the phone number you entered in the shipping address.

If you don’t have a storefront set up yet, you can install one of the Next.js or Gatsby storefronts.

If you’re on a Twilio trial make sure that the phone number you entered on checkout is a verified Twilio number on your console.

Twilio Dashboard

See Also​