Message effects
The bubble and full-screen animations, who actually sees them — and the threads an effect can be sent into.
An effect is the animation Messages plays when a message lands — the bubble
slamming in, or confetti falling across the whole conversation. On an iMessage
line — live or test — it is one key beside the text, with no kind:
{
"text": "You're in. See you Saturday.",
"effect": "confetti"
}Only on the conversation path
An effect rides the line's conversation path, which a thread takes once the transport has
confirmed it is a conversation with that one contact — the first time the contact writes into it —
and which a group chat the transport has reported takes too. Into any other thread the send takes
the recipient path, which carries text alone, and the effect is refused with 422 validation_failed at payload.effect before anything is queued. Nothing is sent without the
effect: the refusal is the answer. See which path a send
takes.
The effects
effect is a closed enum of twelve names. sparkles is taken too, as a second name for
celebration: Messages has one animation for the two, and its effect picker calls it
Celebration. Send celebration.
Bubble effects
Four animate the message bubble itself.
| Effect | What it does |
|---|---|
impact | The bubble slams into the thread hard enough to shake the view. |
loud | The bubble swells oversized, shakes, then settles. |
gentle | The bubble arrives small and quiet, then eases up to normal size. |
invisibleink | The bubble is hidden under shifting static until the reader swipes across it. |
Full-screen effects
Eight take over the conversation view while they play.
| Effect | What it does |
|---|---|
confetti | Confetti falls across the conversation. |
lasers | Laser beams sweep the screen. |
fireworks | Fireworks burst over a darkened screen. |
balloons | Balloons rise up the screen. |
spotlight | The view dims and a spotlight picks the message out. |
echo | The message multiplies and floods the screen. |
love | A big heart swells out of the message, then floats up off the screen. |
celebration | The view goes dark and golden sparks pour in from the top corner. |
The animations themselves are Apple's, not ours. The exact look of any one of
them can change between macOS and iOS releases; the names are what is stable.
Any other name is 422 validation_failed at payload.effect before anything
is queued.
A name is not always the label the Messages app shows in its effect picker:
impact, for one, is presented as "Slam". If a particular effect has to be
right, send it to yourself once and look at it before you ship it. The phones above play
each one, so you can see roughly what it does before that.
A worked example
Here the message is a confirmation that has a genuine reason to feel celebratory — which is the bar worth holding, because an effect on routine traffic gets old quickly. The conversation is one the contact opened, so it is confirmed and the effect goes.
curl -X POST https://api.mapier.ai/v1/commands/message.send \
-H "Authorization: Bearer $MAPIER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: signup-4821-welcome" \
-H "x-mapier-version: 2026-10-15" \
-d '{
"target": {
"kind": "conversation",
"conversationId": "a0000000-0000-4000-8000-000000000001"
},
"payload": {
"text": "You are in. See you Saturday.",
"effect": "confetti"
}
}'Keeping the enum in your own type, as above, is worth the four lines it costs:
effect is a closed set of names, and a typo like "confeti" is a 422
before anything is queued.
Not everyone sees the animation
Effects are an Apple-client feature
The effect plays on iMessage clients — iPhone, iPad, Mac, Apple Watch. A recipient reading over SMS or RCS, or on any non-Apple client, gets the text and nothing else: the animation is absent, with no marker that one was requested.
This is expected iMessage behaviour, not an API failure. The command still
settles succeeded, and there is no field anywhere in the response or on the
stream that reports whether the effect rendered.
Even among Apple clients, full-screen effects can be suppressed by the reader. Apple's accessibility settings include an option to stop message effects auto-playing, and a reader who has turned it on sees the message arrive without the animation.
The practical consequence is that an effect must never carry meaning. If your message only makes sense with confetti attached, write a message that makes sense without it.
Failure modes
Two are synchronous — 422 validation_failed at payload.effect, before
anything is queued:
- A name the API does not take. Nothing is corrected or dropped.
- An effect into a thread the transport has neither confirmed nor reported as a group chat — a recipient send to somebody who has not written to the line, or a thread whose contact has not answered yet. That thread takes the recipient path, which carries text alone. Send the text without the effect first; once the contact answers, the conversation is confirmed.
Two depend on the line's device:
- The device did not take the command within 30 seconds. The
commandframe settlesexpired,failureClass: not_run; nothing was sent. - The device is offline. The send is refused at once with
503 upstream_unavailableandreason: no_live_connector. ItsIdempotency-Keyis spent — resend under a new key once the line is back.