SMS gateway

Back to user help index

The SMS gateway is an optional extra. It is for people who are setting up a dedicated handset whose job is to send text messages on request. When it is switched on, a message that is marked as an SMS command, and that came from a sender on your allowed list, is not shown to you as a message at all — Tetracom hands it straight to a companion app on the same phone, which sends it on as a normal text message (SMS) from that phone’s SIM. Tetracom then quietly tells the sender whether it worked.

On this page

• What it is and who needs it
• Setting it up, in order
• Is it working? Look at the top of the app
• What it is doing right now
• Who is allowed to send
• The three things that must all be true
• Keeping it running
• After a reboot: it waits for the first unlock
• Forwarded commands never appear in your inbox
• What “sent” actually means
• How many texts it will send in a minute
• Checking that it is working
• The quick check-in before every text
• Testing the connection yourself
• If you do not have the gateway app
• Rejected SMS commands
• Recipient opt-outs
• Turning it off
• Privacy & control

What it is and who needs it

Normally, when someone sends you a Tetracom message, you see it. The SMS gateway changes that for one special kind of message: a message that is marked, in the message itself, as an SMS command. Messages of that kind are treated as instructions, not as messages for you to read.

Each instruction says: send this text, to this phone number. Tetracom passes it to the SMS gateway app running on the same phone, and that app sends the text using the phone’s own SIM.

Two apps, one phone

This is the part that surprises people, so it is worth being plain about it. There are two separate apps, and the phone needs both:

• Tetracom — the app you already know. It receives the instruction, checks who sent it, and decides whether to act on it. It is the only thing that talks to the outside world.
• Tetracom SMS Gateway — a small companion app that does one job: actually send the text. It is the only one of the two that holds Android’s SMS permission.

They are deliberately split. The app that can send texts from your number is kept as small and as boring as possible, and it does not decide anything — it only takes orders from Tetracom on the same phone, over the phone’s own internal connection at 127.0.0.1:8769. That address means “this phone, and nothing else”: it is not reachable from the internet, from your Wi-Fi, or from any other device.

The gateway listens on both of the phone’s internal addresses on that one port — 127.0.0.1 and [::1], the older and newer ways of writing “this phone” — because handsets do not agree on which of the two localhost means. 127.0.0.1 is the one Tetracom always asks for, so that is the one that has to work; [::1] is a courtesy, and is skipped quietly on a phone that has no use for it. Neither of them makes the gateway reachable from anywhere but the handset itself.

Setting it up, in order

The order matters. Each step produces something the next step needs, and the gateway app refuses to start until it has been told which Tetracom account it belongs to.

Download the SMS Gateway APK → Download the Tetracom app →

SMS Gateway: version 0.2.4 (build 10), app ID me.tetracom.smsgateway, SHA-256 6d82ed3b8afdbe705934b2e9a0bd041f37ba54533d976315b83c745b6fe9ab06

Tetracom app: version 0.8.4 (build 92), app ID me.tetracom.android, SHA-256 9f9764c39044580baee22d275a20d4bd23975ffff3cd32757ce7999f404b213f

Is it working? Look at the top of the app

Open the Tetracom SMS Gateway app on the handset. Above every setting — above the token, above the pairing boxes, above Start and Stop — there is a section headed Status. It is there to answer one question, in one line, without you having to work anything out: is this thing working? Everything below it is setup you did once. This part is live.

The headline

The first line is in bold, and it is the whole answer. There are five of them, and a plain-language line underneath telling you what to do next.

• “Running — listening on 127.0.0.1:8769, [::1]:8769” — this is the one you want. The gateway is up and ready to take work from Tetracom on the same phone. The line underneath reads “Ready to accept send requests from the Tetracom client on this device.”
• “Running, but it cannot send” — it is listening, and it will still accept requests, but something makes actually sending impossible, so those requests will fail. The line underneath names every reason it found: the SEND_SMS permission has been revoked, there is no SIM available to send with, or the job ledger folder is not writable. Fix what it names.
• “Not running” — nothing is wrong; nobody has started it. “Press Start, under Settings below.”
• “Not running — pairing required” — no valid relay userid has been saved, so the gateway will not listen at all. “Save a valid relay userid under Relay pairing below, then press Start.” That is step 4 of Setting it up.
• “Not running — could not bind loopback port 8769” — another app on the phone is probably holding that port. Change it under Settings and press Save. If you do change it, change Port in Tetracom to match, or the two apps will not find each other.

Permission and SIM

Under the headline is the familiar readiness line, unchanged:

SEND_SMS permission: yes  ·  SIM ready: yes

