# 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. ## I tipi di contenuto | Tipo | Campo | Cosa trasporta | Quando usarlo | | ----------------------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | [Testo semplice](/docs/guides/whatsapp/message-types/plain-text) | `text` | Un corpo fino a 4096 caratteri, con un'anteprima del link opzionale | stai inviando un messaggio senza allegati | | [Immagini](/docs/guides/whatsapp/message-types/images) | `image` | Un URL pubblico di un'immagine e una didascalia opzionale | stai inviando una foto o un elemento grafico | | [Video](/docs/guides/whatsapp/message-types/video) | `video` | Un URL pubblico di un video e una didascalia opzionale | stai inviando un video clip | | [Audio](/docs/guides/whatsapp/message-types/audio) | `audio` | Un URL pubblico di un file audio, eventualmente visualizzato come nota vocale | stai inviando un messaggio vocale o un clip audio | | [Sticker](/docs/guides/whatsapp/message-types/stickers) | `sticker` | Un URL pubblico di un'immagine WebP | stai inviando uno sticker | | [Documenti](/docs/guides/whatsapp/message-types/documents) | `document` | Un URL pubblico di un file, una didascalia opzionale e un nome file opzionale | stai inviando un PDF, un foglio di calcolo o un altro file | | [Posizione](/docs/guides/whatsapp/message-types/location) | `location` | Latitudine e longitudine, con un nome e un indirizzo opzionali | stai inviando un segnaposto, ad esempio un punto di ritiro | | [Schede contatto](/docs/guides/whatsapp/message-types/contact-cards) | `contact_cards` | Da una a cinque schede contatto, ciascuna con un nome e eventuali numeri, email, siti web o indirizzi | stai condividendo i dati di qualcuno, ad esempio il numero di un collega | | [Messaggi interattivi](/docs/guides/whatsapp/message-types/interactive) | `interactive` | Testo del corpo più un pulsante, un menu, un link, una card o una richiesta di posizione o contatto | vuoi che il destinatario tocchi qualcosa invece di digitare una risposta libera | 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`. ## La finestra di assistenza clienti 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`](/docs/api/errors/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](/docs/guides/whatsapp/phone-number-setup). Vedi [la finestra di assistenza clienti](/docs/knowledge-base/whatsapp/customer-service-window) per il ciclo di vita completo: come si apre la finestra, cosa la reimposta e come viene tracciata. ## Invio di media tramite URL `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: - Non vuoto e analizzabile, con un host e nessuno spazio non codificato - Lo schema è `https` 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. ## Quando il media fallisce 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. ## Leggere ciò che un contatto ha inviato 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](/docs/guides/whatsapp/receiving-whatsapp) spiega come leggere i messaggi in entrata tramite API, recuperare i media inviati da un contatto e il webhook `whatsapp.received`. ## Passaggi successivi - [Inviare messaggi WhatsApp](/docs/guides/whatsapp/sending-whatsapp): l'envelope della richiesta, il modello `202` e i retry sicuri - [Messaggi interattivi](/docs/guides/whatsapp/message-types/interactive): i sei tipi che un destinatario può toccare - [Ricevere messaggi WhatsApp](/docs/guides/whatsapp/receiving-whatsapp): messaggi in entrata, media e il webhook `whatsapp.received` - [Template WhatsApp](/docs/guides/whatsapp/templates): i messaggi che puoi ancora inviare quando la finestra è chiusa ## Related resources - [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video) - [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer) - [WhatsApp message builder](/tools/whatsapp-message-builder) (tool) - [WhatsApp](/products/whatsapp) (product) [Get an implementation brief](/learn/workspace?topic=whatsapp)