SMSTunnel for Medusa
Medusa notifications as texts from your own phone and number
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. Install the SMSTunnel app from Google Play on your Android phone and sign in.
- 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. 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:
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:
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 setdefaultCountryCode. - 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.