Both need to read yes. A no here is the same fault the headline is describing when it says it cannot send; this line just tells you which of the two it is.

The counters

Next comes a running tally of what this gateway has done:

Sent 12  ·  Failed 1  ·  Sending now 0  ·  Timed out 0

These are totals over the last 30 days — that is how long the gateway keeps its record of jobs before it prunes itself. They are not lifetime figures, and they are not since-you-opened-the-app figures. A Sending now that never comes down, or a Timed out that keeps climbing, is worth looking into.

Send allowance

Last in the status block is how much headroom is left in the rate limit:

Send allowance: 58 of 60 left this minute

The second number is the one you set yourself, under Send limit (messages per minute) — see How many texts it will send in a minute. The first is what is left of it right now.

When the allowance drops below a quarter of your limit, the line adds a warning: further submissions will be refused with rate_limited, and a refused security code is a failed sign-in for someone. When the gateway is stopped there is nothing to count, so it reads Send allowance: 60 per minute. Counted only while the gateway is running.

What it is doing right now

Below the status block is a section headed What it is doing: a list of the recent jobs, newest first, up to 20 of them. It refreshes every couple of seconds while the screen is open, so a text that is going out right now is visibly going out right now — you can stand there and watch it change. Before anything has ever been sent it simply reads “Nothing sent yet.”

Each entry is two lines: how long ago it happened and what state it is in, then the sending client’s own reference for the job, indented underneath. Times are relative and deliberately rough — just now, 5 min ago, 2 h ago, 3 d ago.

The four states

• “Sending now — taken, not yet handed to the network”
• “Sent — the phone handed every part to the network”
• “Timed out — no confirmation arrived in time”
• “Failed (code) — explanation” — for example “Failed (carrier_rejected) — the mobile network refused it; check signal and the destination number in the sending client”.

The differences between them are the operationally useful part of this whole page, so it is worth being exact about them.

A “Timed out” can still settle itself. If the confirmation turns up late, the gateway quietly corrects that job to Sent — so a row that read Timed out a minute ago may read Sent when you look again. It never corrects in the other direction.

The failure explanations

A failure names its cause in brackets and then explains it. These are the ones you are most likely to meet, and what to do about each:

• carrier_rejected — the mobile network refused it; check signal and the destination number in the sending client.
• no_sim — no SIM was available to send with.
• permission_denied — the SEND_SMS permission was not granted.
• rate_limited — the send limit was reached. Raise it under Settings if this is legitimate traffic; see How many texts it will send in a minute.
• recipient_opted_out — that number is on this gateway’s opt-out list. Someone at that number sent STOP; it is not a fault to fix on this phone.
• busy — another text was already going out. The gateway does one at a time and refuses the second rather than holding it in a queue, so the sender finds out at once instead of waiting.
• send_timeout — there was no time left to attempt the send, so nothing was sent. Not the same as a job that shows Timed out, which may well have gone.
• pairing_required — the gateway and Tetracom are not paired; work through Setting it up, in order again.

The rest are rarer, and all of them point at the sending side rather than at your phone: invalid_request and identity_mismatch (the request was malformed, or did not come from who it claimed), consent_required (the sender holds no current permission to text that number), expired (the request sat too long and was refused before anything was sent), idempotency_conflict (the same job reference came back with different contents), and internal_unavailable (the gateway hit a fault of its own).

What the list never shows

This is deliberate, and it is worth understanding why, because it is the main reason the screen is worth leaving on. These texts routinely carry one-time security codes. A gateway handset lies face-up on a desk all day. A screen that listed the codes it had just sent would hand them to anyone walking past — which would defeat the entire point of sending a code in the first place.

Who is allowed to send

In Settings → SMS gateway there is a list called Allowed SMS senders. It is the guest list for your phone’s SIM: only the userids on it can ever make this phone send a text.

Add one by typing the userid and tapping Add. Remove one by tapping Remove on its row. Userids are saved in lower case with spaces removed, so it does not matter how you type them.

The list is also a perfectly good way to turn the feature off for one sender without turning it off for everybody: remove just that row. Emptying the list altogether stops all forwarding, which is a second, equally effective way of switching the whole feature off.

The three things that must all be true

Tetracom will only forward an instruction when all three of these hold. If any one of them fails, the instruction is thrown away and the sender is told nothing at all.

Keeping it running

A gateway that is not running is not a gateway. This is the part of the job that actually takes attention, because Android works quite hard to shut down apps it thinks you are not using — and a phone sitting in a cupboard sending the occasional text looks exactly like an app you are not using.

Three things keep it alive.

Samsung phones need more than the exemption

