SMSTunnel for Medusa

Medusa notifications as texts from your own phone and number

npm package · Notification Module Provider · Medusa 2 · MIT
npm install @narcisbodea/smstunnel-medusa

Medusa's sms channel, from your number

Your store hands each text to your SMSTunnel account, and your own Android phone sends it from its own SIM, so customers see a number they know and can reply to. No SMS provider account and no sender registration: the phone runs the SMSTunnel app and is linked to your account. You can cut your store off at any time by deleting its API key in your dashboard.

What it does

The sms channel
Medusa's Notification Module hands its sms notifications to your SMSTunnel account, and your phone sends each one.
Templates
Texts by template name, with {{ placeholders }} filled from the notification's data.
Your own code
createNotifications() from a subscriber, a workflow step, an API route or a scheduled job.
Safe retries
Medusa's idempotency_key goes to SMSTunnel too: a retry within 24 hours gets the first answer, never a second text.
Sign-in codes
provider_data.signInCode sends a code of 4 to 10 digits, on its own allowance.
Requirements
Medusa 2 (tested with 2.22.2), Node.js 20 or newer. No other dependencies.

1. Install

npm install @narcisbodea/smstunnel-medusa

Medusa 2 (tested with 2.22.2), Node.js 20 or newer. No other dependencies.

2. Get your key

  1. 1. Install the SMSTunnel app from Google Play on your Android phone and sign in.
  2. 2. In your dashboard, open Apps → Add an app, pick Node.js, name it (for example "My Medusa store") and click Create the key.
  3. 3. Copy the key right away: it's shown only once. You can stop or delete the app there anytime, and My Medusa store can't send texts anymore.

Get the steps with your key in them

It opens Add an app with Node.js picked. Once the key is made, the dashboard shows every step and command with the key already filled in, ready to copy.

