Devices

A device is an Android phone running the app and paired with your gateway. It is the phone, not the gateway, that sends and receives the SMS, with its own SIM cards and its own carrier plan. You can pair as many phones as you like: the gateway spreads the traffic between them and takes over when one drops out.

Everything on this page happens in the Devices screen of the dashboard.

What you need

• An Android phone (a modest, dedicated phone is fine) with one or two SIM cards that have an SMS plan or credit.
• A charger that stays plugged in. See Keep the phone running.
• A network connection between the phone and the gateway: Wi-Fi or mobile data. The phone must be able to reach the address of your gateway.
• A Superadmin account: pairing, unpairing and editing quotas are reserved to that role.

Install the app

The app is distributed outside the Play Store. In Devices, the Android app panel shows a QR code: scan it with the phone's camera to download the app, or use Download the APK. Android asks you to allow installs from the browser: this is expected for an app that does not come from the Play Store.

If the panel says no app is stored on the gateway, the APK file has not been placed on your installation. See the installation guide.

On first launch, the app asks for a few permissions:

Pair a phone

1. In Devices, click Pair a device. A QR code appears, valid for five minutes.
2. In the app, choose Pair and scan the code.
3. The phone appears in the list, Online, with its SIM cards.

No usable camera? Under the QR code, the dialog shows a Fallback code, no camera needed of eight characters. In the app, tap Type the code instead, enter the server address and that code.

Each code works once and expires after five minutes. If it has expired, click Generate a new code. The QR code is signed by your gateway: a phone cannot be tricked into pairing with another server by an edited code.

Follow your phones

The Devices table shows, for each phone:

A connected phone gives news every thirty seconds, or at the Sync interval set in Settings > General, devices. After five minutes without news, or three of its intervals when that is longer (thirty minutes for a ten-minute interval), the gateway marks it Offline. The messages that phone was holding go back to the queue and leave from another phone, without counting as a failed attempt: the message did nothing wrong, the phone disappeared.

The gateway also publishes an event when a phone connects (device.online), drops out (device.offline) or when its battery falls below 15 % (device.low_battery, sent once when the threshold is crossed, not on every reading below it). Subscribe a webhook to these events to be warned in your own tools: see Webhooks.

Actions on a phone

From the Actions column (Superadmin):

Uptime history

The gateway keeps the connection history of every phone, so you can tell a reliable phone from one that keeps dropping out. You see it in two places:

• the Device uptime card of the Dashboard, under the activity chart (the first eight phones, with a link to the others);
• the same card under the table of the Devices screen, for the whole fleet, and the Uptime (24 h) column of the table.

Choose the period with the 24 h, 7 d, 30 d and 90 d buttons. Each phone gets one row: its name, its current status, its uptime percentage over the period, and one bar per time slot (one per hour over 24 hours, per six hours over 7 days, per day over 30 and 90 days). Time slots follow the platform time zone (Settings > Sending), daylight saving included, so the day of a clock change lasts 23 or 25 hours. Hover or tap a bar for the exact times of the slot and how long the phone was in each state. At the top of the card, Fleet uptime gives one figure for all your phones together.

Each bar splits the time into three states, told apart by their position, a word and an icon in the legend and the tooltip, never by color alone:

A slot before the phone was paired stays an empty track: a phone paired this morning is not counted as offline for the night before.

How the percentage is computed. Uptime is the online time divided by the online plus offline time. Time the gateway was stopped is not counted as offline: an update of the gateway at night does not lower the uptime of your phones. When nothing was observed over the period (the gateway was stopped the whole time), the card shows No data instead of 0 %.

How long it is kept. The history is kept 90 days by default, the longest period of the chart. Set GATEWAY_UPTIME_RETENTION_DAYS (from 90 to 3650) to keep it longer, see the installation guide. The history starts when you install a version of the gateway that records it: earlier time reads as unknown. Unpairing a phone deletes its history.

Through the API. GET /devices/uptime?period=24h (or 7d, 30d, 90d) returns the same report: for each phone and each slot, the seconds online, offline, unknown and before pairing, plus uptimePercent (null when nothing was observed). Any key with the read scope and every dashboard role can read it.

Daily SIM quota

Each SIM has a daily allowance of SMS, 200 by default.

Why it matters. Carriers watch consumer SIM cards. A SIM that suddenly sends thousands of SMS a day looks like spam and can be suspended, sometimes for good. The quota keeps each SIM under a volume you choose. When one SIM is spent, the gateway uses another; when every SIM is spent, the messages wait.