Samsung’s One UI has its own power management on top of Android’s, and it will override the exemption. On a Samsung gateway handset you also need to:

• Take the gateway app out of Sleeping apps and Deep sleeping apps, and add it to Never sleeping apps.
• Turn off Auto-optimise daily. This runs at about 3 AM every night and will quietly move the app back into the sleeping list, undoing your work while nobody is watching.
• Turn off Adaptive Battery, which learns from usage patterns and restricts apps it decides you do not use.

The step-by-step screens are in the Samsung guide — it is written for the Tetracom app, but apply the same steps to Tetracom SMS Gateway as well, since both have to stay awake. There are equivalent guides for Google Pixel, OnePlus, Motorola, Xiaomi, and other Android phones.

After a reboot: it waits for the first unlock

The reason is straightforward. The gateway’s token is kept in the part of Android’s storage that stays encrypted until the phone is unlocked for the first time after a restart. Before that unlock the app genuinely cannot read its own credentials, so it does not start. This is a deliberate trade: the alternative would be storing the token somewhere readable before first unlock, which is worse.

What this means in practice, for a handset you are not standing next to:

• Plan for reboots. They happen — system updates, power cuts, a knock to the cable. Any of them takes the gateway down until a person unlocks the phone.
• Turn off automatic system updates on a gateway handset, or at least schedule them for a time when somebody will be there to unlock afterwards.
• Unlock the phone after any restart, then open the gateway app and check that the headline at the top reads “Running — listening on…”. Seeing the “Listening on…” notification come back is the quick version of the same check, and it is enough if you are only walking past.
• If the handset is remote, someone needs physical access after every reboot. There is no way around this today.

Forwarded commands never appear in your inbox

A message marked as an SMS command is never shown to you. It does not land in History, it does not raise a notification, it does not make a sound, and it does not pop anything up on screen. This is deliberate: those instructions are machine traffic, not conversation, and mixing them into your messages would just be noise.

This applies to SMS commands and to nothing else. An ordinary message from the very same account — a voice message, a text, a question with buttons — behaves completely normally: it appears in your History and notifies you like any other message. So an account that usually sends instructions can still send you a plain message when it needs to.

There are two places you will see any sign of this feature working, and neither of them is your inbox. In the gateway app, the “What it is doing” list shows the recent jobs by state and time. In Tetracom, the “Last SMS gateway event” line in Settings shows how the most recent instruction was handled — see Checking that it is working. Neither shows a phone number or a word of any message.

What “sent” actually means

The sender asks once and waits. They do not get a run of updates as the text makes its way out — they get one answer, at the end, once the phone has finished trying. There are exactly three, and they are not interchangeable.

When that happens the gateway does not try again by itself. That is on purpose: a duplicate text is a real cost and a real annoyance, and guessing wrong in the other direction is worse than reporting honestly that nobody knows.

It can also resolve itself. If the phone’s confirmation arrives late — after the sender has already been told timeout — the gateway quietly updates its own record to Sent. The sender can ask again later and get the true answer. So a timeout is often just an answer that arrived after the question stopped being asked.

How many texts it will send in a minute

The SMS gateway app has a setting called “Send limit (messages per minute)”. It is a safety cap: it stops a runaway or misbehaving sender from quietly working through your whole texting plan. Anything over the limit is refused rather than queued — the sender is told rate_limited, and that text is simply never sent.

The limit is a burst allowance that refills, not a counter that resets on the clock. Think of it as a small bucket of tokens: the bucket starts full, each text takes one token out, and tokens trickle back in steadily so the bucket is full again about a minute later. So you can send a whole minute’s worth in one go if you need to, and after that you can keep going at a steady pace. It is not a rule like “10 per clock-minute, then nothing until the next minute starts.”

The default is 60 per minute — roughly one per second, steadily, with a burst of up to 60 available at any moment. It used to be 10, which turned out to be inside the range of ordinary traffic: several people can genuinely ask for a security code in the same minute, such as at a shift change or when a support agent calls someone back.

You can set it anywhere from 1 to 600.

Checking that it is working

Under the same Settings section there is a “Last SMS gateway event” line. It shows a short note about the most recent instruction Tetracom handled — enough to tell whether things are working, and no more.

• Nothing at all — no instruction has arrived since you opened the app, or the switch is off.
• Sent — every part of the text was handed to the mobile network. This is the one that counts, and it is the only success. See What “sent” actually means.
• Failed — the gateway app received the request and refused it, or the send itself did not work. It comes with a code saying which; a wrong token, no SIM, or a missing SMS permission are the usual causes.
• Timeout — the answer did not come back in the time the sender was willing to wait. The text may still have gone out; the gateway does not automatically resend it.

