Envoyer des images et des fichiers dans Apple Messages

Utilisez un modèle Image ou Document pour envoyer des images de produits, des instructions ou un reçu dans une conversation client ouverte. Bird récupère le fichier source et le prépare pour Apple pendant le traitement du message.

Préparer un fichier accessible

Hébergez le fichier prévu à une URL HTTPS publique accessible sans cookies de navigateur ni connexion. Utilisez un fichier dédié qu'il est sûr d'exposer à cette URL. Une page d'aperçu de lecteur privé n'est pas une URL de fichier directe.

La référence d’envoi de messages définit les contraintes média :

Gardez l'URL disponible pendant le traitement. Une URL signée qui expire trop tôt peut provoquer un échec après l'acceptation du message. Testez l'URL dans un navigateur sans session ouverte et confirmez qu'elle renvoie le fichier réel plutôt qu'une page HTML.

Configurer le modèle

1. Ouvrez Templates et choisissez New template > Image ou Document.
2. Dans Content, donnez un Template name au brouillon et saisissez un Message utile qui explique la pièce jointe.
3. Dans Apple delivery, définissez Attachment URL, File name et Media type. Par exemple, un PDF utilise un nom de fichier .pdf et application/pdf.
4. Sélectionnez l'entreprise dans Personalization, puis enregistrez le brouillon.
5. Préparez et vérifiez le message, en contrôlant le client réel et le fichier avant l'envoi.

L'illustration d'aperçu intégrée n'est pas une source de pièce jointe pour un envoi réel. Indiquez explicitement l'URL souhaitée.

Téléverser une fois et réutiliser avec attachment_id

Le flux de modèle ci-dessus envoie par source_url à chaque fois, donc Bird récupère à nouveau le fichier à chaque envoi. Si vous envoyez plutôt via l'API, vous pouvez téléverser un fichier une seule fois avec Téléverser une pièce jointe et le réutiliser dans les envois suivants, ce qui évite de le récupérer à nouveau.

Appelez POST /v1/amb/attachments avec une clé API d'espace de travail disposant de amb:write, un en-tête Idempotency-Key, que la requête exige, et un corps contenant from (l'ID Apple Business de l'entreprise émettrice) et soit une partie file d'au plus 25 000 000 octets, soit une source_url d'au plus 99 999 999 octets. La réponse renvoie un id commençant par aat_. Chaque appel envoie une nouvelle pièce jointe, même pour un fichier déjà envoyé. Une nouvelle tentative avec la même Idempotency-Key renvoie le premier résultat sans renvoyer le fichier ; utilisez donc une nouvelle clé pour chaque fichier à envoyer. Lors d'un envoi ultérieur, définissez content.attachments[].attachment_id sur cet ID au lieu de source_url. Une pièce jointe reçue porte le même type d'ID : lisez-le dans data.message.content.attachments[].attachment_id sur l'événement webhook amb.received, puis renvoyez-le au client sans télécharger ni retéléverser le fichier vous-même.

expires_at sur une pièce jointe est l'estimation par Bird du moment où Apple cesse de conserver le fichier, pas une garantie : Apple indique une disponibilité d'environ 30 jours, renouvelée chaque fois qu'un message ultérieur réutilise la référence. Un envoi avec un attachment_id dont le expires_at est à moins de 24 heures est refusé avant d'atteindre Apple ; dans ce cas, téléversez à nouveau le fichier ou envoyez-le par source_url. Un modèle ne peut pas stocker attachment_id, car un modèle dure longtemps et un identifiant de pièce jointe non.

Vérifier le résultat

Inspectez le message envoyé et ses événements, puis ouvrez la pièce jointe sur un appareil de test Apple autorisé. Vérifiez la lisibilité, le nom du fichier et si le contenu est compréhensible sans le site web environnant.

Si le message échoue après acceptation, inspectez son erreur avant de modifier le modèle. Les causes courantes incluent une URL inaccessible, un type de média inattendu, un fichier dépassant la limite de taille ou des données PNG non valides. Changer l'extension d'un fichier ne convertit pas son format.

Pour télécharger une pièce jointe entrante dans le tableau de bord, sélectionnez son nom de fichier dans la transcription de la conversation. Vous devez disposer d'un accès en lecture à Apple Messages dans l'espace de travail.

Pour récupérer un fichier via l'API, utilisez Télécharger une pièce jointe avec le attachment_id présent dans content.attachments[] du message, ou Récupérer une pièce jointe de message avec data.message.id issu de l'événement webhook amb.received et la position, en base zéro, de la pièce jointe dans le tableau content.attachments de ce message. Dans les deux cas, authentifiez-vous avec une clé API d'espace de travail disposant de amb:read ; la réponse contient les octets du fichier déchiffré. Téléchargez le fichier dès l'arrivée du message et conservez votre propre copie, car la disponibilité après la période de rétention d'Apple n'est pas garantie.