Animations

iMessage supports two families of "send-with-effect" animations on a message: bubble effects that animate the individual message bubble, and screen effects that play a full-screen animation. BlueSender surfaces both directions of this — detecting effects on inbound messages and applying effects on outbound sends.

Effect catalog

Bubble effects

Animate the individual message bubble.

Identifier	Effect
slam	Message slams down onto the screen.
loud	Message shakes and grows large.
gentle	Message appears small and fades in.
invisibleInk	Message is obscured until tapped or hovered.

Screen effects

Full-screen animations that play behind the message.

Identifier	Effect
echo	Message repeats across the screen.
spotlight	Spotlight focuses on the message.
balloons	Balloons float up.
confetti	Confetti falls from the top.
love	Heart grows from the message.
lasers	Laser lights sweep across.
fireworks	Fireworks explode.
celebration	Sparkles and streamers.

Inbound: Mac → CRM

When the user receives a message sent with an effect, BlueSender forwards it to the CRM via POST /conversations/messages/inbound. The animation identifier is carried inside the bluesendr-metadata:v1 footer embedded in the message body — there is no top-level animation field on the inbound HTTP payload.

Inbound example

POST /conversations/messages/inbound

{
  "type": "SMS",
  "contactId": "<crm contact id>",
  "locationId": "<crm location id>",
  "message": "Happy Birthday!\n\n-- bluesendr-metadata:v1 --\n{\"animation\":\"balloons\",\"chat_id\":646,\"is_group\":true,\"message_guid\":\"4D2E91B8-7A55-42B0-AE63-C81F0D3B2F47\",\"recipients\":[\"+32456791066\",\"+32483119453\"],\"sender\":\"+32487444733\"}\n-- end bluesendr-metadata --"
}

The CRM should parse the metadata footer (delimited by -- bluesendr-metadata:v1 -- and -- end bluesendr-metadata --), read the animation field, and strip the footer before displaying the body text.

How a CRM should render

A CRM that doesn't natively render iMessage animations has three reasonable options:

1. Render an inline animation in your UI, based on the short identifier.
2. Show a static badge or icon ("🎈 Balloons effect") next to the message.
3. Append a text indicator like "(sent with balloons effect)".

Even if your UI does none of the above, preserve the animation field on stored messages so it can be round-tripped or surfaced later.

Outbound: CRM → Mac

CRMs send animations by POSTing to /crm/webhook with the animation identifier embedded in the bluesendr-metadata:v1 footer in the message body. There is no top-level animation field on the HTTP request; only fields embedded in the metadata footer reach the Mac through this path.

POST /crm/webhook — 1:1 animation send

{
  "locationId": "<crm location id>",
  "contactId": "<crm contact id>",
  "messageId": "<crm correlation id>",
  "phone": "+15555550100",
  "message": "Happy Birthday!\n\n-- bluesendr-metadata:v1 --\n{\"animation\":\"balloons\"}\n-- end bluesendr-metadata --"
}

Group sends — display_name is required

For group animations to be visible to all recipients (not just the sender's own Mac), the metadata footer must include display_name. BlueSender uses display_name to navigate to the correct group thread before applying the effect; without it, animations may only render locally on the sending Mac, or may target the wrong thread when multiple groups share the same participants.

POST /crm/webhook — group animation

{
  "locationId": "<crm location id>",
  "contactId": "<crm contact id>",
  "messageId": "<crm correlation id>",
  "phone": "+32483119453",
  "message": "Lasers test!\n\n-- bluesendr-metadata:v1 --\n{\"animation\":\"lasers\",\"chat_id\":655,\"display_name\":\"SANDBOX GROUP\",\"is_group\":true,\"recipients\":[\"+32456791066\",\"+32483119453\"]}\n-- end bluesendr-metadata --"
}

Constraints

• Text-only: animations apply to text messages. Sending an effect alongside an attachment (image, voice, sticker) is not supported; the effect will be silently dropped.
• No CRM-driven attachment animation: there is no way to send a voice message or photo with an effect via this API.
• iMessage only: effects are an iMessage feature. SMS / RCS threads ignore them.

Caveats

• RCS chats (service_name: "RCS" in metadata): inbound messages rarely carry animation even if the sender attempted an effect. Apple's RCS implementation does not propagate the send-with-effect signal cleanly. Plan for animation: null on RCS chats.
• macOS updates may add or reorder effects. If a future macOS introduces a new effect, BlueSender will add a new short identifier; existing identifiers will not be reused or renumbered.

CRM responsibilities checklist

• Detect inbound animations by parsing the animation field from the bluesendr-metadata:v1 footer in the inbound message body.
• Render animations in some form — playback, badge, or text indicator — or at minimum preserve the field for round-tripping.
• Send outbound animations by embedding the animation field in the metadata footer of the message body on POST /crm/webhook.
• Include display_name in the metadata footer when sending animations into a group.
• Don't combine animations with attachments — the animation will be dropped.

Related

• Group messages — group sends require display_name to navigate to the correct thread before applying the effect.
• bluesendr-metadata:v1 footer — the schema embedded in message (carries animation, chat_id, display_name).
• HTTP Webhooks — both webhook directions.
• Error codes — including UI_AUTOMATION_DISABLED, INTERNAL_ERROR, and TIMEOUT for cases where an effect can't be applied.