Passa al contenuto principale

Configura webhook stato di consegna

POST 
/api/partner-gateway/v1/webhooks/delivery-status

Registra un URL di callback HTTPS per ricevere notifiche in tempo reale sullo stato di consegna. Una volta configurato, la piattaforma invierà una richiesta HTTP POST al tuo URL di callback ogni volta che si verifica un evento di stato di consegna per i messaggi inviati tramite il tuo account. Gli eventi riportano stati come consegnato, scaduto, non recapitabile e altri esiti specifici del canale su SMS, RCS e WhatsApp. L'URL di callback deve usare HTTPS sulla porta 443 o 8443, non deve contenere credenziali né frammenti e deve risolversi in un indirizzo raggiungibile pubblicamente: gli URL che puntano a indirizzi loopback, privati, link-local o comunque interni vengono rifiutati con 400, così come gli host che non si risolvono. Lo stesso URL riceve gli eventi di tutti i canali, come oggetti JSON il cui eventType ne indica il tipo. DELIVERY (SMS, RCS e WhatsApp) viene inviato all'arrivo della ricevuta di consegna e contiene eventType, channel (SMS, RCS o WHATSAPP), messageId (il customerMessageId che hai ricevuto al momento dell'invio), destination, eventDate, price e l'esito della consegna come statusCode numerico con la relativa description; un evento SMS contiene anche totalParts e numPart, con un evento per ogni parte del messaggio. Un messaggio ancora in transito (accepted su SMS, unknown su RCS e WhatsApp) non ha ancora una ricevuta e non genera alcun evento. READ (RCS e WhatsApp) viene inviato quando il destinatario apre il messaggio e contiene eventType, channel, messageId, destination ed eventDate. INBOUND (RCS e WhatsApp) viene inviato quando il destinatario ti scrive e contiene eventType, channel, messageId (l'id del messaggio nella conversazione), source (il numero del destinatario), destination (il tuo numero WhatsApp o l'id dell'agente RCS), receivedDate, messageType, text e, per i contenuti multimediali, mediaKey. I campi senza valore vengono omessi. I valori di statusCode di un evento DELIVERY sono: 1 accepted (SMS, affidato al carrier senza ancora una ricevuta di ritorno), 2 rejected (SMS), 3 delivered, 4 expired, 5 deleted (SMS), 6 undeliverable (SMS), 9 general error (RCS e WhatsApp), 10 disabled (RCS e WhatsApp), 11 unsupported (RCS e WhatsApp), 12 conversation closed (WhatsApp), 0 unknown. Sono gli stessi codici che la tabella Stati di Consegna nella panoramica dell'API associa ai valori deliveryStatus restituiti da GET /partner-gateway/v1/messages/status e GET /partner-gateway/v1/messages/history, e lo stesso numero che la callback di consegna della piattaforma SMS invia come DELIVERY_STATUS. Il tuo server deve rispondere con un codice di stato 2xx entro 5 secondi per confermare la ricezione. Se il tuo endpoint non è raggiungibile o restituisce un errore, la piattaforma ritenta la notifica fino a un totale di 5 tentativi, a distanza di almeno 5 minuti per gli SMS e di almeno 10 minuti per RCS e WhatsApp, per i messaggi inviati negli ultimi 10 giorni. Uno stesso evento può arrivare più di una volta, quindi elabora gli eventi in modo idempotente. Per ogni account può essere attivo un solo URL webhook. Se un webhook è già configurato, questo endpoint restituisce 409 Conflict. In tal caso, usa PUT /webhooks/delivery-status per aggiornare l'URL esistente, oppure DELETE /webhooks/delivery-status per rimuoverlo prima. Restituisce 400 se il corpo della richiesta non è valido: callbackUrl mancante o malformato, uno schema diverso da HTTPS, una porta diversa da 443 o 8443, oppure un host non raggiungibile pubblicamente. Restituisce 401 se la chiave API è mancante o non valida. Restituisce 500 in caso di errore interno.

Richiesta​

Risposte​

Webhook configurato con successo

Ultimo aggiornamento il