> ## Documentation Index
> Fetch the complete documentation index at: https://flow.engineer/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# iMessage message types

> Every message type you can send on iMessage, with the API call and how it looks on the contact's iPhone.

Each type below is one API call. The screenshots are real messages sent through the Flow API, as they appear on the contact's iPhone. Setup, lines and limits are on [iMessage](https://flow.engineer/docs/unified-messaging-api/guides/imessage-agent.md).

Every call takes your key in `Authorization: Bearer` and an `Idempotency-Key`, as in this one:

```bash curl
curl https://api.flow.engineer/v0/conversations/$CONV/basic \
  -H "Authorization: Bearer $FLOW_MESSAGING_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: evt_123:hello" \
  -d '{"text": "Hi! This is a plain iMessage sent through the Flow API."}'
```

A message that goes by SMS or RCS instead (see [SMS and RCS from the same number](https://flow.engineer/docs/unified-messaging-api/guides/imessage-agent.md#6-sms-and-rcs-from-the-same-number)) shows its text and files, without styles, a subject, an effect or your line's contact card.

## Text

Plain text, sent exactly as written, up to 9999 characters.

`POST /v0/conversations/{conversation_id}/basic`

```json
{ "text": "Hi! This is a plain iMessage sent through the Flow API." }
```

![A grey iMessage bubble: Hi! This is a plain iMessage sent through the Flow API.](https://flow.engineer/docs/images/imessage/imessage-text.webp)

## Reaction (tapback)

A reaction on one of the contact's messages. ❤️ 👍 👎 😂 ‼️ ❓ show as tapbacks; any other emoji shows as an emoji reaction. `"emoji": null` removes one you sent. Not in group chats.

`POST /v0/conversations/{conversation_id}/reaction`

```json
{ "message_id": "msg_01JB8ZC3K5M7P9R1T3V5X7Z9C2", "emoji": "❤️" }
```

![A heart tapback on the contact's blue message.](https://flow.engineer/docs/images/imessage/imessage-reaction.webp)

## Inline reply

A reply attached to an earlier message: Messages shows the quoted message above yours. Add `reply_to` to a basic message (or any other kind).

`POST /v0/conversations/{conversation_id}/basic`

```json
{ "text": "Sure, here's everything, replying to your message inline.", "reply_to": "msg_01JB8ZC3K5M7P9R1T3V5X7Z9C2" }
```

![A reply bubble with the contact's quoted message above it.](https://flow.engineer/docs/images/imessage/imessage-inline-reply.webp)

## Subject line and text styles

`imessage.subject` (up to 200 characters) is a bold line above the text. `imessage.styles` styles ranges of the text (`start` and `length` in UTF-16 code units): `bold`, `italic`, `underline`, `strikethrough`, `big`, `small`, or the animations `shake`, `nod`, `explode`, `ripple`, `bloom` and `jitter`.

`POST /v0/conversations/{conversation_id}/basic`

```json
{
  "text": "Bold, italic and underlined text",
  "imessage": {
    "subject": "A subject line",
    "styles": [
      { "start": 0, "length": 4, "style": "bold" },
      { "start": 6, "length": 6, "style": "italic" },
      { "start": 17, "length": 10, "style": "underline" }
    ]
  }
}
```

![A bubble with the bold subject 'A subject line' above bold, italic and underlined text.](https://flow.engineer/docs/images/imessage/imessage-subject-styles.webp)

## Effects

Text sent with a full-screen or bubble effect: `slam`, `loud`, `gentle`, `invisible_ink`, `echo`, `spotlight`, `balloons`, `confetti`, `love`, `lasers`, `fireworks` or `celebration`. The contact can tap Replay to see it again.

`POST /v0/conversations/{conversation_id}/effect`

```json
{ "text": "Sent with confetti", "effect": "confetti" }
```

![Two bubbles, 'Sent with confetti' and 'Sent with slam', each with a Replay link.](https://flow.engineer/docs/images/imessage/imessage-effect.webp)

## Link preview

A link shown as a rich card with the page's image and title. iMessage shows previews by default; `"link_preview": false` sends the link as plain text.

`POST /v0/conversations/{conversation_id}/basic`

```json
{ "text": "https://www.apple.com/iphone/", "link_preview": true }
```

![A link preview card showing iPhones, titled iPhone, from apple.com.](https://flow.engineer/docs/images/imessage/imessage-link-preview.webp)

## Image

One image with an optional caption (up to 1024 characters). Give an HTTPS `url`, or a `file_id` from [`POST /v0/files`](https://flow.engineer/docs/api-reference/files/upload-a-file). Files up to 100 MB.

`POST /v0/conversations/{conversation_id}/basic`

```json
{ "text": "An image", "media": { "type": "image", "url": "https://example.com/fjord.jpg" } }
```

![A photo of a fjord with the caption 'An image'.](https://flow.engineer/docs/images/imessage/imessage-image.webp)

## Video

One video with an optional caption. The contact plays it inline.

`POST /v0/conversations/{conversation_id}/basic`

```json
{ "text": "A video", "media": { "type": "video", "url": "https://example.com/clip.mp4" } }
```

![A video bubble with a play button and the caption 'A video'.](https://flow.engineer/docs/images/imessage/imessage-video.webp)

## Document

A file such as a PDF, with an optional caption. `filename` is the name the contact sees.

`POST /v0/conversations/{conversation_id}/basic`

```json
{ "text": "A PDF document", "media": { "type": "document", "url": "https://example.com/receipt.pdf", "filename": "receipt.pdf" } }
```

![A PDF file bubble with the caption 'A PDF document'.](https://flow.engineer/docs/images/imessage/imessage-document.webp)

## Voice note

An audio file shown with the voice note player and its waveform. Send an mp3, wav, m4a, caf or aac file.

`POST /v0/conversations/{conversation_id}/voice`

```json
{ "url": "https://example.com/note.caf" }
```

![A voice note bubble with a play button, a waveform and its length.](https://flow.engineer/docs/images/imessage/imessage-voice-note.webp)

## Contact card

A contact card the contact taps to save. Send the person's vCard (a `.vcf` file) as a document:

`POST /v0/conversations/{conversation_id}/basic`

```json
{ "text": "A contact card", "media": { "type": "document", "url": "https://example.com/card.vcf", "filename": "card.vcf" } }
```

![A contact card bubble showing a name, a short note and initials, with the caption 'A contact card'.](https://flow.engineer/docs/images/imessage/imessage-contact-card.webp)

On a dedicated line, `imessage.line_contact_card` attaches your line's own card (its name, photo and number) to a text. It needs `text` and cannot go with `media`; a shared line answers `422 unsupported_content`.

```json
{ "text": "Save my contact card so you can find me", "imessage": { "line_contact_card": true } }
```

The `/contact-card` endpoint is for Telegram and WhatsApp; on iMessage it answers `422 unsupported_content`.

## Photo carousel (media group)

2 to 10 images and videos in one message, shown as a stack the contact swipes through, with one optional caption. Each item is an `image` or `video` with a `url` or `file_id`.

`POST /v0/conversations/{conversation_id}/basic`

```json
{
  "text": "A carousel of images",
  "imessage": {
    "media_group": [
      { "type": "image", "url": "https://example.com/fjord.jpg" },
      { "type": "image", "url": "https://example.com/pug.jpg" },
      { "type": "image", "url": "https://example.com/forest.jpg" }
    ]
  }
}
```

![A stack of three photos, a fjord, a pug and a forest, with the caption 'A carousel of images'.](https://flow.engineer/docs/images/imessage/imessage-media-group.webp)

Use it instead of `media`. The `/carousel` endpoint (cards with buttons) is WhatsApp's; on iMessage it answers `422 unsupported_content`.

## Edit

New text for a message you sent, within 15 minutes of sending. Messages marks it Edited. The message that started the conversation cannot be edited.

`PATCH /v0/messages/{message_id}`

```json
{ "text": "This message was edited through the API" }
```

![A bubble reading 'This message was edited through the API', marked Edited.](https://flow.engineer/docs/images/imessage/imessage-edit.webp)

## Unsend

Removes a message you sent, within 2 minutes of sending. The contact sees that a message was unsent.

`DELETE /v0/messages/{message_id}` (no body)

![The line 'Flow Engineer unsent a message' in the conversation.](https://flow.engineer/docs/images/imessage/imessage-unsend.webp)

## Typing and read receipts

These show no message bubble. Both work once the contact wrote, for 5 minutes after your line's last message to them, and not in group chats.

* **Typing** shows the typing indicator until your next message goes or a few seconds pass. `imessage.duration_seconds` (1 to 60) sets how long.

  `POST /v0/conversations/{conversation_id}/typing`

  ```json
  {}
  ```

* **Read** marks the whole conversation as read.

  `POST /v0/conversations/{conversation_id}/read`

  ```json
  {}
  ```

## Related

* [iMessage](https://flow.engineer/docs/unified-messaging-api/guides/imessage-agent.md): lines, who writes first, group chats and limits.
* [Message kinds](https://flow.engineer/docs/unified-messaging-api/concepts/content-types.md): every channel side by side.
* API: [Send a basic message](https://flow.engineer/docs/api-reference/messages/send-a-basic-message-text-or-media-with-a-caption.md), [React to a message](https://flow.engineer/docs/api-reference/messages/react-to-a-message.md), [Send text with an iMessage effect](https://flow.engineer/docs/api-reference/messages/send-text-with-an-imessage-effect.md), [Send a voice note](https://flow.engineer/docs/api-reference/messages/send-a-voice-note.md), [Edit a sent message](https://flow.engineer/docs/api-reference/messages/edit-a-sent-message.md), [Unsend a message](https://flow.engineer/docs/api-reference/messages/unsend-a-message.md).