Afbeeldingen en bestanden versturen in Apple Messages

Gebruik een Image- of Document-template om productafbeeldingen, instructies of een bon te versturen in een open klantgesprek. Bird haalt het bronbestand op en bereidt het voor op Apple tijdens de berichtverwerking.

Een opvraagbaar bestand voorbereiden

Host het beoogde bestand op een openbare HTTPS-URL die opgehaald kan worden zonder browsercookies of aanmelding. Gebruik een doelgericht bestand dat veilig via die URL toegankelijk mag zijn. Een voorbeeldpagina van een privédrive is geen directe bestands-URL.

De send-message-referentie definieert de mediavereisten:

Houd de URL beschikbaar totdat de verwerking is voltooid. Een ondertekende URL die te snel verloopt, kan een fout veroorzaken nadat het bericht is geaccepteerd. Test de URL zonder een ingelogde browser en controleer of deze het daadwerkelijke bestand retourneert in plaats van een HTML-pagina.

Configureer het template

1. Open Templates en kies New template > Image of Document.
2. Geef het concept in Content een Template name en voer een nuttig Message in dat de bijlage toelicht.
3. Stel in Apple delivery de Attachment URL, File name en Media type in. Een PDF gebruikt bijvoorbeeld een .pdf-bestandsnaam en application/pdf.
4. Selecteer het bedrijf in Personalization en sla het concept op.
5. Bereid het bericht voor en controleer het, en controleer de daadwerkelijke klant en het bestand voordat je het verstuurt.

Gebundeld voorbeeldmateriaal is geen bijlagebron voor een echte verzending. Geef je beoogde URL expliciet op.

Eén keer uploaden en hergebruiken met attachment_id

De templateflow hierboven verstuurt elke keer via source_url, dus Bird haalt het bestand bij elke verzending opnieuw op. Verstuur je in plaats daarvan via de API, dan kun je een bestand één keer uploaden met Een bijlage uploaden en het in latere verzendingen hergebruiken, zodat het niet opnieuw wordt opgehaald.

Roep POST /v1/amb/attachments aan met een API-sleutel van de werkruimte die over amb:write beschikt, een verplichte Idempotency-Key-header en een body met from (de Apple Business-ID van het verzendende bedrijf) en ofwel een file-deel van maximaal 25.000.000 bytes, ofwel een source_url van maximaal 99.999.999 bytes. Het antwoord bevat een id die begint met aat_. Elke aanroep uploadt een nieuwe bijlage, ook voor een bestand dat je eerder al uploadde. Een nieuwe poging met dezelfde Idempotency-Key levert het eerste resultaat op zonder opnieuw te uploaden; gebruik dus voor elk bestand een nieuwe sleutel. Stel bij een latere verzending content.attachments[].attachment_id in op die ID in plaats van source_url. Een ontvangen bijlage heeft hetzelfde soort ID: lees die uit data.message.content.attachments[].attachment_id op het amb.received-webhookevent en stuur hem terug naar de klant zonder het bestand zelf te downloaden en opnieuw te uploaden.

expires_at op een bijlage is de schatting van Bird van wanneer Apple het bestand niet meer bewaart, geen garantie: Apple documenteert een beschikbaarheid van ongeveer 30 dagen, die wordt verlengd telkens wanneer een later bericht de referentie hergebruikt. Een verzending met een attachment_id waarvan de expires_at minder dan 24 uur verwijderd is, wordt geweigerd voordat die Apple bereikt; upload in dat geval het bestand opnieuw of verstuur het via source_url. Een template kan geen attachment_id opslaan, omdat een template lang meegaat en een bijlage-ID niet.

Controleer het resultaat

Bekijk het verzonden bericht en de events en open de bijlage op een geautoriseerd Apple-testapparaat. Controleer de leesbaarheid, de bestandsnaam en of de inhoud begrijpelijk is zonder de omringende website.

Als het bericht na acceptatie mislukt, bekijk je de fout voordat je het template aanpast. Veelvoorkomende oorzaken zijn een onbereikbare URL, een onverwacht mediatype, een bestand boven de limiet of ongeldige PNG-data. Het wijzigen van een bestandsextensie converteert het formaat niet.

Om een binnenkomende bijlage in het dashboard te downloaden, selecteer je de bestandsnaam in het gesprekstranscript. Je hebt leestoegang tot Apple Messages in de werkruimte nodig.

Gebruik om een bestand via de API op te halen Een bijlage downloaden met de attachment_id uit content.attachments[] van het bericht, of Een berichtbijlage ophalen met data.message.id uit het amb.received-webhookevent en de nulgebaseerde positie van de bijlage in de content.attachments-array van dat bericht. Authenticeer je in beide gevallen met een API-sleutel van de werkruimte die over amb:read beschikt; het antwoord bevat de ontsleutelde bestandsbytes. Download het bestand zodra het bericht binnenkomt en bewaar je eigen kopie, want beschikbaarheid na Apples bewaartermijn is niet gegarandeerd.