Bilder und Dateien in Apple Messages senden

Verwenden Sie ein Image- oder Document-Template, um Produktbilder, Anleitungen oder eine Quittung in einer offenen Kundenkonversation zu senden. Bird ruft die Quelldatei ab und bereitet sie während der Nachrichtenverarbeitung für Apple auf.

Eine abrufbare Datei vorbereiten

Hosten Sie die gewünschte Datei unter einer öffentlichen HTTPS-URL, die ohne Browser-Cookies oder Anmeldung abgerufen werden kann. Verwenden Sie eine zweckgebundene Datei, die unter dieser URL bedenkenlos zugänglich ist. Eine Vorschauseite eines privaten Laufwerks ist keine direkte Datei-URL.

Die Send-Message-Referenz definiert die Medienanforderungen:

Halten Sie die URL verfügbar, bis die Verarbeitung abgeschlossen ist. Eine signierte URL, die zu früh abläuft, kann einen Fehler verursachen, nachdem die Nachricht bereits akzeptiert wurde. Testen Sie die URL ohne angemeldeten Browser und prüfen Sie, ob sie die eigentliche Datei zurückgibt und nicht eine HTML-Seite.

Vorlage konfigurieren

1. Öffnen Sie Templates und wählen Sie New template > Image oder Document.
2. Geben Sie unter Content dem Entwurf einen Template name und tragen Sie eine hilfreiche Message ein, die den Anhang erklärt.
3. Setzen Sie unter Apple delivery die Felder Attachment URL, File name und Media type. Für ein PDF verwenden Sie beispielsweise einen .pdf-Dateinamen und application/pdf.
4. Wählen Sie das Unternehmen unter Personalization aus und speichern Sie den Entwurf.
5. Bereiten Sie die Nachricht vor und prüfen Sie sie, indem Sie den tatsächlichen Kunden und die Datei vor dem Senden kontrollieren.

Mitgelieferte Vorschaugrafiken sind keine Anhangquelle für einen echten Versand. Geben Sie Ihre gewünschte URL explizit an.

Einmal hochladen und mit attachment_id wiederverwenden

Der oben beschriebene Template-Ablauf sendet jedes Mal per source_url, sodass Bird die Datei bei jedem Versand erneut abruft. Wenn Sie stattdessen über die API senden, können Sie eine Datei einmal mit Anhang hochladen hochladen und in späteren Sendungen wiederverwenden, sodass der erneute Abruf entfällt.

Rufen Sie POST /v1/amb/attachments mit einem Workspace-API-Schlüssel auf, der über amb:write verfügt, mit einem erforderlichen Idempotency-Key-Header und einem Body mit from (der Apple-Business-ID des sendenden Unternehmens) sowie entweder einem file-Teil mit bis zu 25.000.000 Byte oder einer source_url mit bis zu 99.999.999 Byte. Die Antwort enthält eine id, die mit aat_ beginnt. Jeder Aufruf lädt einen neuen Anhang hoch, selbst für eine zuvor hochgeladene Datei. Eine Wiederholung mit demselben Idempotency-Key liefert wieder das erste Ergebnis, ohne erneut hochzuladen; verwenden Sie daher für jede hochzuladende Datei einen neuen Schlüssel. Setzen Sie bei einem späteren Versand content.attachments[].attachment_id anstelle von source_url auf diese ID. Ein empfangener Anhang trägt dieselbe Art von ID: Lesen Sie sie aus data.message.content.attachments[].attachment_id im Webhook-Ereignis amb.received aus und senden Sie sie an den Kunden zurück, ohne die Datei selbst herunterzuladen und erneut hochzuladen.

expires_at an einem Anhang ist die Schätzung von Bird, wann Apple die Datei nicht mehr vorhält, keine Garantie: Apple dokumentiert eine Verfügbarkeit von etwa 30 Tagen, die sich jedes Mal verlängert, wenn eine spätere Nachricht die Referenz wiederverwendet. Eine Sendung mit einer attachment_id, deren expires_at weniger als 24 Stunden entfernt ist, wird abgelehnt, bevor sie Apple erreicht; laden Sie die Datei in diesem Fall erneut hoch oder senden Sie sie per source_url. Ein Template kann keine attachment_id speichern, weil ein Template langlebig ist und eine Anhangs-ID nicht.

Ergebnis prüfen

Prüfen Sie die gesendete Nachricht und die Ereignisse und öffnen Sie den Anhang auf einem autorisierten Apple-Testgerät. Achten Sie auf Lesbarkeit, den Dateinamen und darauf, ob der Inhalt ohne die umgebende Website verständlich ist.

Falls die Nachricht nach der Annahme fehlschlägt, prüfen Sie den Fehler, bevor Sie das Template ändern. Häufige Ursachen sind eine nicht erreichbare URL, ein unerwarteter Medientyp, eine Datei über dem Größenlimit oder ungültige PNG-Daten. Das Ändern einer Dateiendung konvertiert nicht das Format.

Um einen eingehenden Anhang im Dashboard herunterzuladen, wählen Sie seinen Dateinamen im Konversationsverlauf aus. Sie benötigen Lesezugriff auf Apple Messages im Workspace.

Um eine Datei über die API abzurufen, verwenden Sie Einen Anhang herunterladen mit der attachment_id aus content.attachments[] der Nachricht oder Einen Nachrichtenanhang abrufen mit data.message.id aus dem Webhook-Ereignis amb.received und der nullbasierten Position des Anhangs im content.attachments-Array dieser Nachricht. In beiden Fällen authentifizieren Sie sich mit einem Workspace-API-Schlüssel, der über amb:read verfügt; die Antwort enthält die entschlüsselten Dateibytes. Laden Sie die Datei herunter, sobald die Nachricht eintrifft, und speichern Sie eine eigene Kopie, da die Verfügbarkeit nach Apples Aufbewahrungsfrist nicht garantiert ist.