Put it in your Medusa environment (.env, or your host's secret settings), never in your code:

SMSTUNNEL_API_KEY=sk_live_...

3. Register the provider

Register it with Medusa's Notification Module in medusa-config.ts:

medusa-config.ts
module.exports = defineConfig({
  // ...
  modules: [
    {
      resolve: "@medusajs/medusa/notification",
      options: {
        providers: [
          {
            resolve: "@narcisbodea/smstunnel-medusa",
            id: "smstunnel",
            options: {
              channels: ["sms"],
              apiKey: process.env.SMSTUNNEL_API_KEY,
              // Optional:
              defaultCountryCode: "+1", // for numbers written without + or 00
              templates: {
                "order-placed": "Thanks {{ first_name }}! Your order #{{ display_id }} is confirmed.",
              },
            },
          },
        ],
      },
    },
  ],
})

Medusa takes one provider per channel: if another provider already handles sms, swap it for this one. Medusa won't start without an apiKey, so a missing variable shows up right away.

apiKey
Required. Your SMSTunnel API key.
channels
Required by Medusa: ["sms"].
templates
Texts by template name, with {{ placeholders }} filled from the notification's data (dots reach inside objects: {{ customer.first_name }}).
defaultCountryCode
Completes numbers written without + or 00, e.g. "+40". It wins over the phone's own country.
deviceId
The phone that sends, when your account has several (its ID is under Phones, with a Copy button). Empty: your phone that is online.
baseUrl
Default https://smstunnel.io.
timeoutMs
Default 30000.

4. Text the customer when an order is placed

Add a subscriber, src/subscribers/order-placed.ts:

src/subscribers/order-placed.ts
import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils"

// Texts the customer when an order is placed, from your own phone, through SMSTunnel.
export default async function orderPlacedText({ event: { data }, container }: SubscriberArgs<{ id: string }>) {
  const query = container.resolve(ContainerRegistrationKeys.QUERY)
  const notifications = container.resolve(Modules.NOTIFICATION)

  const {
    data: [order],
  } = await query.graph({
    entity: "order",
    fields: ["id", "display_id", "shipping_address.first_name", "shipping_address.phone", "billing_address.phone"],
    filters: { id: data.id },
  })
  const phone = order?.shipping_address?.phone || order?.billing_address?.phone
  if (!phone) return // the customer left no number: nothing to send

  await notifications.createNotifications({
    to: phone,
    channel: "sms",
    template: "order-placed",
    data: { first_name: order.shipping_address?.first_name ?? "", display_id: order.display_id },
    // Medusa sends a notification only once per key, and SMSTunnel won't send the same text twice either.
    idempotency_key: `order-placed-${order.id}`,
  })
}

export const config: SubscriberConfig = { event: "order.placed" }

With the order-placed template above, the customer gets: Thanks Ana! Your order #1042 is confirmed. The same pattern works for order.fulfillment_created, order.canceled, delivery.created and the other Medusa events.

Customers type phone numbers in many ways. Ask for the international format at checkout, or set defaultCountryCode for your country.

Send a text from your own code

From a workflow step, an API route or a scheduled job, resolve the Notification Module and pass the text in content.text:

const notifications = container.resolve(Modules.NOTIFICATION)

await notifications.createNotifications({
  to: "+14155550123",
  channel: "sms",
  template: "pickup-ready", // a name for your records; content.text is what's sent
  content: { text: "Your order is ready for pickup at our Market St store until 7 pm." },
  provider_data: { deviceId: "6ae9940bf30ce9d1447cc179" }, // optional: another phone of yours
})

What a notification can carry:

to
One number, in international format (+14155550123). For several people, create one notification each.
content.text
The text, up to 1600 characters. When it's there, it is sent as is.
template + data
Without content.text, the provider's templates[template] filled from data.
idempotency_key
Medusa's own field. The provider also sends it to SMSTunnel (Idempotency-Key: medusa:<key>), so a retry within 24 hours gets the first text's answer instead of a second text.
provider_data.deviceId
Send from this phone.
provider_data.defaultCountryCode
For this text only.
provider_data.signInCode
true sends it as a sign-in code: the text must contain a code of 4 to 10 digits on its own (482913, or 123-456), 320 characters at most, and it counts against your sign-in code allowance.
provider_data.idempotencyKey
Your own key instead of medusa:<idempotency_key>.

Each notification Medusa stores keeps SMSTunnel's message id in external_id.

When a text doesn't go out

createNotifications throws, and Medusa stores the notification with status failure. The error says why:

401
The API key is wrong, deactivated or deleted. Create a new one under Apps → Add an app.
403
The key lacks a permission (the error carries code: "PERMISSION_REQUIRED" and the permission), or your plan doesn't include what was asked.
429
Too many requests (30 sends a minute per key): Retry-After says how many seconds to wait. Without it, today's allowance of your plan is used up.
5xx, or no answer
SMSTunnel had a problem. The text may or may not have gone out: check the Messages page in your dashboard before you send it again, or send it again with the same idempotency_key.
400
SMSTunnel refused a field, such as a number it can't read or a code text without a code.

A number that isn't one, a list of numbers in to, an empty text or one over 1600 characters is refused before anything is sent. If your phone is offline, the text isn't lost: it waits in the queue on your account and goes out as soon as the phone is back online (up to 3 days). The provider never resends a text by itself. In a subscriber, a failure is logged by Medusa and doesn't affect the order.

The client on its own

The package also exports the small API client it uses, for status checks or listing phones:

import { SmsTunnelClient, fetchTransport } from "@narcisbodea/smstunnel-medusa"

const smstunnel = new SmsTunnelClient({ apiKey: process.env.SMSTUNNEL_API_KEY!, transport: fetchTransport() })
const { devices } = await smstunnel.listPhones() // [{ id, name, isOnline, lastSeenAt }]
const status = await smstunnel.getStatus(notification.external_id) // pending, sent, delivered, failed

Limits worth knowing

  • 30 send requests a minute per key. Over it, a 429 with Retry-After.
  • Plans: each plan has its own allowance. See Pricing.
  • Length: up to 1600 characters; sign-in codes up to 320.
  • Numbers: use the international format (+14155550123), or set defaultCountryCode.
  • Offline phone: the text waits on your account and goes out when the phone is back online, for up to 3 days.

Build it with an AI assistant

Copy this prompt into Claude, ChatGPT, Cursor or Copilot and replace the part in [brackets]. Don't paste your API key into the chat: the prompt doesn't need it.

Help me send texts from my Medusa 2 store with SMSTunnel.

About SMSTunnel (https://smstunnel.io): my own apps and tools hand text messages (SMS) to my SMSTunnel account, and my own Android phone sends them from my own number, on my own SIM and plan. The phone runs the SMSTunnel app from Google Play (https://play.google.com/store/apps/details?id=io.smstunnel.app), signed in to my account.

What I want: [describe what should send a text, to whom, and when]

How it works:
- Use @narcisbodea/smstunnel-medusa (npm install @narcisbodea/smstunnel-medusa; Medusa 2, Node.js 20+, no other dependencies), a Notification Module Provider for the "sms" channel, registered in medusa-config.ts: modules: [{ resolve: "@medusajs/medusa/notification", options: { providers: [{ resolve: "@narcisbodea/smstunnel-medusa", id: "smstunnel", options: { channels: ["sms"], apiKey: process.env.SMSTUNNEL_API_KEY, defaultCountryCode: "+1" (optional), deviceId (optional, which phone sends), templates: { "<name>": "a text with {{ placeholders }} filled from data" } (optional) } }] } }]. Medusa takes one provider per channel.
- To send, resolve Modules.NOTIFICATION in a subscriber, workflow step or API route and call createNotifications({ to: "+14155550123", channel: "sms", template: "<name>", data: {...} }), or pass content: { text: "..." } (content.text wins over the template). provider_data may carry deviceId, defaultCountryCode, signInCode: true (a sign-in code: the text must contain a code of 4 to 10 digits standing on its own, at most 320 characters) and idempotencyKey.
- Set idempotency_key on the notification so a retry can't send a second text: the provider sends it to SMSTunnel as Idempotency-Key: medusa:<key>, and a retry within 24 hours gets the first text's answer. One recipient per notification: for several people, create one notification each. Each stored notification keeps SMSTunnel's message id in external_id.
- A failed send throws and Medusa stores the notification as "failure" with SMSTunnel's reason: 401 wrong key, 403 missing permission or plan (with a code such as PERMISSION_REQUIRED), 429 too many requests (Retry-After header) or today's allowance used up, 5xx SMSTunnel problem (the text may have gone out: never resend without the same idempotency key). The provider never resends by itself. If the phone is offline, the text waits in the queue and goes out when the phone is back online.
- Texts up to 1600 characters; 30 send requests a minute per key; defaultCountryCode (e.g. "+40") completes numbers written without + or 00 and wins over the phone's own country.
- The API key comes from my SMSTunnel dashboard (https://dashboard.smstunnel.io): Apps → Add an app → Create the key. It is shown only once and can send texts and check whether they went out.

Rules for your answer:
- Keep the API key in an environment variable or the platform's secret store (for example SMSTUNNEL_API_KEY). Never put it in source code, in a repository, or in code that runs in a browser or a mobile app: call SMSTunnel from a server. I will not paste my key in this chat; use a placeholder.
- Validate phone numbers before sending (international format, like +14155550123) and skip or report the invalid ones.
- Handle errors: log or show what went wrong, retry only after 429, 5xx or network errors and only a few times, and never send the same text twice.
- Only send texts people expect from me: alerts to myself, reminders, sign-in codes, updates they asked for. No unsolicited texts.

Responsible use

Built for alerts to yourself and your team, and texts people expect from you. One text goes to one number. Sending unsolicited messages from a consumer SIM generally breaches mobile carrier terms of service.

Medusa is a trademark of its owner. SMSTunnel is a third-party integration and is not affiliated with, endorsed by, or sponsored by Medusa.

No phone paired yet?

Install the Android app and sign in with your account, and you're ready in about a minute.

Get it on Google Play