Inviare immagini e file in Apple Messages

Usa un template Image o Document per inviare immagini di prodotti, istruzioni o una ricevuta in una conversazione aperta con un cliente. Bird recupera il file sorgente e lo prepara per Apple durante l'elaborazione del messaggio.

Preparare un file raggiungibile

Ospita il file desiderato a un URL HTTPS pubblico che possa essere recuperato senza cookie del browser o autenticazione. Usa un file specifico per lo scopo previsto, che sia sicuro da esporre a quell'URL. La pagina di anteprima di un drive privato non è un URL diretto al file.

Il riferimento send-message definisce i vincoli sui contenuti multimediali:

Mantieni l'URL disponibile fino al completamento dell'elaborazione. Un URL firmato che scade troppo presto può causare un errore dopo che il messaggio è stato accettato. Testa l'URL senza un browser con sessione attiva e verifica che restituisca il file effettivo anziché una pagina HTML.

Configura il template

1. Apri Templates e scegli New template > Image o Document.
2. In Content, assegna alla bozza un Template name e inserisci un Message utile che descriva l'allegato.
3. In Apple delivery, imposta Attachment URL, File name e Media type. Ad esempio, un PDF utilizza un nome file .pdf e application/pdf.
4. Seleziona l'azienda in Personalization, quindi salva la bozza.
5. Prepara e rivedi il messaggio, controllando il cliente effettivo e il file prima dell'invio.

Le grafiche di anteprima incluse nel bundle non sono una sorgente valida per un allegato in un invio reale. Fornisci esplicitamente l'URL desiderato.

Carica una volta e riutilizza con attachment_id

Il flusso del template descritto sopra invia ogni volta tramite source_url, quindi Bird recupera di nuovo il file a ogni invio. Se invece invii tramite l'API, puoi caricare un file una sola volta con Carica un allegato e riutilizzarlo negli invii successivi, evitando un nuovo recupero.

Chiama POST /v1/amb/attachments con una chiave API dello spazio di lavoro che dispone di amb:write, un'intestazione Idempotency-Key, richiesta obbligatoriamente, e un corpo con from (l'ID Apple Business dell'azienda mittente) e, in alternativa, una parte file fino a 25.000.000 di byte oppure una source_url fino a 99.999.999 di byte. La risposta restituisce un id che inizia con aat_. Ogni chiamata carica un nuovo allegato, anche per un file già caricato in precedenza. Ripetere la chiamata con la stessa Idempotency-Key restituisce il primo risultato senza ricaricare il file, quindi usa una chiave nuova per ogni file da caricare. In un invio successivo, imposta content.attachments[].attachment_id su quell'ID invece di source_url. Un allegato ricevuto porta lo stesso tipo di ID: leggilo da data.message.content.attachments[].attachment_id nell'evento webhook amb.received e rinviarlo al cliente senza scaricare e ricaricare tu stesso il file.

expires_at su un allegato è la stima di Bird di quando Apple smette di conservare il file, non una garanzia: Apple documenta una disponibilità di circa 30 giorni, rinnovata ogni volta che un messaggio successivo riutilizza il riferimento. Un invio con un attachment_id il cui expires_at è a meno di 24 ore di distanza viene rifiutato prima di raggiungere Apple; in quel caso, carica di nuovo il file o invialo tramite source_url. Un template non può memorizzare attachment_id, perché un template dura a lungo e un ID allegato no.

Verifica il risultato

Esamina il messaggio inviato e gli eventi, quindi apri l'allegato su un dispositivo di test Apple autorizzato. Verifica la leggibilità, il nome del file e se il contenuto ha senso senza il sito web circostante.

Se il messaggio non riesce dopo l'accettazione, esamina l'errore prima di modificare il template. Le cause più comuni includono un URL non raggiungibile, un tipo di media imprevisto, un file che supera il limite di dimensione o dati PNG non validi. Cambiare l'estensione di un file non ne converte il formato.

Per scaricare un allegato in arrivo nella dashboard, seleziona il nome del file nella trascrizione della conversazione. Ti serve l'accesso in lettura ad Apple Messages nello spazio di lavoro.

Per recuperare un file tramite l'API, usa Scaricare un allegato con l'attachment_id presente in content.attachments[] del messaggio, oppure Recuperare un allegato di un messaggio con data.message.id proveniente dall'evento webhook amb.received e la posizione, a base zero, dell'allegato nell'array content.attachments di quel messaggio. In entrambi i casi, autenticati con una chiave API dello spazio di lavoro che dispone di amb:read; la risposta contiene i byte del file decifrato. Scarica il file non appena arriva il messaggio e conserva una copia tua, perché la disponibilità dopo il periodo di conservazione di Apple non è garantita.