# Messaggi immagine WhatsApp

Un messaggio immagine contiene un URL pubblico che WhatsApp recupera al momento dell'invio, con una didascalia opzionale sotto.

## Inviare un'immagine

Imposta `image.url`:

**TypeScript**

```typescript
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  image: { url: "https://cdn.example.com/receipt.png" },
});
console.log(msg.id, msg.status);
```

Examples: [TypeScript](/it-it/documentazione/guides/whatsapp/message-types/images.ts.md) · [Python](/it-it/documentazione/guides/whatsapp/message-types/images.py.md) · [Go](/it-it/documentazione/guides/whatsapp/message-types/images.go.md) · [PHP](/it-it/documentazione/guides/whatsapp/message-types/images.php.md) · [CLI](/it-it/documentazione/guides/whatsapp/message-types/images.cli.md) · [MCP](/it-it/documentazione/guides/whatsapp/message-types/images.mcp.md) · [cURL](/it-it/documentazione/guides/whatsapp/message-types/images.curl.md)

La struttura completa aggiunge un `caption` opzionale:

```json
{
  "to": "+16505551234",
  "from": "+13124495648",
  "image": {
    "url": "https://cdn.example.com/receipts/a1b2c3.png",
    "caption": "Your receipt for order A1B2C3"
  }
}
```

`image` non ha il campo `filename`. `from` è obbligatorio in ogni messaggio di servizio: un numero di proprietà del tuo spazio di lavoro, non uno gestito da Bird.

## Limiti

| Campo           | Limite                                          | Applicato da                        |
| --------------- | ----------------------------------------------- | ----------------------------------- |
| Dimensione file | 5 MB                                            | Solo WhatsApp, al fetch (asincrono) |
| Tipo di file    | JPEG o PNG                                      | Solo WhatsApp, al fetch (asincrono) |
| `caption`       | fino a 1024 caratteri                           | Bird, all'accettazione (`422`)      |
| `url`           | assoluto, `https`, con host, senza spazi grezzi | Bird, all'accettazione (`422`)      |

Bird controlla la struttura dell'URL e la lunghezza della didascalia prima di accodare qualsiasi cosa. Non controlla la dimensione o il tipo effettivo del file: solo il fetch di WhatsApp al momento dell'invio può farlo. Consulta la pagina dell'hub [invio di media tramite URL](/docs/guides/whatsapp/message-types#sending-media-by-url) per i dettagli del controllo sulla struttura e [quando i media falliscono](/docs/guides/whatsapp/message-types#when-media-fails) per cosa succede quando il fetch di WhatsApp rifiuta il file.

## Leggere un'immagine in entrata

Un'immagine in entrata contiene lo stesso oggetto `image`, più un `id` e un `mime_type` che Bird ha ricavato recuperando il file. Entrambi sono assenti nella rilettura di un messaggio in uscita, dato che Bird non ha mai recuperato il file inviato. Consulta [Ricezione di immagini WhatsApp](/docs/guides/whatsapp/receiving-whatsapp/images) per la lettura in entrata completa, il payload `whatsapp.received` e gli aspetti a cui prestare attenzione.

## Limiti e modalità di errore

- **La finestra di servizio clienti deve essere aperta.** Le immagini sono messaggi di servizio, recapitabili solo all'interno di una finestra aperta; consulta la pagina dell'hub sulla [finestra di servizio clienti](/docs/guides/whatsapp/message-types#the-customer-service-window).
- **Bird rifiuta `http`; WhatsApp stesso lo recupererebbe.** Questa distinzione, e il resto del controllo sulla struttura dell'URL, si trovano nella pagina dell'hub [invio di media tramite URL](/docs/guides/whatsapp/message-types#sending-media-by-url).
- **Un file troppo grande, un tipo MIME errato o un URL irraggiungibile falliscono tutti allo stesso modo, e dopo l'addebito.** Consulta la pagina dell'hub [quando i media falliscono](/docs/guides/whatsapp/message-types#when-media-fails) per `media_rejected` e il fatto che l'addebito avviene anche in caso di errore.
- **WhatsApp mantiene in cache un URL recuperato per circa 10 minuti.** Reinviare lo stesso URL entro quella finestra restituisce il primo fetch invece di recuperare di nuovo il file; varia l'URL (ad esempio con un parametro di query) per forzarne uno nuovo.

## Passaggi successivi

- [Messaggi di servizio WhatsApp](/docs/guides/whatsapp/message-types): la finestra di servizio clienti e il modello condiviso da ogni messaggio di servizio
- [Video](/docs/guides/whatsapp/message-types/video): la stessa struttura per un video clip
- [Documenti](/docs/guides/whatsapp/message-types/documents): per un PDF, un foglio di calcolo o un altro file
- [Invio di messaggi WhatsApp](/docs/guides/whatsapp/sending-whatsapp): l'envelope della richiesta, il modello `202` e i tentativi sicuri

## 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)