Skip to main content

Messages

Plain 1:1 iMessage and SMS conversations are BlueSender's default shape. Most of your traffic will be exchanges between one CRM contact and one Mac user, with no group context, no Tapback, no animation, and no media. This guide is the canonical reference for that case.

If your scenario involves multiple recipients, send-with-effect animations, Tapback reactions, voice messages, or stickers, see the dedicated guide:

Inbound: Mac → CRM​

When the Mac receives a 1:1 iMessage or SMS from a contact, BlueSender forwards it to the CRM as POST /conversations/messages/inbound. The body of the message carries a bluesendr-metadata:v1 footer with the structural envelope — chat identity, sender handle, recipients, and message_guid — appended to the human-readable text.

POST /conversations/messages/inbound — plain 1:1
{
  "type": "SMS",
  "contactId": "<crm contact id>",
  "locationId": "<crm location id>",
  "message": "Got it, thanks!\n\n-- bluesendr-metadata:v1 --\n{\"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\"}\n-- end bluesendr-metadata --"
}

The structural footer is always present on inbound 1:1 messages from Mac 1.10.5 and later — see the message_guid field row for the rollout caveat. CRMs must strip the footer before rendering the message to end users; everything between (and including) the -- bluesendr-metadata:v1 -- / -- end bluesendr-metadata -- lines is non-display content. Render only what comes before.

In a 1:1 thread the sender is the contact, so the top-level contactId and metadata.sender resolve to the same person. (This is the simplification that doesn't hold for groups.)

Inbound with attachments​

iMessage attachments (images, video, audio, files) ride on the top-level attachments[] array — a flat array of pre-uploaded asset URLs. The message body carries the caption, if any, plus the metadata footer. For attachment-only messages the body before the footer is empty.

POST /conversations/messages/inbound — 1:1 with image
{
  "type": "SMS",
  "contactId": "<crm contact id>",
  "locationId": "<crm location id>",
  "attachments": ["https://.../IMG_4521.jpeg"],
  "message": "Look at this!\n\n-- bluesendr-metadata:v1 --\n{\"animation\":null,\"chat_id\":660,\"display_name\":null,\"group_id\":null,\"is_group\":false,\"message_guid\":\"5C2A6B41-9F28-4730-B0E1-8C9A3D5F7124\",\"recipients\":[\"+32456832391\"],\"room_name\":null,\"sender\":\"+32456832391\",\"service_name\":\"iMessage\"}\n-- end bluesendr-metadata --"
}

Voice messages have a richer wire shape — see Voice messages.

Outbound: CRM → Mac​

To send a CRM-originated 1:1 reply, POST to /crm/webhook with the recipient's phone and the body. No metadata footer is required for plain 1:1 sends — BlueSender will route to the recipient's existing 1:1 chat thread on the Mac.

POST /crm/webhook — plain 1:1 reply
{
  "type": "SMS",
  "locationId": "<crm location id>",
  "contactId": "<crm contact id>",
  "messageId": "<crm correlation id>",
  "phone": "+32456832391",
  "message": "Thanks! I'll get back to you shortly."
}

See HTTP Webhooks for the full field reference, including the optional attachments[] array for outbound media.

Reacting to a 1:1 message​

When the customer sends a 1:1 message your CRM wants to react to, read the inbound message_guid from the metadata footer and feed it to the outbound reaction wire as target_message_guid:

Outbound reaction body — paste into CRM composer
-- bluesendr-metadata:v1 --
{
  "chat_id": 660,
  "reaction": {
    "action": "add",
    "kind": "classic",
    "target_message_guid": "7EE3FD68-C2D6-4066-9623-2598202C8A42",
    "type": "like"
  }
}
-- end bluesendr-metadata --

chat_id and target_message_guid both come from the inbound metadata footer of the message you're reacting to. See Reactions (Tapbacks) for the full reaction contract — classic, emoji, and sticker variants, add and remove, acks and idempotency.

CRM responsibilities checklist​

  • Preserve the metadata footer when storing the inbound message.
  • Strip the footer before rendering the body to end users.
  • Read message_guid when you need to react to or reference a specific inbound message.
  • Don't include the footer on plain 1:1 outbound sends — it is required only when targeting a group, applying an animation, or sending a structured Tapback or sticker.