Four more explain that Tetracom could not get an answer out of the gateway app at all. They look similar and they are not: each one tells you to do a different thing.

• gateway_not_installed — the gateway app is not installed on this phone, so there is nothing to send texts with and nothing was sent. The sender is told this is permanent, so they stop waiting and try another way. See If you do not have the gateway app.
• gateway_unreachable — it is installed but not answering. Start the gateway app, and check it is listening on the expected loopback port. See the check-in below.
• gateway_unauthorized — it answered, but turned Tetracom away: the bearer token does not match. Correct it in Settings; see Setting it up, in order. This is the most fixable failure on the list, and a recently regenerated token is the usual reason for it.
• gateway_bad_response — it answered, but Tetracom could not make sense of the reply. That almost always means the two apps are at different versions; update both.

The sender is now told the same detail

When an instruction fails, the reply Tetracom sends back to the sender now carries the same technical detail that the Test connection button shows you — the phase the check reached, the cause, and so on. So whoever sent the instruction can see for themselves why it did not go — that the gateway app was not running, say, or that the token did not match — without needing to get hold of your phone or ask you to read anything out. That is usually the fastest way to get it fixed, because the person who noticed the problem is the person who can act on it.

The quick check-in before every text

Just before it hands over any text, Tetracom asks the gateway app one very short question: are you there and ready? Only if the app answers does the request go across.

This matters because of what these texts usually are. A typical one is a security code that stops working after about ten minutes. If the gateway app is not running, whoever sent the instruction needs to know straight away so they can reach you another way — by email, for example — while the code is still good. Waiting the better part of a minute to find out would waste time nobody has.

So when the check-in fails, it fails immediately — not after a pause — and the reply says “Service unavailable”.

You do not need to turn this on, and there is no setting for it. The check-in happens on its own, before every single text, so the answer is never out of date.

Testing the connection yourself

You do not have to wait for somebody to send a text to find out whether the gateway is ready. In Settings → SMS gateway, just under Gateway relay binding ID, there is a Test connection button. Tapping it asks the gateway app the very same question Tetracom asks automatically before every text — are you there and ready? — and shows you the answer straight away.

It is worth being precise about that: it is the same check, not a similar one. If the button tells you the gateway is ready, that is exactly what the next real instruction will find. If it tells you something is wrong, that is exactly what the next real instruction would have run into.

Reading the answer

The first line is written in plain language, and it tells you what to do. These are the answers you may see.

• It answered, and it is ready — the gateway app is running and the token matches. Texts will be forwarded. There is nothing to do.
• “Nothing is listening on 127.0.0.1:8769” — the Gateway app is not running. Open it: the headline at the top will say Not running and, if there is more to it than nobody having pressed Start, why. Tap Start and test again. If it keeps stopping on its own, see Keeping it running.
• “did not answer in time” — the Gateway app is running but stuck. Force-stop it, open it again, and test again.
• “rejected the bearer token” — the token saved in Tetracom does not match the one in the Gateway app. Copy it across again. If it was regenerated, remember that you must copy the Relay binding ID across again too.
• “The gateway host is not set” or “The gateway port is not set” — that box in Settings is empty. Gateway host should be 127.0.0.1 and Port should be 8769.
• “is not a loopback address” — the host box has the wrong value in it. It must be 127.0.0.1, which means “this phone, and nothing else”. Put that back and test again.
• “not installed” — the companion Gateway app is not on this phone at all, so there is nothing to test and nothing that could send a text. See If you do not have the gateway app.
• “not answering as the Gateway app” — something did answer on that port, but it was not the Gateway app. Some other app on the phone is using it. Check which port the Gateway app says it is listening on, and make Port match.

The detail lines underneath

Below that sentence you will see a short technical list — the phase the check reached, the cause, the host, the port, and so on. You are not expected to make sense of it, and you do not need to. It is there so you can read it out over the phone, or send a screenshot of it, to whoever is helping you: from those few lines they can tell exactly where the check stopped, without guessing.

If you do not have the gateway app

Most phones do not have the companion SMS gateway app, and that is completely normal — it is a separate app for people who deliberately set this up. If an instruction arrives on a phone without it, no text is ever sent, and nothing is shown to you.

What the sender hears is a short “not supported” answer, meaning: this phone cannot send text messages this way — do not keep trying. Otherwise they would simply get silence, wait for a reply that was never coming, and have no way to tell a wrong phone from a slow one.

This matters most for security codes. A code that expires in ten minutes is no use to anyone if the person sending it spends most of that time waiting. Told straight away, they can reach you another way — by email, for example — while the code still works.