How it counts.

• A long message counts for as many SMS as it takes (a message of 200 plain characters is two SMS).
• The count restarts every day at midnight UTC, whatever the time zone of your platform. This is deliberate: carriers count in absolute time, and changing your time zone must never grant a second allowance for the same day.

Where you see it. In the Today's quota column: "12 of 200 today", or just "No cap" for a SIM without a cap, with a bar that turns amber from 80 % and red when the quota is reached, and a Quota reached marker. The Dashboard also shows an alert for each SIM close to or at its quota.

Change it (Superadmin). Click the pencil next to the SIM. The Quota and cadence of the SIM dialog offers:

What happens when you save:

• Today's count is kept. Raising from 200 to 500 at noon after 200 sends leaves 300 for the rest of the day. Lowering below what was already sent stops the SIM until midnight UTC.
• Held messages leave at once. If messages were waiting because every quota was reached, raising a quota, removing the cap or putting a SIM back in service sends them right away instead of at midnight. The Queue screen shows a banner counting those messages, with an Edit quotas link to this screen.

A SIM with its own interval shows "Own cadence: 1 SMS every 30 s" under its quota.

Through the API, the same setting is PATCH /devices/{deviceId}/sims/{slot} with dailyQuota (0 means no cap), enabled and minIntervalSeconds (null to follow the setting again, 0 for no wait). GET /devices returns minIntervalSeconds for each SIM, null when it follows the setting.

The local time of each phone

Your phones do not have to be in the same country as your platform. The header of the dashboard shows, next to the live indicator, the local time of your phones: with one phone, its time directly; with several, their number, and the detail when you click it. Each phone shows its time zone and a Not on platform time marker when its clock differs from the time zone of the platform.

Why it matters. The night and Sunday pauses of campaigns and the time of scheduled sends follow the platform time zone (set in Settings > Sending), not the time of each phone. The marker tells you when a phone lives at another hour than the one your schedules use.

A phone marked Time zone unknown runs an older version of the app: update the app on that phone to see its time zone.

Keep the phone running

An SMS gateway is only as reliable as its phones. Android is designed to save battery by putting apps to sleep, which is exactly what a gateway must avoid. The app keeps a permanent connection to your gateway so that messages leave within seconds; for that, the phone has to stay awake.

Do this once for every phone:

1. Keep it plugged in. A phone on its charger is not put into deep sleep by Android. This is the single most effective measure. If your phone offers a battery protection option (charge limited to 80 % or similar), turn it on: it spares the battery that stays on the charger for months.
2. Turn off battery optimisation for the app. In the app, tap Fix battery settings. As long as the dashboard shows Battery optimisation still active, Android can suspend the app and the SMS stop leaving.
3. Allow automatic start. Some manufacturers (Xiaomi, Huawei, Oppo, Samsung and others) block apps from restarting on their own. The app shows an Automatic start card with Open the setting. If the setting cannot be found, look for "Autostart" or "Auto-launch" in the battery settings. The Battery assistant link under the Devices table opens a site that describes the settings of each manufacturer.
4. Leave the permanent notification alone. It is what lets Android keep the app running. Do not swipe the app away from the recent apps, and do not force it to stop.
5. Give it a stable connection. Prefer a Wi-Fi network that does not switch off at night, or mobile data that stays on.

A paired phone restarts the app by itself when it reboots, as long as the manufacturer allows automatic start (point 3) and Start automatically is on in Settings > General, devices. With that setting off, open the app once after each restart of the phone. On a phone whose manufacturer suspends apps as soon as the screen is off despite the points above, Keep the screen on in the same tab keeps the screen lit, dimmed, while the app runs; it drains the battery, so only use it on a phone that stays plugged in.

Options

Every setting of a phone and of its SIM cards, where to change it, and what it does to the rest of the product. All of them are reserved to a Superadmin.

Changes to a quota or to the in-service switch apply to the very next message: there is nothing to restart, on the gateway or on the phone. The per-minute limit of each SIM, the retries and the time zone are sending settings, described in Sending messages.

The Settings > General, devices tab holds the phone settings: Sync interval, in seconds (how often the phone gives news, and so how long before a silent phone goes offline), Strip diacritics, Trim extra whitespace, Uppercase everything (applied to the text when a message leaves for the phone, and shown as such in the history), Start automatically and Keep the screen on. Each phone applies them as soon as they are saved, or when it reconnects. Their details are in Settings.

Troubleshooting