SMS API for Developers: Integration Guide
The GenioSms API is designed for developers who need to integrate high-speed messaging into their own ecosystems, such as Home Automation (IoT), OTP (One-Time Password) verification, or automated notifications.
1. Rapid Integration
We prioritize ease of use. In your control panel, you will find a table of available APIs. To get started:
1. Locate the desired API row.
2. Click the "CODE" button on the right.
3. Access ready-to-use source code snippets in PHP, Python, Perl, and cURL.
For a deep dive into every endpoint, please refer to our [Complete API Documentation].
2. Architecture: Multi-Device Scalability
Our gateway architecture allows for unlimited scaling. You can link as many Android devices as you need to a single list using a PIN.
● Smart Routing: When you trigger an API request, the task is broadcast to all associated devices.
● Load Balancing: Only the first available device will pick up the task and perform the actual SMS transmission. This ensures your infrastructure remains fast even during high-volume bursts.
3. Response Handling & Delivery Tracking
The JSON Response
When an API request is successfully processed by our servers, you will receive a JSON response:
{
"response": "200",
"status_code": "2"
}
● `response: 200`: The request is valid and has been successfully pushed to your connected devices. Note: This confirms delivery to your smartphone, not yet to the final recipient.
● `status_code`: Provides diagnostic info (e.g., code "2" indicates the `over_ip` option is active, allowing requests from any IP).
Status Code Table (`status_code`)
| Code | Status | Description |
|---|---|---|
| 1 | ok_ip | Sending allowed because the IP address is authorized. |
| 2 | ok_over_ip | Sending allowed from any IP becauseover_ip > 0 and `API key = 0`. |
| 3 | api_key_error | Sending not allowed: incorrect API token. |
| 4 | unauthorized_ip | Sending not allowed: IP address not authorized. |
| 5 | param_error | Sending not allowed: invalid parameters (deprecated). |
| 6 | token_or_id_device_error | Sending not allowed: incorrect device token or device ID. |
| 7 | missing_to_number | Sending not allowed: missing destination number. |
| 8 | missing_msg | Sending not allowed: missing message content. |
| 9 | balance_error | Sending not allowed: insufficient credit. |
Real-Time Status via IPN (Webhooks)
To track the actual lifecycle of an SMS (Sent vs. Delivered), you must use the IPN (Instant Process Notification) system.
● Automatic Callbacks: Once enabled, our server makes an HTTP POST request to your script the moment the message status changes.
● Backend Sync: This is the only reliable way to update your database with real-time delivery confirmations.
4. API Security & Access Control
Security is paramount when exposing messaging endpoints.
● IP Whitelisting: Use the "Allow only from IP" option to restrict API access to your specific server address. Any request from an unauthorized IP will be rejected.
● CORS Settings: If you are making requests from a browser or a different domain, ensure you configure the correct domain for cross-domain access.
Video Tutorial: Deploying Your First API Call
In the video below, we walk through:
● API Key Generation: How to create and manage your credentials.
● Code Implementation: Where to find and copy the integration snippets.
● cURL Testing: How to run a live test from your terminal to verify your setup.
[VIDEO: API Creation, Testing, and cURL Implementation]
Key Developer Notes:
● Asynchronous Logic: Remember that the API call to GenioSms is the first step; the IPN callback is the second. Always design your backend to handle these two events.
● JSON Format: All responses are strictly JSON, making them easy to parse in any modern programming environment.
Redundancy: By linking multiple phones, you ensure that even if one device is offline, your API requests will still be fulfilled by others.
