在 Apple Messages 中发送图片和文件

使用 Image 或 Document 模板，在开放的客户对话中发送产品图片、说明或收据。Bird 在处理消息时获取源文件，并将其准备为 Apple 所需的格式。

准备可获取的文件

将目标文件托管在公开的 HTTPS URL 上，确保无需浏览器 Cookie 或登录即可获取。使用可在该 URL 安全公开的专用文件。私人网盘预览页不是文件的直接 URL。

发送消息参考规定了以下媒体限制：

在处理完成之前，保持 URL 可用。签名 URL 过早过期，可能导致消息已受理后仍处理失败。在未登录的浏览器中测试 URL，确认返回的是实际文件，而不是 HTML 页面。

配置模板

1. 打开 Templates，选择 New template > Image 或 Document。
2. 在 Content 中为草稿填写 Template name，并输入能说明附件内容的 Message。
3. 在 Apple delivery 中设置 Attachment URL、File name 和 Media type。例如，PDF 使用 .pdf 文件名和 application/pdf。
4. 在 Personalization 中选择商家，然后保存草稿。
5. 准备并检查消息，在发送前核对实际客户和文件。

随附的预览图片不是实际发送时的附件来源。请明确提供目标 URL。

上传一次，通过 attachment_id 重复使用

上述模板流程每次都通过 source_url 发送，因此 Bird 每次发送都会重新获取文件。如果改为通过 API 发送，可以使用上传附件将文件上传一次，并在后续发送中重复使用，从而无需重新获取。

使用具有 amb:write 权限的工作区 API 密钥调用 POST /v1/amb/attachments，请求必须携带 Idempotency-Key 请求头，并在请求体中提供 from（发送方企业的 Apple Business ID），以及一个不超过 25,000,000 字节的 file 部分或一个不超过 99,999,999 字节的 source_url 二选一。响应会返回一个以 aat_ 开头的 id。每次调用都会上传一个新附件，即使是之前上传过的文件也是如此。使用相同的 Idempotency-Key 重试会返回第一次的结果而不会重新上传，因此每个要上传的文件都应使用新的密钥。在之后的发送中，将 content.attachments[].attachment_id 设置为该 ID，而不是 source_url。收到的附件带有同类型的 ID：从 amb.received webhook 事件中的 data.message.content.attachments[].attachment_id 读取该 ID，然后直接将其回发给客户，无需自行下载和重新上传文件。

附件上的 expires_at 是 Bird 对 Apple 何时停止保存该文件的估计，而非保证：Apple 文档说明可用期约为 30 天，每当后续消息重复使用该引用时都会续期。如果发送时使用的 attachment_id 的 expires_at 距现在不到 24 小时，请求会在到达 Apple 之前被拒绝；遇到这种情况，请重新上传文件，或通过 source_url 发送。模板不能保存 attachment_id，因为模板会长期存在，而附件 ID 不会。

检查结果

查看已提交的消息和事件，然后在获授权的 Apple 测试设备上打开附件。检查可读性、文件名，以及脱离网站上下文后内容是否仍清楚。

如果消息在受理后失败，请先查看错误，再修改模板。常见原因包括 URL 无法访问、媒体类型不符、文件超过大小限制或 PNG 数据无效。更改文件扩展名不会转换文件格式。

要在控制台中下载收到的附件，请在对话记录中选择其文件名。你需要拥有工作区中 Apple Messages 的读取权限。

要通过 API 获取文件，可使用下载附件，并提供消息 content.attachments[] 中的 attachment_id；也可使用获取消息附件，并提供来自 amb.received webhook 事件的 data.message.id，以及该附件在该消息 content.attachments 数组中从零开始的位置。两种方式都需要使用具有 amb:read 权限的工作区 API 密钥进行身份验证；响应中包含解密后的文件字节。消息到达后请下载文件并保存自己的副本，因为超过 Apple 的保留期限后无法保证文件仍然可用。