Enviar imágenes y archivos en Apple Messages

Usa una plantilla de tipo Image o Document para enviar imágenes de productos, instrucciones o un recibo en una conversación abierta con un cliente. Bird obtiene el archivo de origen y lo prepara para Apple durante el procesamiento del mensaje.

Prepara un archivo accesible

Aloja el archivo en una URL HTTPS pública que se pueda obtener sin cookies de navegador ni inicio de sesión. Usa un archivo específico para ese fin que sea seguro exponer en esa URL. Una página de vista previa de una unidad privada no es una URL directa al archivo.

La referencia de envío de mensajes define las restricciones de contenido multimedia:

Mantén la URL disponible mientras se completa el procesamiento. Una URL firmada que expire demasiado pronto puede provocar un fallo después de que el mensaje fue aceptado. Prueba la URL sin un navegador con sesión iniciada y confirma que devuelve el archivo real en lugar de una página HTML.

Configura la plantilla

1. Abre Templates y elige New template > Image o Document.
2. En Content, asigna un Template name al borrador e introduce un Message útil que explique el adjunto.
3. En Apple delivery, configura Attachment URL, File name y Media type. Por ejemplo, un PDF usa un nombre de archivo .pdf y application/pdf.
4. Selecciona el negocio en Personalization y guarda el borrador.
5. Prepara y revisa el mensaje, verificando el cliente y el archivo reales antes de enviar.

Las imágenes de vista previa incluidas no son una fuente de adjuntos para un envío real. Proporciona tu URL prevista de forma explícita.

Sube una vez y reutiliza con attachment_id

El flujo de plantillas anterior envía por source_url cada vez, así que Bird vuelve a obtener el archivo en cada envío. Si envías a través de la API, puedes subir un archivo una sola vez con Subir un adjunto y reutilizarlo en envíos posteriores, lo que evita volver a obtenerlo.

Llama a POST /v1/amb/attachments con una clave API de espacio de trabajo que tenga amb:write, un encabezado Idempotency-Key, que la solicitud requiere, y un cuerpo con from (el ID de Apple Business de la empresa que envía) y, además, una parte file de hasta 25.000.000 de bytes o una source_url de hasta 99.999.999 de bytes. La respuesta devuelve un id que comienza con aat_. Cada llamada sube un adjunto nuevo, incluso si ya subiste ese archivo antes. Si reintentas con la misma Idempotency-Key obtienes el primer resultado sin volver a subir el archivo, así que usa una clave nueva por cada archivo que quieras subir. En un envío posterior, define content.attachments[].attachment_id con ese ID en lugar de source_url. Un adjunto recibido lleva el mismo tipo de ID: léelo desde data.message.content.attachments[].attachment_id en el evento de webhook amb.received y reenvíalo al cliente sin descargar ni volver a subir el archivo tú mismo.

expires_at en un adjunto es la estimación de Bird de cuándo Apple deja de conservar el archivo, no una garantía: Apple documenta una disponibilidad de unos 30 días, que se renueva cada vez que un mensaje posterior reutiliza la referencia. Un envío con un attachment_id cuyo expires_at queda a menos de 24 horas se rechaza antes de llegar a Apple; si ocurre, vuelve a subir el archivo o envíalo por source_url. Una plantilla no puede guardar attachment_id, porque una plantilla dura mucho tiempo y un ID de adjunto no.

Comprueba el resultado

Inspecciona el mensaje enviado y sus eventos, luego abre el adjunto en un dispositivo de prueba Apple autorizado. Comprueba la legibilidad, el nombre del archivo y si el contenido tiene sentido sin el sitio web que lo rodea.

Si el mensaje falla después de ser aceptado, inspecciona su error antes de modificar la plantilla. Las causas habituales incluyen una URL inaccesible, un tipo de medio inesperado, un archivo que supera el límite de tamaño o datos PNG no válidos. Cambiar la extensión de un archivo no convierte su formato.

Para descargar un adjunto entrante en el panel, selecciona su nombre de archivo en la transcripción de la conversación. Necesitas acceso de lectura a Apple Messages en el espacio de trabajo.

Para recuperar un archivo a través de la API, usa Descargar un adjunto con el attachment_id de content.attachments[] del mensaje, o Obtener un adjunto de un mensaje con data.message.id del evento de webhook amb.received y la posición del adjunto, con base cero, dentro del arreglo content.attachments de ese mensaje. En ambos casos, autentícate con una clave API de espacio de trabajo que tenga amb:read; la respuesta contiene los bytes del archivo descifrado. Descarga el archivo cuando llegue el mensaje y guarda tu propia copia, porque la disponibilidad después del período de retención de Apple no está garantizada.