Messaggi di servizio WhatsApp

Un messaggio di servizio è qualsiasi cosa invii che non sia un template pre-approvato: il contenuto libero che un'azienda invia all'interno di una conversazione aperta. POST /v1/whatsapp/messages trasporta esattamente uno dei nove tipi di contenuto per messaggi di servizio, oppure un template. Questa pagina illustra ciò che i nove tipi hanno in comune; la pagina dedicata a ciascun tipo descrive la sua struttura e i suoi limiti specifici.

Una richiesta trasporta esattamente uno tra template o uno di questi nove campi. Una richiesta che non ne contiene nessuno, o ne contiene più di uno, viene rifiutata con un 422.

Un messaggio di servizio, cioè uno qualsiasi dei nove tipi elencati sopra, viene consegnato solo all'interno di una finestra di assistenza clienti di 24 ore aperta. Il contatto apre questa finestra inviando un messaggio o chiamando il tuo numero aziendale, e ogni messaggio successivo da parte sua la reimposta a 24 ore.

Un messaggio di servizio inviato in una finestra chiusa viene rifiutato immediatamente: la richiesta restituisce un 422 E15044 WhatsAppServiceWindowClosed, e nulla viene creato o addebitato. Invia invece un template approvato: raggiunge il contatto indipendentemente dalla finestra, e la sua risposta la riapre. Una finestra che si chiude nell'istante tra l'accettazione e l'invio causa comunque un errore, ma in modo asincrono: il messaggio raggiunge failed con service_window_expired su last_error.

Il controllo al momento dell'accettazione è best effort, non una garanzia: il gate fallisce in aperto, quindi un cache miss o un errore di lettura lascia passare l'invio anziché bloccarlo. Un 202 non è quindi prova che la finestra fosse aperta al momento dell'invio; il segnale definitivo è lo stato del messaggio stesso, non la risposta di accettazione.

Ogni messaggio di servizio richiede anche from, un numero di proprietà del tuo spazio di lavoro. I numeri gestiti da Bird non possono trasportarlo, quindi un messaggio di servizio ha bisogno di un tuo numero collegato per primo; vedi Configurazione del numero di telefono.

Vedi la finestra di assistenza clienti per il ciclo di vita completo: come si apre la finestra, cosa la reimposta e come viene tracciata.

image, video, audio, sticker e document accettano tutti un url che punta a un file che WhatsApp recupera al momento dell'invio, anziché un file che carichi su Bird. Bird verifica la forma dell'URL all'accettazione, prima che qualsiasi cosa venga accodata:

Un URL http viene rifiutato con un 422 all'accettazione, anche se WhatsApp di per sé lo recupererebbe senza problemi. È una policy di Bird, non un limite imposto da WhatsApp.

Bird non verifica la dimensione del file, il suo tipo MIME, né se l'URL è raggiungibile. WhatsApp recupera l'URL direttamente, una volta che invia il messaggio, quindi un URL firmato deve restare valido oltre quel momento, non solo al momento in cui invii la richiesta; un URL privato o scaduto fallisce quando WhatsApp tenta di recuperarlo. WhatsApp inoltre mette in cache un URL recuperato per circa 10 minuti, quindi reinviare lo stesso identico URL entro quella finestra riutilizza il primo fetch anziché effettuarne uno nuovo.

Un invio di media segue lo stesso percorso asincrono di qualsiasi messaggio WhatsApp: Bird restituisce 202 e accetta il messaggio, poi WhatsApp recupera l'URL al momento dell'invio. Se quel fetch fallisce, il messaggio raggiunge failed con media_rejected su last_error, che corrisponde al 131053 di Meta.

media_rejected è un codice generico che copre un file sovradimensionato, un 404, un errore DNS e un tipo MIME errato allo stesso modo; Bird non lo suddivide ulteriormente, quindi non aspettarti un codice distinto per ogni causa.

Un invio di media fallito in modo asincrono viene comunque addebitato. L'addebito avviene quando Bird elabora l'invio accettato, prima che WhatsApp recuperi l'URL, e non esiste un percorso di rimborso una volta che l'addebito è registrato. Pianifica di conseguenza: un messaggio che fallisce successivamente in media_rejected costa quanto uno consegnato con successo.

Un messaggio in entrata trasporta uno degli stessi nove tipi, quindi il campo che leggi corrisponde al tipo usato dal contatto. Le schede contatto vengono lette sullo stesso campo contact_cards sia che il contatto ne abbia condivisa una sia che l'abbia inviata tu. Ricevere messaggi WhatsApp spiega come leggere i messaggi in entrata tramite API, recuperare i media inviati da un contatto e il webhook whatsapp.received.