You do not need to do anything about this, and there is no setting for it. If you never wanted this feature, you can safely ignore it: without the gateway app, nothing is ever sent from your phone.

Rejected SMS commands

In the same Settings section, whenever it applies, you will also see a line like “Rejected SMS commands: 3 — last: …”. It counts the instructions Tetracom received and refused since you last started the app, with a short note about the most recent one.

An instruction is counted here for one of two reasons: it came from a sender that did not pass the checks in The three things that must all be true, or the instruction itself could not be used — it was incomplete, malformed, or missing something Tetracom needs.

Seeing a small number here is normal, and nothing is wrong. A count that keeps climbing usually means one of three things: your Allowed SMS senders list is empty or does not contain the userid that is actually sending, the sender is not the account you think it is, or that sender was never added and approved as one of your contacts. All three are worth checking if texts you expected are not arriving.

Why most failures are silent

It is worth understanding the difference, because it changes what you should expect to see when something is wrong.

• Silent, always. Anything to do with permission: the sender is not on your allowed list, is not an approved contact, is blocked, cannot produce a valid signature, or you have forwarding switched off. In every one of these cases Tetracom says nothing at all. Telling an unauthorised sender why they were refused would just tell them what to fix, and would confirm the feature exists at all.
• Answered, for senders who already passed every check. Only two situations get a reply, and both are about what the phone can do rather than about your settings: “not supported” means the gateway app is not installed, and “service unavailable” means it is installed but did not answer. Neither reveals anything you chose.

Recipient opt-outs

The gateway app keeps a list of numbers it must never text. Enter the number in international form — for example +15551234567 — and choose Add opt-out or Remove opt-out. Once a number is on the list, requests to text it are refused, and no retry overrides that.

The audit list shows only a short keyed tag, what was done, and when. It never displays or stores the number itself or any message text.

Turning it off

Open Settings → SMS gateway and switch “Forward SMS commands” off. That takes effect immediately: from that moment nothing is forwarded, no matter who sends it or how it is signed. Your host, port, token, binding ID and allowed-senders list stay saved, so you can switch it back on later without typing them again.

Removing every row from Allowed SMS senders has the same practical effect, and is the right tool when you want to stop one sender rather than all of them: remove just their row and leave the switch alone.

Switching it off is silent: senders are simply ignored, and nobody is told you turned it off. The single exception is a phone that does not have the gateway app at all — there, an approved sender is still told “not supported”, because that is about the phone rather than about your setting.

To stop the gateway app itself as well, open it and tap Stop. The headline at the top changes to “Not running”, the notification disappears, and the app will not come back after a reboot until you start it again. If you want a specific sender to stop trying entirely, block them like any other contact, or remove them from your contacts.

Privacy & control

• Off unless you turn it on. Nothing anyone sends can enable it — there is no remote switch.
• Only a proven, approved contact you named. On your Allowed SMS senders list, an approved contact, and a valid digital signature — all three, every time. An empty list means nobody qualifies.
• Nothing is displayed. SMS commands never reach your History, your notifications, or your screen — and that is decided by the message being marked as a command, which cannot be faked or altered in transit. Ordinary messages from the same account are unaffected and arrive normally.
• It stays on the phone. The gateway app listens only on 127.0.0.1 and [::1] — the phone’s own two internal addresses, neither of which is reachable from the internet, your Wi-Fi, or any other device. It takes work only from the Tetracom app on the same handset, and it never sends anything out to the network itself. Its one optional callback is checked to make sure it, too, points back at the same phone and nowhere else.
• The token is the real lock. Being on the phone’s internal address keeps other devices out, but other apps on the same phone could still knock on the door. The bearer token is what stops them, which is why it matters that you keep it to yourself.
• Tetracom’s servers cannot read any of this. The instruction arrives end-to-end encrypted, exactly like a normal message, and is decrypted only on your phone.
• Nothing sensitive is logged. Neither app records the phone number or the message text anywhere you or anyone else can read it back. Status records keep only an opaque reference, a state, and a time, and are cleared within 31 days.
• Nothing sensitive is on screen either. The gateway’s “What it is doing” list shows only the state, the timing, and the reference the sender chose — never the message, never the destination number, neither of which is written down anywhere in the first place. That matters because these texts carry one-time codes and the handset sits face-up on a desk. The bearer token and relay binding ID stay in their own sections further down, never in the status area.
• Rejected senders learn nothing. If someone fails any of the checks, Tetracom simply stays silent — it does not tell them whether the feature exists, is on, or why they were refused.