SMSTunnel for ERPNext

Document texts from your own phone and number

Built into ERPNext and Frappe · no app
SMS Settings
ERPNext SMS docs

Order and appointment texts from a number customers know

ERPNext can text a customer when their order is ready, or you when something needs your attention. With SMSTunnel in SMS Settings, ERPNext hands each text to your SMSTunnel account and your own Android phone sends it from your own number, so people can simply reply.

1. 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 Script or server, name it (for example "ERPNext") 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 ERPNext can't send texts anymore.

Get the steps with your key in them

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

2. Fill in SMS Settings

As a System Manager, type SMS Settings in the search bar and open it. Fill in:

URL (the first field)
https://smstunnel.io/api/v1/sms/send
Message Parameter
message
Receiver Parameter
to
Static Parameters
X-API-Key = your key, Header ticked
Static Parameters
Content-Type = application/json, Header ticked
Use POST
ticked
  • Write application/json exactly: that's what makes ERPNext send JSON. Tick Header on both rows.
  • Add no other Static Parameters: a row without Header becomes a field in the body, and SMSTunnel refuses fields it doesn't know.
  • ERPNext sends one request per number: {"message": "…", "to": "+14155550123"}. It removes spaces, dashes and parentheses from numbers and keeps the +, so store phone numbers with the country code.

3. Test it with your own number

Open SMS Center, put only your own number in Receiver List, type a message and click Send SMS. ERPNext shows "SMS sent successfully" and logs it in SMS Log. Use SMS Center for tests and single texts, not to text whole groups of contacts or leads: SMSTunnel is for texts people expect.

4. Text the right person automatically

  • Notification: create one with Channel: SMS, choose the document and Send Alert On (for example when a Sales Order is submitted), and under Recipients pick Receiver By Document Field with the phone field. The Message takes Jinja, like: 
Hi {{ doc.customer_name }}, your order {{ doc.name }} is ready for pickup.

Send SMS: on submitted sales and purchase documents, the ⋯ menu offers Send SMS once SMS Settings are filled in, for a one-off text to that customer or supplier.

Worth knowing

  • Don't turn on SMS for two-factor sign-in in System Settings with this setup: ERPNext sends those codes in a different format, and they would fail.
  • The key is stored in clear in SMS Settings, readable by System Managers. Give ERPNext its own app in SMSTunnel, so you can stop it without touching your other apps.
  • One failing number stops the rest of that send. Keep numbers in international format.
  • 30 sends a minute, up to 1600 characters per text. If your phone is offline, the text waits.

If it doesn't work

  • ERPNext writes failed Notifications to the Error Log ("Failed to send Notification"), with SMSTunnel's answer.
  • 401 "Invalid or expired API key": the key is wrong or was deleted. "API key is required. Use X-API-Key header.": the key isn't in an X-API-Key header. SMSTunnel reads the key only from that header: Bearer or Basic authentication won't work.
  • 403 with PERMISSION_REQUIRED: the key may not send texts. Make a new one under Apps → Add an app.
  • 400 "property … should not exist": the body has a field SMSTunnel doesn't know. Send only to and message (and, if you need them, deviceId and defaultCountryCode). "message must be shorter than or equal to 1600 characters": shorten the text. "Phone number must contain…": put the number in international format, like +14155550123.
  • 400 with "to must be a string" and "message must be a string": the body didn't arrive as JSON. Add the header Content-Type: application/json.
  • 404 "Cannot GET /api/v1/sms/send": the tool sent a GET. Choose POST.
  • 429: too many texts at once. SMSTunnel takes 30 send requests a minute. Wait a minute and try again.
  • No text, but no error? If your phone is offline, the text waits and goes out as soon as the phone is back online. Open the SMSTunnel app on the phone to check it's linked.

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 ERPNext (Frappe) SMS from my own phone, with SMSTunnel: notifications and the "Send SMS" button on documents.

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:
- No app to install: ERPNext's SMS Settings (search bar: "SMS Settings"; System Manager only).
- The URL field at the top: https://smstunnel.io/api/v1/sms/send. Message Parameter: message. Receiver Parameter: to. Static Parameters, both with "Header" ticked: X-API-Key = <my key>, and Content-Type = application/json (exactly this value; that is what makes Frappe send JSON). Use POST: ticked. No other Static Parameters: rows without "Header" become body fields, which SMSTunnel refuses with 400.
- Frappe then sends one POST per number with {"message": "…", "to": "+14155550123"}. It strips spaces, dashes and parentheses, keeps the +, and stops at the first number that fails.
- Where texts come from: a Notification with Channel "SMS" (Send Alert On, Recipients "Receiver By Document Field" with a phone field, Message in Jinja like "Hi {{ doc.customer_name }}, your order {{ doc.name }} is ready for pickup."), and "Send SMS" in the ⋯ menu of submitted sales and purchase documents.
- Test: SMS Center with only my own number in Receiver List. Don't use SMS Center to text whole groups of contacts or leads: SMSTunnel is for texts people expect.
- Don't turn on SMS for two-factor sign-in in System Settings: that path sends the parameters as a form and fails.
- The key is stored in SMS Settings in clear, readable by System Managers.
- One recipient per request: SMSTunnel sends one text to one number. For several people, one request (or one notification) per number.
- Answers: 200 {"success": true, "messageId": "…"}; 401 wrong or deleted key; 403 the key lacks a permission ("code": "PERMISSION_REQUIRED"); 400 a missing, unknown or too long field; 429 too many requests (30 sends a minute, with Retry-After): wait and retry; without Retry-After, the plan's limit for the day or month is reached. If my phone is offline the text waits and goes out when it is back, within 3 days.
- 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:
- Do not ask for my SMSTunnel password or API key and do not put a real key in your answer; I will not paste it in this chat.
- Phone numbers must be in international format (+ and the country code).
- Help me test it with my own number first.
- Only send texts people expect from me. No unsolicited texts.
- Help me write Notifications that text only the person the document is about (their order, their appointment).

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.

ERPNext and Frappe are trademarks of Frappe Technologies. SMSTunnel is a third-party integration and is not affiliated with, endorsed by, or sponsored by Frappe Technologies.

More texts from your own tools

Zoho CRM
Webhook texts
Airtable
Texts from a script step
n8n
Texts from your workflows

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