Documentazione
Sign inGet started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

Ricevere immagini WhatsApp

Una foto o un'immagine inviata da un contatto arriva come messaggio in entrata con image: un riferimento al file che Bird ha archiviato per te, più l'eventuale didascalia digitata sotto.

Cosa contiene un'immagine in entrata

Esempio di codice
{
  "id": "wam_01kya19eknftrs2s6p82asmvnh",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "image": {
    "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
    "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kya19eknftrs2s6p82asmvnh/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
    "mime_type": "image/jpeg",
    "caption": "Is this the right part?"
  },
  "created_at": "2026-08-25T09:04:11Z"
}
CampoCosa contiene
idIl file archiviato, da passare come media_id quando scarichi i byte
urlUn URL Bird, da scaricare con la tua chiave API
mime_typeIl tipo di media che WhatsApp ha riportato per il file, ad esempio image/jpeg
captionIl testo che il contatto ha digitato sotto l'immagine; assente se non ne ha inviato
id e mime_type compaiono solo su un'immagine in entrata: Bird li ricava entrambi scaricando il file, e non ha mai archiviato quello che hai inviato tu. Un'immagine in uscita viene riletta con il url che hai fornito e senza id.
Tratta mime_type come un'indicazione di WhatsApp piuttosto che come una garanzia, e basa la logica su di esso anziché sull'estensione del file in url, che non ne contiene.

Scaricare i byte

url e id puntano entrambi allo stesso file archiviato: passa l'ID del messaggio e il id del media al metodo media del canale, in qualsiasi SDK, nella CLI o in cURL. La sezione scaricare media in entrata dell'hub riporta quella chiamata in ogni linguaggio, insieme alle regole di redirect e header che segue.
Il messaggio e il suo media scadono insieme, 30 giorni dopo l'arrivo del messaggio; la sezione scaricare media in entrata dell'hub gestisce quella finestra e ciò che le letture restituiscono una volta trascorsa. Archivia qualsiasi immagine che ti serve più a lungo finché il messaggio è ancora leggibile.

Il payload del webhook

whatsapp.received porta il ramo image sull'envelope dell'evento, riferimento media incluso:
Esempio di codice
{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:04:11.118Z",
  "data": {
    "whatsapp_id": "wam_01kya19eknftrs2s6p82asmvnh",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "image": {
      "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
      "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kya19eknftrs2s6p82asmvnh/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
      "mime_type": "image/jpeg",
      "caption": "Is this the right part?"
    },
    "tags": null,
    "metadata": null
  }
}
Il webhook si attiva all'arrivo del messaggio, che è anche il momento in cui inizia la finestra di conservazione: un endpoint che accoda il download anziché eseguirlo inline ha l'intera finestra per recuperare.

Aspetti da tenere d'occhio

  • La didascalia appartiene al contatto. Arriva come testo semplice senza formattazione né informazioni sulle entità, quindi renderizzala come testo.
  • Un'immagine per messaggio. Un contatto che invia più foto produce più messaggi in entrata, ciascuno con il proprio id e il proprio riferimento media. Raggruppali per from e orario di arrivo; nessun array li raccoglie.

Passi successivi

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Guarda la guidaConnecting WhatsApp to Bird: from buying a number to a live channelComprendi il concettoWhat is the 24-hour customer service window on WhatsApp?Usa lo strumentoWhatsApp message builderEsplora la funzionalitàWhatsApp
Prova l'esercitazione e ottieni un brief di implementazione