Message effects

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"
}

The 13 effects

effect is a closed enum. Four are bubble effects, which animate the message bubble itself; the other nine are full-screen, taking over the conversation view while they play.

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. A name outside the thirteen is 422 validation_failed at payload.effect before anything is queued.

Those names are Apple's identifiers, and they do not always match the label the Messages app shows in its effect picker — impact is the one presented as "Slam". If a particular effect has to be right, send it to yourself once and look at it before you ship it.

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" \
  -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 thirteen names, and a typo like "confeti" is a 422 before anything is queued.

Not everyone sees the animation

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 outside the thirteen. 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 command frame settles expired, failureClass: not_run; nothing was sent.
• The device is offline. The send is refused at once with 503 upstream_unavailable and reason: no_live_connector. Its Idempotency-Key is spent — resend under a new key once the line is back.

Related