---
title: Message Effects | API Docs
description: Add iMessage screen and bubble effects to your messages.
---

Message effects are iMessage-specific visual animations that play when a recipient opens your message. They add personality and emphasis to conversations. For the basics of sending messages, see [Sending Messages](/guides/messaging/sending-messages/index.md).

The `effect` field is an object with a `type` (`screen` or `bubble`) and a `name`:

```
"effect": { "type": "screen", "name": "confetti" }
```

## Screen effects

Screen effects fill the entire screen with an animation. Use `"type": "screen"`:

| Name             | Description                                        |
| ---------------- | -------------------------------------------------- |
| `confetti`       | Colorful confetti falls from the top of the screen |
| `fireworks`      | Fireworks explode across the screen                |
| `lasers`         | Laser beams sweep across the screen                |
| `sparkles`       | Sparkles glitter across the screen                 |
| `celebration`    | Streamers and confetti burst out                   |
| `hearts`         | Hearts float up from the message                   |
| `love`           | A large heart floats up from the message           |
| `balloons`       | Balloons float up from the bottom                  |
| `happy_birthday` | A “Happy Birthday” banner with confetti            |
| `echo`           | The message echoes and repeats across the screen   |
| `spotlight`      | A spotlight illuminates the message                |

## Bubble effects

Bubble effects animate the message bubble itself. Use `"type": "bubble"`:

| Name        | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| `slam`      | The message slams down onto the screen                         |
| `loud`      | The message grows large and shakes                             |
| `gentle`    | The message appears small and delicate                         |
| `invisible` | The message is blurred until the recipient swipes to reveal it |

## Sending a message with an effect

Add the `effect` object inside `message`, alongside `parts`:

- [cURL](#tab-panel-12)
- [TypeScript](#tab-panel-13)
- [Python](#tab-panel-14)

Terminal window

```
curl -X POST https://api.linqapp.com/api/partner/v3/chats/{chatId}/messages \
  -H "Authorization: Bearer $LINQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "parts": [
          {
            "type": "text",
            "value": "Congratulations! 🎉"
          }
        ],
        "effect": {
          "type": "screen",
          "name": "confetti"
        }
      }
    }'
```

```
await client.chats.messages.send({chatId}, {
  message: {
    parts: [
      {
        type: "text",
        value: "Congratulations! 🎉",
      },
    ],
    effect: {
      type: "screen",
      name: "confetti",
    },
  },
});
```

```
client.chats.messages.send(
    {chat_id},
    message={
        "parts": [
            {
                "type": "text",
                "value": "Congratulations! 🎉",
            },
        ],
        "effect": {
            "type": "screen",
            "name": "confetti",
        },
    },
)
```

## Important notes

- **iMessage only** — Effects are an iMessage feature. They are silently ignored when sending via RCS or SMS. See [Protocol Selection](/guides/messaging/protocol-selection/index.md) for protocol capabilities.
- **One effect per message** — You can only apply a single effect to each message.
- **Playback** — Effects play once when the recipient first opens the message. They can be replayed by the recipient.
- **Combine with media** — Effects work with both text and media message parts.