Message effects

An effect is the animation Messages plays when a message lands — the bubble slamming in, or confetti falling across the whole conversation. You request one by adding effect to a rich_text payload.

{
  "kind": "rich_text",
  "text": "You're in. See you Saturday.",
  "effect": "confetti"
}

Two constraints follow from that shape. Effects need kind: "rich_text", so a bare { text } payload cannot carry one — and because rich_text needs a conversation target, effects are unavailable on a recipient send. You cannot open a cold thread with fireworks.

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.

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

An effect is one extra field on a send you were making anyway. 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.

curl -X POST $MAPIER_BASE_URL/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": {
      "kind": "rich_text",
      "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. The API does not validate payload before queueing, so a typo like "confeti" returns a perfectly ordinary 202 and only fails seconds later on the stream.

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

Effects add one new way to fail, and it is asynchronous:

• An unrecognised effect name settles failed on the stream. There is no boundary validation to catch the typo for you.
• A connector that has not negotiated rich content settles failed with capability_not_negotiated or capability_constraint_violation. Rich content is a capability the Mac advertises at handshake, and there is no endpoint to query it in advance.

Both look identical at the moment you POST — a 202. Watch the stream.

Related