SMSTunnel for Strapi

Texts from your Strapi project, sent by your own phone and number

npm package · Strapi 5 plugin · Node.js 20+ · MIT
npm install @narcisbodea/smstunnel-strapi

A service your code calls, a settings page in the admin

Strapi hands each text to your SMSTunnel account, and your own Android phone sends it from its own SIM, so people 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 project off at any time by deleting its API key in your dashboard.

What it does

A service
strapi.plugin('smstunnel').service('sms'): send(), sendCode(), getStatus(), listPhones() and getUsage(), from lifecycles, controllers and cron jobs.
A settings page
Settings → SMSTunnel: the key (checked, then saved encrypted), your phones and whether they are online, the phone that sends, the country code and a test text.
Roles
Two permissions decide who may read or change the settings. The plugin adds no public API routes.
Safe retries
An idempotencyKey per text: a second call with the same key within 24 hours never sends a second text.
Sign-in codes
sendCode(): a code of 4 to 10 digits, on its own allowance.
Requirements
Strapi 5 (tested with 5.60.0), Node.js 20 or newer. No other dependencies.

1. Install

npm install @narcisbodea/smstunnel-strapi
npm run build   # rebuilds the admin panel with the plugin's settings page

Strapi 5 (tested with 5.60.0), Node.js 20 or newer. No other dependencies. Strapi finds the plugin by itself; restart it after installing.

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 Strapi project") 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 Strapi project 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.

