MySim SMS — Product Documentation

Product: MySim SMS (My Sim · My SMS)

Platform: Android only

Website: https://mysim-sms.hafiz.live

Admin console: https://sms.console.fitwellhub.com

API server: https://sms.server.fitwellhub.com

This guide explains how to install the Android gateway app, which permissions to allow, and how to send SMS through the API.

1. What MySim SMS is

MySim SMS turns an Android phone with a SIM into a private SMS gateway.

• You install the MySim SMS / Fitwell SMS gateway app on Android
• An admin creates your account and plan in the console
• Your business system (or a script) creates an SMS job via the API
• The phone sends the SMS using the device SIM (normal carrier SMS)
• The phone confirms success back to the server

iOS is not supported. The gateway app is Android-only.

2. Install the Android app

Requirements

• Android phone with an active SIM and SMS balance / plan
• Internet (Wi‑Fi or mobile data) so the app can reach the server
• Account created by an admin (email + password)
• APK file from your MySim SMS provider (sideload install)

Install steps

• On the phone, allow Install unknown apps for your file manager / browser
• Open the APK and install
• Open Fitwell SMS / MySim SMS
• Log in with the email and password from your admin
• Complete the permissions screens (see below)
• Keep the SMS gateway running notification active

After install checklist

• [ ] Logged in successfully
• [ ] SMS permission allowed
• [ ] Notifications allowed
• [ ] Battery unrestricted / not optimized
• [ ] Gateway shows running
• [ ] Plan is active (not expired)

3. Android permissions (required)

How to set battery correctly (important)

• Open phone Settings → Apps → Fitwell SMS / MySim SMS
• Battery → set to Unrestricted (wording varies by brand)
• Or follow the in-app battery / optimization prompt

If battery is restricted, SMS jobs may sit pending until you open the app.

4. Admin setup (before API use)

• Open https://sms.console.fitwellhub.com
• Create a gateway user (full name + email + password)
• Assign a plan (Trial / Monthly / Yearly / Lifetime)
• Activate the user
• Install the app on that user’s phone and log in with the same email
• Use that email as `userEmail` when calling the API

One phone → one gateway user email.

Multiple phones → one user account per phone.

5. API overview

Base URL

https://sms.server.fitwellhub.com

Auth (system / backend only)

X-System-Api-Key: YOUR_SYSTEM_API_KEY

Also accepted: `X-Api-Key` or `Authorization: Bearer YOUR_SYSTEM_API_KEY`.

Keep the system API key on your **server only**. Never put it in the mobile app or a public website.

Health check (no auth)

GET /health

6. Send / schedule an SMS

Important about “schedule”

The API enqueues a job immediately. The connected Android phone sends it as soon as it claims the job.

There is no server-side delayed schedule field yet.

To schedule a message for later:

• Run a cron / queue worker on your side, and
• Call the API at the desired time

Calling the API = “send as soon as the phone is online and gateway is running.”

Recommended: Upsert (create or update pending)

`PUT /api/system/sms-jobs/upsert`

curl -X PUT "https://sms.server.fitwellhub.com/api/system/sms-jobs/upsert" \
  -H "Content-Type: application/json" \
  -H "X-System-Api-Key: YOUR_SYSTEM_API_KEY" \
  -d "{
    \"id\": \"order-otp-1001\",
    \"userEmail\": \"gateway@clinic.com\",
    \"to\": \"+923001234567\",
    \"message\": \"Your OTP is 123456\",
    \"metadata\": { \"source\": \"website\", \"purpose\": \"otp\" }
  }"

Response: job object + `created: true|false`

Create (optional id)

`POST /api/system/sms-jobs`

Same body as above; `id` optional (server generates UUID if omitted).

Still requires `userEmail` or `userId`.

Update a pending job

`PATCH /api/system/sms-jobs/:id`

Only while status is `pending`.

{
  "to": "+923009999999",
  "message": "Updated text"
}

Get job status

`GET /api/system/sms-jobs/:id`

Poll every 5–15 seconds until status is `acked` or `failed`.

HTTP 201/200 on create ≠ SMS delivered.

Success = status `acked`.

7. Example: Node.js enqueue

const SMS_API = "https://sms.server.fitwellhub.com";
const SYSTEM_API_KEY = process.env.MYSIM_SMS_SYSTEM_API_KEY;

async function sendSms({ id, userEmail, to, message, metadata }) {
  const res = await fetch(`${SMS_API}/api/system/sms-jobs/upsert`, {
    method: "PUT",
    headers: {
      "Content-Type": "application/json",
      "X-System-Api-Key": SYSTEM_API_KEY,
    },
    body: JSON.stringify({ id, userEmail, to, message, metadata }),
  });

  if (!res.ok) {
    throw new Error(`SMS enqueue failed ${res.status}: ${await res.text()}`);
  }
  return res.json();
}

// Schedule for later on YOUR server:
// setTimeout(() => sendSms(...), delayMs);
// or use cron / BullMQ / agenda at the desired time.

8. Example: schedule on your side (cron idea)

Your scheduler (cron)  →  at 09:00 call upsert API  →  phone sends SMS via SIM

Pseudo:

// every day 09:00
await sendSms({
  id: `reminder-${patientId}-2026-09-21`,
  userEmail: "clinic-phone@example.com",
  to: "+923001234567",
  message: "Reminder: your appointment is today at 11:00.",
});

9. Operational tips

• Keep the gateway phone charged, online, and gateway running
• Use a stable `id` so retries do not duplicate SMS
• Always pass the correct `userEmail` for the phone that should send
• Check admin console presence if messages stay `pending`
• Carrier SMS charges apply on the SIM

10. Security

• System API key = server secret only
• Use HTTPS only
• Do not call mobile claim/ACK routes from your main app
• Rotate the key if it leaks (server `.env` + restart + update your backends)

11. Support links

*MySim SMS — Android SIM gateway documentation*