Send images and files in Apple Messages

Use an Image or Document template to send product images, instructions, or a receipt in an open customer conversation. Bird fetches the source file and prepares it for Apple during message processing. To attach files from your computer while you reply, see Send a reply.

Prepare a fetchable file

Host the intended file at a public HTTPS URL that can be fetched without browser cookies or a sign-in. Use a purpose-specific file that is safe to expose at that URL. A private drive preview page is not a direct file URL.

The send-message reference defines the media constraints:

Keep the URL available while processing completes. A signed URL that expires too soon can cause a failure after the message was accepted. Test the URL without a signed-in browser and confirm that it returns the actual file rather than an HTML page.

Configure the template

1. Open Templates and choose New template > Image or Document.
2. In Content, give the draft a Template name and enter a useful Message that explains the attachment.
3. In Apple delivery, set Attachment URL, File name, and Media type. For example, a PDF uses a .pdf file name and application/pdf.
4. Select the business in Personalization, then save the draft.
5. Prepare and review the message, checking the actual customer and file before sending.

Bundled preview artwork is not an attachment source for a real send. Supply your intended URL explicitly.

Upload once and reuse it with attachment_id

The template flow above sends by source_url each time, so Bird fetches the file again on every send. When you send through the API instead, you can upload a file once with Upload an attachment and reuse it in later sends, which skips the refetch.

Call POST /v1/amb/attachments with a workspace API key that has amb:write, an Idempotency-Key header, which the request requires, and a body with from (the sending business's Apple business ID) and either a file part, up to 25,000,000 bytes, or a source_url, up to 99,999,999 bytes. The response returns an id starting with aat_. Each call uploads a new attachment, even for a file you uploaded before. Retrying with the same Idempotency-Key returns the first result without uploading again, so use a new key for each file you mean to upload. In a later send, set text.attachments[].attachment_id to that ID instead of source_url. A received attachment carries the same kind of ID: read it from data.message.text.attachments[].attachment_id on the amb.received webhook event, and send it back to the customer without downloading and re-uploading the file yourself.

expires_at on an attachment is Bird's estimate of when Apple stops holding the file, not a guarantee: Apple documents about 30 days of availability, renewed each time a later message reuses the reference. A send with an attachment_id whose expires_at is less than 24 hours away is refused before it reaches Apple; upload the file again, or send it by source_url, if that happens. A template cannot store attachment_id, because a template is long-lived and an attachment ID is not.

Check the result

Inspect the submitted message and events, then open the attachment on an authorized Apple test device. Check legibility, the file name, and whether the content makes sense without the surrounding website.

If the message fails after acceptance, inspect its error before changing the template. Common causes include an inaccessible URL, an unexpected media type, a file above the size limit, or invalid PNG data. Changing a file extension does not convert its format.

To download an incoming attachment in the dashboard, select its filename in the conversation transcript. You need read access to Apple Messages in the workspace.

To retrieve a file through the API, use Download an attachment with the attachment_id from the message's text.attachments[], or Get a message attachment with data.message.id from the amb.received webhook event and the attachment's zero-based position in that message's text.attachments array. Either way, authenticate with a workspace API key that has amb:read; the response contains the decrypted file bytes. Download the file when the message arrives and store your own copy, because availability after Apple's retention period is not guaranteed.