How VeloGate really works

A complete, step-by-step procedure — from account creation to a real SMS leaving a physical SIM. Every step below is live and testable on this server, including a built-in simulator sandbox.

System architecture

🖥️

Your AppREST API + JWT

→queue

⚙️

VeloGate ServerMySQL queue

→poll

📱

Android DeviceVeloGate app + SIM

→radio

📲

Recipientreal SMS

Replies travel the reverse path (SIM → device → inbox), and every state change fires a webhook back to your app.

Create your account & sign in

Register at Create account, or sign in with the default admin account: admin / admin123. Login returns a JWT access token used for every API call.

# Login via API curl -X POST https://smsgate.veloex-inc.com/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"username":"admin","password":"admin123"}'

Register a device

Each Android phone running the VeloGate app is a device with 1–2 SIMs. Register it in Dashboard → Devices, or via API. The server returns a device ID the phone uses when polling.

# Register a device (use your JWT) curl -X POST https://smsgate.veloex-inc.com/3rdparty/v1/devices \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"My Phone","simCount":2}'

Queue an outgoing SMS

Your app sends a POST with E.164 phone numbers and a text payload. The server validates, stores it as Pending, and returns an ID. The phone number is never dialed from the server — the message waits in the MySQL queue.

# Queue an SMS curl -X POST https://smsgate.veloex-inc.com/3rdparty/v1/messages \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"phoneNumbers":["+639171234567"],"textMessage":{"text":"Hello!"},"deviceId":"DEVICE_ID"}'

Device picks up the queue

The phone polls its personal outbox every few seconds. Polling doubles as a heartbeat — the server updates last_active so you can see which devices are alive. Only due, unclaimed messages for that device are returned.

# Device poll (heartbeat + fetch outbox) curl https://smsgate.veloex-inc.com/3rdparty/v1/devices/DEVICE_ID/queue \ -H "Authorization: Bearer YOUR_TOKEN"

Device sends & reports delivery

The phone transmits via its SIM, then reports each state change. Watch the lifecycle:

Pending→ Processed→ Sent→ Delivered or Failed

# Report Sent, then Delivered curl -X PATCH https://smsgate.veloex-inc.com/3rdparty/v1/messages/MESSAGE_ID \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"state":"Sent"}' curl -X PATCH https://smsgate.veloex-inc.com/3rdparty/v1/messages/MESSAGE_ID \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"state":"Delivered"}'

Receive inbound SMS

When a text arrives at the SIM, the phone pushes it to the inbox. Read it in Dashboard → Inbox, or poll the API. Each inbound message fires an sms:received webhook.

# Push inbound (what the phone does) / read inbox (what you do) curl -X POST https://smsgate.veloex-inc.com/3rdparty/v1/inbox \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"deviceId":"DEVICE_ID","phoneNumber":"+63918...","text":"Reply text"}' curl https://smsgate.veloex-inc.com/3rdparty/v1/inbox \ -H "Authorization: Bearer YOUR_TOKEN"

Webhooks — real-time proof

Register a URL per event. The server POSTs signed JSON on every state change and logs each delivery (viewable in the simulator). No external URL? Use the built-in sandbox receiver:

# Your test receiver — no auth needed to RECEIVE POST https://smsgate.veloex-inc.com/api/v1/sandbox/receiverGET https://smsgate.veloex-inc.com/api/v1/sandbox/received

Event	Fires when
`sms:received`	Inbound SMS stored
`sms:sent`	Device reports Sent
`sms:delivered`	Device reports Delivered
`sms:failed`	Device reports Failed

Try it live — no phone needed

Open the Device Simulator Sandbox: a virtual Android phone in your browser. Connect, create a device, start the sender loop, queue an SMS from the dashboard, and watch it get picked up, sent, and delivered — with webhooks landing in the sandbox receiver.

Open simulator sandbox Open dashboard

Go live with a real Android phone

Build the APK: run android-velogate/build-velogate.ps1, or grab it at the download page.
Install on a phone with an active SIM. HTTPS is required by the app (use Let's Encrypt on hosting; plain HTTP only works on local test builds).
In the app: Settings → Cloud Server → enter API URL https://smsgate.veloex-inc.com/api/mobile/v1 and private token vlp-9f3k7Q2mZ8xD4vB6nT (or your account login to attach the phone to your user).
Go to Home → enable Cloud server → tap Offline. The phone self-registers and shows Online — credentials are auto-generated.
From here the phone polls /api/mobile/v1/message, sends via SIM, reports states, and pushes inbound SMS — exactly like the simulator in step 8.

Key API endpoints

Method	Endpoint	Purpose
POST	`/3rdparty/v1/messages`	Queue outgoing SMS
GET	`/3rdparty/v1/devices/{id}/queue`	Device poll + heartbeat
PATCH	`/3rdparty/v1/messages/{id}`	Report Sent/Delivered/Failed
GET	`/3rdparty/v1/messages`	List messages
POST	`/3rdparty/v1/inbox`	Push inbound SMS
GET	`/3rdparty/v1/inbox`	Read inbox
POST	`/3rdparty/v1/webhooks`	Register webhook
GET	`/3rdparty/v1/webhooks/deliveries`	Delivery proof log