API sms gateway request response e webhook IPN
La sezione API DEV è progettata per chi desidera integrare le funzionalità di GenioSms (come l'invio di codici OTP, notifiche di domotica o alert di sistema) direttamente nel proprio software.
Distribuzione orizzontale del carico di lavoro
GenioSms agisce come un gateway distribuito. Puoi collegare un numero illimitato di smartphone alla stessa lista tramite lo stesso PIN:
Quando invii un comando tramite API, la richiesta viene inoltrata a tutti i dispositivi collegati
Il primo telefono disponibile prende in carico la richiesta ed effettua l'invio materiale dell'SMS
Questo sistema garantisce velocità e ridondanza: se un telefono è occupato o offline, gli altri subentrano immediatamente.
Come integrare il codice
L'integrazione è immediata grazie agli esempi pronti all'uso:
Individua l'API di tuo interesse nella tabella del pannello
Clicca sul pulsante "CODE" a destra della riga
Copia lo snippet di codice nel linguaggio che preferisci (PHP, Perl, Python, ecc.).
Sicurezza e autorizzazioni IP
Per proteggere il tuo account, puoi limitare l'accesso alle API:
Consenti solo da IP: Se attivo, solo l'indirizzo IP del tuo server potrà inviare comandi
Cross-Domain: Configura il dominio corretto se le chiamate provengono da un'applicazione web esterna.
Gestione della risposta (JSON Response)
Ogni chiamata API restituisce un oggetto JSON che conferma la presa in carico del messaggio da parte del gateway:
- GenioApi
- Json
########################################## #### Json response code 200 #### {
"response": "200" ,
"status_code": "2"
}
##########################################
Legenda dei codici:
Response "200": La richiesta è sintatticamente corretta ed è stata consegnata con successo ai dispositivi associati
Attenzione: questo indica che il telefono ha ricevuto il comando, non che l'SMS è già arrivato al destinatario finale
Status_code: Indica il livello di autorizzazione della chiamata.
| Status code | Status msg | Descrizione |
|---|---|---|
| 1 | ok_ip | Invio consentito perché l'indirizzo IP è autorizzato. |
| 2 | ok_over_ip | Invio consentito da qualsiasi IP perché over_ip > 0 e l'API key = 0. |
| 3 | api_key_error | Invio non consentito: token API errato. |
| 4 | unauthorized_ip | Invio non consentito: indirizzo IP non autorizzato. |
| 5 | param_error | Invio non consentito: parametri errati (deprecato). |
| 6 | token_or_id_device_error | Invio non consentito: token del dispositivo o ID device errato. |
| 7 | missing_to_number | Invio non consentito: numero di destinazione mancante. |
| 8 | missing_msg | Invio non consentito: messaggio da inviare mancante. |
| 9 | balance_error | Invio non consentito: credito insufficiente. |
Webhook HTTP Callback IPN (Instant Process Notification)
Quando tramite le API invii una request la response sarà la seguente. Nell'esempio sottostante abbiamo usato cURL.
- GenioApi
- Json
########################################## #### cURL API request #################### C:\Program\Curl\bin>curl -A "GenioSmsBot/1.0 (+http://api.geniosms.net)" --data-urlencod
e "to=3246874140" --data-urlencode "custom=CUSTOM" --data-urlencode "msg=Test Genio Api" --data-urle
ncode "api=178706800164876471483587417320829331" https://geniosms.net/tools/api.pl ########################################## #### Json API response ################### { "GenioApi": { "id_smsout": "2219" ,
"action": "send sms" ,
"response": "200" ,
"response msg": "message delivered to phone, first available phone send. See ipn." ,
"status code": "2" ,
"status msg": "ok_over_ip" ,
"api type": "API" ,
"request over ip": "1" ,
"device id": "122" ,
"device pin": "600680014583" ,
"api id": "100" ,
"from": "00393246874140" ,
"to": "3246874140" ,
"response_date": "2026-09-16 23:11:40" ,
"tmstamp": "1789593100"
}
} ##########################################
La Callback su endpoint IPN
Le callback degli endpoint possono essere di 2 tipi: (ipn_type)
Sent: Messaggio inviato con successo dalla SIM
Delivery: Messaggio consegnato e ricevuto dal destinatario (Rapporto di consegna)
Due Webhook call a endpoint separate, in due processi e momenti differenti, callback chiamata da evento.
L'endpoint ricevera il flusso dati della callback con i seguenti parametri:
- GenioIpn
- PayLoad sent
########################################## #### endpoint webhook param ############## #### ipn_type=SENT ####################### ?status=RESULT_OK&status_code=-1&sim_state_code=5&sim_state_msg=SIM_STATE_READY&insert_date=2026_09_16T23_08_19&insert_tmstamp=1789592902&delivered_to_phone_date=2026_09_16T23_08_21&id_smsout=2219&request_code=70812452&pin=600680014583&custom=CUSTOM&ipn_type=SENT&service_type=API&to=3246874140&from=00393246874140&msg=Test%20Genio%20Api ##########################################
- GenioIpn
- PayLoad delivery
########################################## #### endpoint webhook param ############## #### ipn_type=DELIVERY ################### ?status=RESULT_OK&status_code=-1&sim_state_code=5&sim_state_msg=SIM_STATE_READY&insert_date=2026_09_16T23_42_30&insert_tmstamp=1789594953&delivered_to_phone_date=2026_09_16T23_42_31&id_smsout=2219&request_code=70812452&pin=600680014583&custom=CUSTOM&ipn_type=DELIVERY&service_type=API&to=3246874140&from=00393246874140&msg=Test%20Genio%20Api ##########################################
Parametri endpoint status e status_code
status e status_code Questi parametri indicano lo stato di invio del messaggio, se inviato o meno con i seguenti codici di stato
status_code -1 status RESULT_OK Operation succeeded, SMS sent
status_code 1 status RESULT_ERROR GENERIC_FAILURE Generic failure cause
status_code 4 status RESULT_ERROR NO_SERVICE Failed because service is currently unavailable
status_code 3 status RESULT_ERROR NULL_PDU Failed because no pdu provided
status_code 2 status RESULT_ERROR RADIO_OFF Failed because radio was explicitly turned off
status_code 22 status RESULT_NO_RESOURCES Failed because there are no resourcesf
Parametri endpoint sim_state_code e sim_state_msg
sim_state_code e sim_state_msg Questi parametri indicano lo stato della sim card o della eSim con i seguenti codici di stato
sim_state_code 0 sim_state_msg SIM_STATE_UNKNOWN OUnknown. Signifies that the SIM is in transition between states. For example, when the user inputs the SIM pin under PIN_REQUIRED state, a query for sim status returns this state before turning to SIM_STATE_READY. These are the ordinal value of IccCardConstants State
sim_state_code 1 sim_state_msg SIM_STATE_ABSENT No SIM card is available in the device
sim_state_code 2 sim_state_msg SIM_STATE PIN_REQUIRED Locked, requires the user's SIM PIN to unlock
sim_state_code 3 sim_state_msg SIM_STATE PUK_REQUIRED Locked, requires the user's SIM PUK to unlock
sim_state_code 4 sim_state_msg SIM_STATE NETWORK_LOCKED Locked, requires a network PIN to unlock
sim_state_code 5 sim_state_msg SIM_STATE_READY SIM card state Ready
sim_state_code 6 sim_state_msg SIM_STATE_NOT_READY SIM Card is NOT READY
sim_state_code 7 sim_state_msg SIM_STATE PERM_DISABLED SIM Card Error, permanently disabled
sim_state_code 8 sim_state_msg SIM_STATE CARD_IO_ERROR SIM Card Error, present but faulty
sim_state_code 9 sim_state_msg SIM_STATE CARD_RESTRICTED SIM Card restricted, present but not usable due to carrier restrictions
Parametro API ed endpoint id_smsout
Il parametro id_smsout ci viene restituito dalla response delle API e indica un ID univoco nel flusso dati dentro lo stack queue. Di fondamentale importanza conoscere l'ID del messaggio che stiamo inviando per monitorare lo stato di invio e consegna. le callback dell'endpoin IPN contengono il parametro id_smsout, potremo cosi monitorare lo stato del messaggio inviato tramite il suo id nelle 3 fasi, response API, callback SENT e callback DELIVERY.
Parametro ipn_type callback endpoint
Il parametro ipn_type passato all'endpoint puà essere di 2 tipi SENT e DELIVERY. Si tratta di due callback separate generate in momenti differenti. SENT, evento gernerato quando il dispositivo invia il messaggio sms e DELIVERY, evento che viene generato quando il destinatario del messaggio riceve l'sms. Riceve non vuol dire che l'utente ha aperto il messaggio e lo sta visualizzando, vuol dire che il messaggio sms è arrivato sul telefono.
Scenario request response API e callback IPN
Nella response della request cURL possiamo notare fra i vari parametri il paramentro id_smsout che contiene l'id univoco del messaggio sms che vogliamo inviare.
La callback su endpoint contiene fra i vari parametri lo stesso parametro id_smsout che identifica ogni sms inviato con le API.
Dopo la callback sull'endpoint, facciamo il parsing del payload per estrarre l'id del messaggio e verificare se è stato inviato sent oconsegnato delivery
Nel payload dell'endpoint ipn_type=SENT possiamo notare che i parametri status=RESULT_OK, ipn_type=SENT ci confermano che il messaggio id id_smsout 2219 è stato inviato correttamente.
Nel payload dell'endpoint ipn_type=DELIVERY possiamo notare che i parametri status=RESULT_OK, ipn_type=DELIVERY ci confermano che il messaggio id id_smsout 2219 è stato consegnato correttamente.
Nota: Se un dispositivo è spento o in un luogo non raggiunto dalla rete mobile, il messaggio risulta inviato ma non consegnato, la consegna averrà quando il dispositivo verrà acceso o entrerà in una zona con copertuira.
GitHub api e ipn code
Scarica il codice api e ipn direttamente dal GitHub repository GenioSms. GitHub HTTPS e GitHub CLI
gh repo clone GenioSms/geniosms
Creazione api e test con cURL
In questo video vedremo come generare le chiavi, trovare il codice di esempio e testare un invio reale direttamente da riga di comando utilizzando cURL.
