Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Send rich links and locations in Apple Messages

Use a Rich link template when a customer needs a clear destination and visual context. Use Location when the action is finding a place. Apple's conversation design standards expect web addresses, including links to videos, to arrive as rich links.

Bird sends a web address in a text message as a rich link built from the page's own title and image: its og:image, then its icon, then the largest image on the page. Only an address that starts with https://, http:// or www. becomes a rich link, so write www.example.com/visit rather than example.com/visit. Bird loads every page over HTTPS. If a page does not load, or has no title or usable image, the message ends send_failed, and so does a message with more than 20 links. To recover, fix the page or the address, or remove the link, and send the message again. The Send message reference has the full rules. When a text template or a conversation reply contains a link, set Link preview layout to Icon to show a small image beside the title instead of a full-width card. Bird tries the page's icon first, and a page without a usable icon shows its og:image or another page image at that small size. Use a Rich link template when you want to choose the title and image yourself.

You need a template draft, a connected business, and an open conversation for a real send. A business in Testing can send in test conversations.

  1. Open Templates and create a Rich link.
  2. In Content, enter the Title and Message. Name the destination or the action the customer can complete there.
  3. In Apple delivery, set Link preview source to My image and title.
  4. Enter Destination URL and Preview image. Use a PNG, JPEG, GIF, or WebP file that meets the media requirements.
  5. Set Image layout. Choose Icon for a logo.
  6. If you include a video, supply Optional video and Video media type. Keep the video accessible to Apple when the customer opens it.
  7. Save, then prepare and review the message.

Apple picks the layout from the image's shape and width, so Bird resizes or crops your image to match the one you choose:

  • Icon shows a small image beside the title. A logo shown as a large card takes up much of the conversation, so use an icon for it.
  • Square crops the image to a square from its center.
  • Large shows a wide image above the title, for photos and product images. Bird crops a square or portrait image to a wide rectangle.
  • Automatic keeps the image's proportions and lets Apple pick the layout: an image under 150 px wide shows as an icon, a wider square as a square, and a wider rectangle as a large image. Bird converts the image as the media requirements describe.

Square enlarges an image whose shorter side is under 240 px, and Large one narrower than 240 px, which can blur it.

Use a destination that remains useful when the preview cannot load. Avoid putting customer secrets or authentication tokens into a URL to personalize the card.

Use an Apple-generated preview

For supported Apple content, choose Apple-generated preview under Link preview source, then enter Apple content URL. For Apple Music, enter the two-letter Store region appropriate to the content.

Preparation checks with Apple that it can build the preview, and Apple builds it again when the message is sent. The browser cannot reproduce the device-generated card, so inspect it on an authorized Apple device before using the template with customers.

An unsupported URL or unavailable provider configuration can cause preparation to fail. Read the error and use a supported Apple content URL or an ordinary rich link with your own image and title.

Share a location

Share a place as a Location template. Enter a title and explanatory message, such as the name of the store the customer should visit. Under Apple delivery, provide Apple Maps URL, or supply both Latitude and Longitude. Bird sends either one as an Apple Maps link, so the customer sees a map preview.

Verify the map pin and directions on a device. A valid coordinate pair can still point to the wrong entrance or a different branch. Use the location's actual customer-facing name so the recipient can recognize it.

Verify the destination

Complete a test send, open the card on the Apple device, and follow its action. Check the final destination, language, image, and sign-in experience. For a media failure after acceptance, inspect Messages and events.

For an App Clip or a published iMessage app, follow app experiences.