Keep the key out of your code: put it in an environment variable such as SMSTUNNEL_API_KEY (.env, or your host's secret settings), or paste it on the plugin's settings page.

3. Set it up

Either way works; what config/plugins sets wins, and the settings page then shows it read-only.

In config (config/plugins.ts), with the key in an environment variable:

config/plugins.ts
export default ({ env }) => ({
  smstunnel: {
    enabled: true,
    config: {
      apiKey: env('SMSTUNNEL_API_KEY'),
      deviceId: env('SMSTUNNEL_DEVICE_ID', ''), // optional: which of your phones sends
      defaultCountryCode: '+1', // optional: for numbers written without + or 00
    },
  },
});

In the admin panel: Settings → SMSTunnel → Texts from your phone. Paste the key there: it is checked with SMSTunnel first, then saved encrypted with Strapi's encryption key (ENCRYPTION_KEY in .env, which new Strapi 5 projects have) and never sent back to the browser. The page also shows your phones and whether they are online, lets you pick the phone that sends and the country code, and sends a test text.

apiKey
Your SMSTunnel API key.
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.
defaultCountryCode
Completes numbers written without + or 00, e.g. '+40'. It wins over the phone's own country.
baseUrl
Default https://smstunnel.io.
timeoutMs
Default 30000.

Who may see or change the settings: Settings → Administration panel → Roles → a role → Settings → SMSTunnel (Read the SMSTunnel settings and phones, Change the SMSTunnel settings and send a test text). The plugin adds no public API routes.

4. Send a text from your code

const sent = await strapi.plugin('smstunnel').service('sms').send({
  to: '+14155550123',
  message: 'Your table for 4 is ready.',
});
// sent: { messageId: '6ae9952f7f9ac207c547af90', queued: false, replayed: false }
send({ to, message, deviceId?, defaultCountryCode?, idempotencyKey? })
One text to one number, up to 1600 characters. For several people, call it once per number.
sendCode({ to, message, ... })
A sign-in or verification code. The text must contain the code: 4 to 10 digits on their own (482913, or 123-456), 320 characters at most. It counts against your sign-in code allowance.
getStatus(messageId)
pending, sent, delivered or failed (deliveryStatus: 'unconfirmed': handed to the SIM without a confirmation; it was most likely sent).
listPhones()
{ devices: [{ id, name, isOnline, lastSeenAt }], online, total }.
getUsage()
What your plan allows today and what is left.

idempotencyKey: a second call with the same key within 24 hours gets the first answer back (replayed: true) instead of sending a second text. Use one key per text, such as order-1042-shipped.

TypeScript: import the service's type and cast the service to it.

import type { SmsTunnelService } from '@narcisbodea/smstunnel-strapi/strapi-server'

Text each new entry (a lifecycle)

For example a lead collection with name and phone fields:

src/api/lead/content-types/lead/lifecycles.ts
// Texts each new lead from your own phone, through SMSTunnel.
export default {
  async afterCreate(event: { result: { documentId: string; name?: string; phone?: string } }) {
    const { result } = event;
    if (!result.phone) return; // no number: nothing to send

    try {
      await strapi.plugin('smstunnel').service('sms').send({
        to: result.phone,
        message: `Thanks ${result.name ?? ''}, we got your request and will call you back today.`,
        // A retry (or a second afterCreate for the same entry) within 24 h can't send a second text.
        idempotencyKey: `lead-${result.documentId}`,
      });
    } catch (error) {
      // A text that can't go out must not undo the entry: log it.
      strapi.log.error(`SMSTunnel: ${(error as Error).message}`);
    }
  },
};

This fits a content type without Draft & Publish. With Draft & Publish on, Strapi creates a new row when an entry is published, so afterCreate runs again; use a Document Service middleware instead, which runs once per new document:

src/index.ts
import type { Core } from '@strapi/strapi';

export default {
  register({ strapi }: { strapi: Core.Strapi }) {
    // With Draft & Publish, lifecycles fire again when an entry is published: a Document Service
    // middleware on "create" texts once per new document.
    strapi.documents.use(async (context, next) => {
      const result = await next();
      if (context.uid === 'api::booking.booking' && context.action === 'create') {
        const booking = result as { documentId: string; phone?: string; date?: string };
        if (booking.phone) {
          strapi
            .plugin('smstunnel')
            .service('sms')
            .send({
              to: booking.phone,
              message: `Your booking for ${booking.date ?? 'your date'} is confirmed.`,
              idempotencyKey: `booking-${booking.documentId}`,
            })
            .catch((error: Error) => strapi.log.error(`SMSTunnel: ${error.message}`));
        }
      }
      return result;
    });
  },

  bootstrap() {},
};

Ask for numbers in the international format in your forms (+14155550123), or set defaultCountryCode. Keep the phone field a text field: a number field loses the + and leading zeros, and the plugin refuses a JavaScript number.

When a text doesn't go out

The service throws an SmsTunnelError with status, code, retryAfter and mayHaveSent:

401
The API key is wrong, deactivated or deleted. Create a new one under Apps → Add an app.
403
The key lacks a permission (code: 'PERMISSION_REQUIRED', with permission), or your plan doesn't include what was asked.
429
Too many requests (30 sends a minute per key): retryAfter 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. mayHaveSent is true: check the Messages page in your dashboard before you send it again, or send it again with the same idempotencyKey.
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, several numbers in to, an empty text or one over 1600 characters is refused before anything is sent. Without a key, the error says where to add one. If your phone is offline, the text isn't lost: queued is true, it waits in the queue on your account and goes out as soon as the phone is back online (up to 3 days). The plugin never resends a text by itself.

Limits worth knowing

  • 30 send requests a minute per key. Over it, an SmsTunnelError with retryAfter.
  • 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 Strapi 5 project 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 the plugin @narcisbodea/smstunnel-strapi (npm install @narcisbodea/smstunnel-strapi, then npm run build to rebuild the admin panel; Strapi 5, Node.js 20+). Its key is in config/plugins.ts: smstunnel: { enabled: true, config: { apiKey: env('SMSTUNNEL_API_KEY'), deviceId (optional, which phone sends), defaultCountryCode: '+1' (optional) } } (or saved, encrypted, in Settings → SMSTunnel → Texts from your phone, which also sends a test text). The plugin adds no public API routes.
- From server code, call strapi.plugin('smstunnel').service('sms'): send({ to, message, deviceId?, defaultCountryCode?, idempotencyKey? }) → { messageId, queued, replayed }: one text to one number, up to 1600 characters; sendCode({ to, message }) for sign-in codes: the text must contain a code of 4 to 10 digits standing on its own (e.g. 482913 or 123-456), at most 320 characters; getStatus(messageId), listPhones(), getUsage().
- It throws SmsTunnelError with status, code, retryAfter and mayHaveSent. For a new entry, use a lifecycle (afterCreate) on content types without Draft & Publish, or strapi.documents.use(...) on action "create" when Draft & Publish is on (lifecycles fire again on publish).
- Pass an idempotencyKey per text (e.g. based on the documentId): a second call with the same key within 24 hours gets the first answer back (replayed: true) instead of a second text. The plugin never resends by itself.
- Errors: 401 wrong key, 403 missing permission or plan (code such as PERMISSION_REQUIRED), 429 too many requests (Retry-After) or today's allowance used up, 5xx SMSTunnel problem (mayHaveSent: the text may have gone out: never resend without the same idempotencyKey). If the phone is offline, the text waits in the queue (queued: true) and goes out when the phone is back online.
- 30 send requests a minute per key; defaultCountryCode (e.g. "+40") completes numbers written without + or 00. Store phone numbers in a text field: a number field loses the + and leading zeros.
- 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.

Strapi is a trademark of its owner. SMSTunnel is a third-party integration and is not affiliated with, endorsed by, or sponsored by Strapi Solutions SAS or the Strapi project.

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