Webhooks
Ricevi chiamate in tempo reale sugli aggiornamenti in Smstools.
Cosa sono i webhooks?
I webhooks sono un'estensione di un'API, ma invece che il tuo codice richieda dati da Smstools, Smstools invia dati a te. I dati arrivano in una richiesta web alla tua applicazione. I webhooks sono anche utilizzati per notificare la tua applicazione di eventi come una chiamata in arrivo o un messaggio. Poiché i server di Smstools devono essere in grado di inviare dati alla tua applicazione tramite webhooks, è necessario configurare un server web per ricevere le richieste HTTP in arrivo. È anche necessario specificare l'URL di ogni webhook sul tuo server web in modo che i dati possano essere inviati a ciascuno.
| Tipo | Descrizione |
|---|---|
| delivery_report | Rapporto di consegna dopo ogni messaggio inviato. A volte possono esserci 2 webhooks: prima uno stato 'inviato' e successivamente uno stato 'consegnato' o 'non consegnato'. A volte sono disponibili dettagli aggiuntivi quando il messaggio non viene consegnato. |
| read_report | Conferma di lettura dopo che il messaggio è stato letto. Una conferma di lettura è disponibile solo per la Messaggistica Sociale o utilizzando il link 'Richiedi un rapporto di lettura'. |
| inbox_message | Messaggio in arrivo. Disponibile solo se si utilizza la Messaggistica Sociale o un numero virtuale. |
| call_forwarding | Inoltro di chiamata. Disponibile solo se utilizzi la Messaggistica Sociale o un numero virtuale. |
| add_contact | 1 contatto è stato aggiunto tramite API o software |
| delete_contact | 1 contatto è stato rimosso tramite API o software |
| add_group | Un gruppo è stato aggiunto tramite API o software |
| delete_group | Un gruppo è stato rimosso tramite API o software |
| add_optout | Un contatto è stato aggiunto alla lista di opt-out tramite API o software |
| delete_optout | Un contatto è stato rimosso dalla lista di opt-out tramite API o software |
| funds_purchased | L'account ha completato un nuovo acquisto di crediti |
| insufficient_funds | L'account non ha più crediti disponibili |
| email2sms_received | Email2Sms ha ricevuto un'email e ha tentato di inviarla via SMS |
| Codici di dettaglio del rapporto di consegna | Stato | Spiegazione |
|---|---|---|
| 0 | SUBMITTED | Questo messaggio è stato consegnato con l'operatore ma non abbiamo ricevuto alcun rapporto di consegna. |
| 1 | DELIVERED | Questo messaggio è stato consegnato correttamente. |
| 2 | NOT DELIVERED | Questo messaggio non è stato consegnato. Possibile motivo: il destinatario è fuori dal raggio di rete, problemi di rete, destinatario in paese straniero. |
| 3 | BUFFERED | Questo messaggio è stato consegnato con l'operatore ma non consegnato al destinatario. |
| 4 | REJECTED | Questo messaggio è stato rifiutato dall'operatore. |
| 5 | REJECTED | Informazioni estese di seguito! |
| 9 | UNKNOWN | Non ci sono rapporti di consegna disponibili per questo messaggio. |
| Stato | Spiegazione |
|---|---|
| 10 | Il numero del destinatario non è valido o sconosciuto |
| 11 | Il destinatario è temporaneamente fuori dal raggio dell'operatore di rete |
| 12 | Problema legato al telefono. |
| 13 | Problema di rete dell'operatore |
| 14 | Messaggio scaduto - motivo sconosciuto |
| 15 | Il destinatario è elencato in una lista nera |
| 16 | Problema di contenuto del messaggio |
| 17 | Il destinatario non può essere liquidato |
| 18 | L'operatore ha rifiutato questo a causa di spam |
| 19 | Il sottoscrittore non può ricevere messaggi premium (bloccato dall'operatore) |
| Stato | Spiegazione |
|---|---|
| 2000 | INSUFFICIENT_FUNDS |
| 2001 | TOO_LONG |
| 2002 | TOO_SHORT |
| 2003 | TIMEOUT |
| 2004 | GATEWAY_ISSUES |
| 2005 | INVALID_SENDER |
| 2006 | INVALID_NUMBER |
| 4000 | UNKNOWN |
| 4001 | EMPTY_MESSAGE |
| 4002 | EMPTY_CLIENT |
| 4003 | LOCKED |
| 4004 | BLOCKED |
| 4005 | JOB_FAILED |
| 4006 | DUPLICATE |
| 4007 | INVALID_CONTENT |
Esempio: rapporto di consegna
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "delivery_report",
"username": "myusername",
"timezone": "Europe/Brussels",
"message": {
"messageid": "e1qk89exbzgf6fzfunceym2sd67h88",
"datetime": "2019-01-01 00:00:00",
"datetime_utc": "2019-01-01 00:00:00",
"content": "here comes your message body",
"sender": "yoursender",
"receiver": "32470123456",
"reference": "yourref",
"delivery_code": "1",
"delivery_status": "delivered",
"delivery_status_datetime": "2019-01-01 00:00:00",
"delivery_code_detail": "10",
"delivery_code_detail_description": "Unknown Subscriber"
}
}
]
Esempio: messaggio in arrivo
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "inbox_message",
"username": "myusername",
"timezone": "Europe/Brussels",
"message": {
"id": "12345678",
"date": "2019-01-01 00:00:00",
"date_utc": "2019-01-01 00:00:00",
"sender": "sendernumber",
"receiver": "12345678",
"content": "message content",
"type": "sms",
"file": null,
"processed": 0
},
"isreply": {
"reply": true,
"orig_message_content": "original message content",
"orig_messageid": "985zvqipp73csuuha2079fbshx",
"orig_messagedate": "2019-01-01 00:00:00",
"orig_messagedate_utc": "2019-01-01 00:00:00",
"orig_sender": "32471123456",
"orig_receiver": "12345678",
"orig_reference": ""
}
}
]
Esempio: inoltro di chiamata
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "call_forwarding",
"username": "myusername",
"timezone": "Europe/Brussels",
"message": {
"id": "12345678",
"date": "2019-01-01 00:00:00",
"date_utc": "2019-01-01 00:00:00",
"sender": "sendernumber",
"receiver": "12345678",
"content": "Incoming VOIP Call - Forwarded to XXXXX",
"content_type": "complete",
"type": "call"
}
}
]
Esempio: rapporto di conferma di lettura
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "read_report",
"username": "myusername",
"timezone": "Europe/Brussels",
"message": {
"messageid": "e1qk89exbzgf6fzfunceym2sd67h88",
"datetime": "2019-01-01 00:00:00",
"datetime_utc": "2019-01-01 00:00:00",
"content": "here comes your message body",
"sender": "yoursender",
"receiver": "32470123456",
"reference": "yourref",
"delivery_code": "1",
"delivery_status": "delivered",
"delivery_status_datetime": "2019-01-01 00:00:00",
"read_status": "message_read",
"read_datetime": "2019-01-01 00:01:00"
}
}
]
Esempio: Aggiungi contatto
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "add_contact",
"username": "myusername",
"timezone": "Europe/Brussels",
"contact": {
"action": "add",
"groupid": "12345",
"groupname": "Groupname",
"receiver": "32498123456",
"firstname": "John",
"lastname": "Doe",
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"unsubscribed": null,
"unsubscribe_date": null
}
}
]
Esempio: Elimina contatto
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "delete_contact",
"username": "myusername",
"timezone": "Europe/Brussels",
"contact": {
"action": "delete",
"groupid": "12345",
"groupname": "Groupname",
"receiver": "32498123456",
"firstname": "John",
"lastname": "Doe",
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"unsubscribed": null,
"unsubscribe_date": null
}
}
]
Esempio: Aggiungi gruppo
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "add_group",
"username": "myusername",
"timezone": "Europe/Brussels",
"group": {
"action": "add",
"groupid": "12345",
"groupname": "Groupname"
}
}
]
Esempio: Elimina gruppo
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "delete_group",
"username": "myusername",
"timezone": "Europe/Brussels",
"message": {
"id": "12345678",
"date": "2019-01-01 00:00:00",
"content": "Group deleted",
"type": "group"
}
}
]
Esempio: Aggiungi opt-out
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "add_optout",
"username": "myusername",
"timezone": "Europe/Brussels",
"optout": {
"action": "add",
"id": "1234",
"number": "32498123456",
"memo": "Sample opt-out",
"date": "2025-08-04",
"date_utc": "2025-08-04"
}
}
]
Esempio: Elimina opt-out
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "delete_optout",
"username": "myusername",
"timezone": "Europe/Brussels",
"optout": {
"action": "delete",
"number": "32498123456",
"date": "2025-08-04",
"date_utc": "2025-08-04"
}
}
]
Esempio: Crediti acquistati
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "funds_purchased",
"username": "myusername",
"timezone": "Europe/Brussels",
"funds": {
"order_id": "1234",
"item_amount": 1,
"currency": "eur",
"total_price": 10,
"price_excl": 0,
"purchase_type": "credits",
"payment_mode": "online",
"reference": "Reference",
"date": "2025-08-04 14:33:45",
"date_utc": "2025-08-04 12:33:45"
}
}
]
Esempio: Crediti insufficienti
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "insufficient_funds",
"username": "myusername",
"timezone": "Europe/Brussels",
"funds": {
"item_amount": "0.000",
"item_type": "balance",
"message": "Insufficient funds",
"date": "2025-08-04 14:34:22",
"date_utc": "2025-08-04 12:34:22"
}
}
]
Esempio: Trigger Email2SMS
[
{
"webhook_id": "a9b56720-7adc-4c78-a04d-62521d1d3b09",
"webhook_type": "email2sms_received",
"username": "myusername",
"timezone": "Europe/Brussels",
"email2sms": {
"sender": "[email protected]",
"receiver": {
"group": false,
"receiver": "32498123456"
},
"result": "Success",
"status": "Message Sent",
"email_message_id": "abc123def456",
"sms_message_id": "985zvqipp73csuuha2079fbshx",
"date": "2025-01-01 00:00:00",
"date_utc": "2025-01-01 00:00:00"
}
}
]