bluesendr-metadata:v1 footer

BlueSender appends a machine-readable footer to every inbound message_received body — plain 1:1 messages, group messages, reactions, animations, and standalone stickers. The footer carries structured context — chat identity, group membership, the per-message identifier, reactions, stickers — that can't be expressed in a plain phone number alone. CRMs that integrate with BlueSender must preserve this footer for storage and round-tripping, but strip it before showing the message to end users.

Format

-- bluesendr-metadata:v1 --
{"animation":null,"chat_id":649,"display_name":"Family Group","group_id":null,"is_group":true,"message_guid":"7EE3FD68-C2D6-4066-9623-2598202C8A42","recipients":["+111","+222","+333"],"room_name":null,"sender":"+222","service_name":"iMessage"}
-- end bluesendr-metadata --

The block is delimited by literal -- bluesendr-metadata:v1 -- / -- end bluesendr-metadata -- lines. The middle line is a single JSON object.

Fields

Core fields

The fields below are part of the core v1 schema. Where a field carries a presence caveat (e.g. only emitted by newer Mac versions), it is called out in its row.

Field	Type	Meaning
is_group	bool	true when the chat has more than one external recipient.
chat_id	int	Mac-local chat identifier. Treat as opaque — preserve but do not interpret.
recipients	array of string	Participant handles. May include the Mac user's own handle; CRMs should filter that out when rendering a participant list.
sender	string	Handle of the sender for this specific message. In a group, this is the actual person who sent the message — not necessarily the same as the contactId BlueSender resolved on the inbound payload (see Sender vs contact resolution in groups).
service_name	string | null	Communication service: "iMessage", "SMS", "RCS", etc.
room_name	string | null	Internal chat room name from the Mac.
display_name	string | null	User-visible group name, if the user has set one.
group_id	string | null	Group identifier from the Mac.
animation	string | null	iMessage send-with-effect identifier (e.g. "lasers", "confetti"). See Animations.
message_guid	string | absent	Stable per-message identifier surfaced by the Mac. Treat as opaque. Use this value as target_message_guid when sending an outbound reaction back to the message a customer just sent. Ships on Mac 1.10.5+ and is always present from those clients; older Mac installs continue to emit a footer without message_guid until they auto-update. CRMs writing schema validators should treat the field as optional for now, then tighten to required once their customer base has fully updated.

Optional extension blocks

Field	Type	When	Reference
reaction	object	The row is a Tapback reaction (classic, emoji, or sticker reaction).	Reactions
sticker	object	The row is a standalone sticker message (sticker as its own message, not a reaction).	Stickers

reaction and sticker are mutually exclusive — a single message row is either a reaction or a standalone sticker, never both.

Examples by message shape

Plain 1:1 message

Got it, thanks!

-- bluesendr-metadata:v1 --
{"animation":null,"chat_id":660,"display_name":null,"group_id":null,"is_group":false,"message_guid":"7EE3FD68-C2D6-4066-9623-2598202C8A42","recipients":["+32456832391"],"room_name":null,"sender":"+32456832391","service_name":"iMessage"}
-- end bluesendr-metadata --

Group message

See Group messages → Inbound example.

Reaction

See Reactions for the reaction extension block.

CRM responsibilities

• Preserve the footer unchanged when storing the message body. Field ordering does not matter, but the JSON must remain valid.
• Strip the footer from anything shown to end users. Match on the literal delimiters; everything between (and including) those two lines is removed.
• Pass the footer back when sending a CRM → Mac reply that targets the same conversation. Embed the same footer (or at least chat_id and display_name) in the message body of your POST /crm/webhook request so the Mac routes the outbound send to the correct chat. See Group messages.
• Do not modify the JSON beyond keeping it valid. Don't reorder, don't drop fields, don't add fields.

Versioning

The :v1 suffix is the schema version. Future schema changes that are not backward-compatible will use a new version (e.g. bluesendr-metadata:v2). Additive changes (new optional fields) will stay in :v1 — old fields will not be removed within a major version. See Versioning policy.

Related

• Group messages — uses chat_id, display_name, and recipients from this footer.
• Animations — uses the animation field.
• Reactions — uses the reaction extension block.
• Stickers — uses the sticker extension block.
• Voice messages — voice messages in group threads carry this footer for chat context.
• HTTP Webhooks — both webhook directions.