Getting Started with Bonrix SMS Server 4 HTTP API: A Quick GuideBonrix SMS Server 4 is a lightweight, Windows-based SMS gateway that lets you send and receive SMS messages via connected GSM/3G/4G modems or Android phones. Its HTTP API provides a simple, REST-like interface that developers can call from web applications, scripts, or automation tools to dispatch messages, check status, and manage incoming messages. This guide walks through installation basics, HTTP API structure and endpoints, authentication, common request examples, error handling, and practical tips for deployment.
1. What you need before you begin
- A Windows machine (server or desktop) to host Bonrix SMS Server 4.
- A supported GSM/3G/4G USB modem or an Android phone compatible with the Bonrix client for connecting as an SMS gateway.
- Bonrix SMS Server 4 installed and configured to recognize your modem/phone and be able to send/receive SMS.
- Network access to the Bonrix machine from your application (HTTP port used by Bonrix must be reachable).
- Basic knowledge of HTTP requests (GET/POST) and URL encoding.
2. Understanding the HTTP API basics
Bonrix exposes a simple web API over HTTP. The API is typically accessible at the Bonrix server’s IP address and a configured port (for example: http://192.168.1.100:8800). The core idea: your application makes HTTP requests to specific endpoints with query parameters or POST form data to instruct the server to send messages, fetch incoming messages, or check status.
Key characteristics:
- Endpoints are usually simple paths like /sendsms or /getsms.
- Parameters include phone number, message text, sender ID, and optional settings (unicode, flash, etc.).
- Responses are plain text or basic status codes you can parse in your app.
Example base URL: http://
3. Common API endpoints and parameters
(Note: exact endpoint names and parameter names may vary slightly depending on Bonrix version or local configuration. Verify in your installed server’s documentation or web interface.)
-
/sendsms — send a single SMS
- Parameters commonly used:
- username / password — credentials if HTTP auth is enabled
- to — destination phone number (E.164 format recommended, e.g., +15551234567)
- text — message content (URL-encoded)
- from — sender ID or short code (if supported by your modem/network)
- unicode — flag for Unicode messages (1 = enabled)
- flash — flag for flash SMS (1 = enabled)
- Example request (GET):
- Parameters commonly used:
-
/sendsms_bulk or /sendsms_multiple — send same message to multiple recipients
- Often accepts a comma-separated list for the
toparameter or multipletoparameters.
- Often accepts a comma-separated list for the
-
/getsms or /inbox — retrieve incoming messages
- Parameters:
- lastid — fetch messages after a specific message ID to avoid duplicates
- Returns a list of messages with IDs, sender numbers, timestamps, and text.
- Parameters:
-
/status or /delivery — check delivery status for a sent message
- Parameters:
- messageid — ID returned when sending
- Returns delivery state: pending, delivered, failed, etc.
- Parameters:
-
/balance — check SMS credits (if your setup uses a provider that supports credit checking)
4. Authentication and security
Bonrix’s HTTP API may be protected in several ways:
- HTTP Basic Authentication: username/password parameters or browser-level auth.
- Token-based keys configured in server settings.
- IP whitelisting: allow only specific IP addresses to call the API.
- Network-level controls: run Bonrix behind a VPN or on an internal-only network.
Always:
- Use HTTPS or an SSH tunnel if the Bonrix server will be reached across untrusted networks (Bonrix’s built-in interface often runs HTTP only; consider fronting it with a reverse proxy that provides TLS).
- Avoid embedding plaintext credentials in client-side code or public repositories.
- Limit permissions (e.g., separate account for sending vs. administrative functions).
5. Sending your first SMS — example requests
Below are common examples showing how to send SMS via HTTP GET and POST. Replace the host, parameters, and credentials with your values.
GET example:
http://192.168.1.100:8800/sendsms?to=%2B15551234567&text=Hello%20from%20Bonrix&from=MyApp POST example (application/x-www-form-urlencoded):
POST /sendsms HTTP/1.1 Host: 192.168.1.100:8800 Content-Type: application/x-www-form-urlencoded Content-Length: <length> to=%2B15551234567&text=Hello+from+Bonrix&from=MyApp If authentication is required, include credentials per your server settings (username/password query params or HTTP Basic Auth).
6. Handling Unicode and message length
- For messages containing non-Latin characters (e.g., Cyrillic, Chinese), enable Unicode mode (commonly
unicode=1) so the server sends messages using UCS-2 encoding. Unicode messages have a smaller per-SMS character limit (70 chars per segment vs 160 for GSM 7-bit). - Long messages are automatically segmented into multiple SMS parts (concatenation) if supported; check how Bonrix reports message IDs and parts for tracking.
7. Parsing responses and tracking delivery
- Simple responses may be plain text indicating success and a message ID (e.g., OK:12345) or an error description.
- For robust systems, log the returned message ID and periodically call /status or handle delivery report callbacks (if Bonrix can POST delivery reports to your endpoint) to track final delivery state.
- Implement retries for transient failures (network timeouts, temporary modem issues) with exponential backoff and idempotency (so you don’t double-send).
8. Receiving inbound messages
- Polling: call /getsms with last known message ID to fetch new messages periodically.
- Webhook/callback: if Bonrix supports pushing incoming messages, configure a callback URL in the server so incoming SMS are POSTed to your app.
- Parse inbound messages to extract sender number, received timestamp, message text, and message ID.
9. Common issues and troubleshooting
- Modem not detected: ensure drivers are installed, correct COM port selected, and no other application is occupying the port.
- SMS not delivered: check network signal, SIM balance, and whether your sender ID is allowed by the network/carrier.
- Encoding problems: ensure correct unicode flag for non-Latin text and URL-encode message bodies.
- Firewall/port blocking: verify the Bonrix HTTP port is open and accessible from your application host.
- Authentication failures: confirm credentials, IP whitelist, and whether Basic Auth or query-params are required.
10. Practical tips for production
- Use a reverse proxy (Nginx/IIS) in front of Bonrix to add HTTPS, basic auth, rate limiting, and logging.
- Monitor modem health and signal strength; consider multiple modems/phones for redundancy and higher throughput.
- Respect carrier rules and local regulations for sender IDs and bulk messaging; implement opt-in/opt-out handling.
- Back up Bonrix configuration regularly and document COM port mappings and SIM information.
- Test with different carriers and regions to ensure message formatting and routing works correctly.
11. Example integration (pseudo-code)
Simple curl example to send SMS:
curl "http://192.168.1.100:8800/sendsms?to=%2B15551234567&text=Test%20message&from=MyApp" Node.js (fetch) pseudo-code:
const url = 'http://192.168.1.100:8800/sendsms'; const params = new URLSearchParams({ to: '+15551234567', text: 'Hello from Bonrix', from: 'MyApp' }); fetch(`${url}?${params.toString()}`) .then(r => r.text()) .then(console.log) .catch(console.error); 12. Where to find more information
- Refer to the Bonrix SMS Server 4 documentation packaged with your installation for exact endpoint names, parameter lists, and server-specific configuration options.
- Bonrix’s web interface often includes API usage examples and logs that help with debugging.
If you want, I can:
- Draft ready-to-use code for your platform (Python, PHP, Node.js, etc.) using your Bonrix host, port, and authentication details.
- Help map your exact Bonrix server’s API by inspecting a sample response if you paste it here.
Leave a Reply