Skip to main content

Voice messages

iMessage voice messages render as blue voice bubbles with a waveform, play button, and duration — visually distinct from a regular audio attachment. BlueSender preserves this distinction across the wire so your CRM can render voice messages with appropriate UI in both directions.

The bsvm1 identifier​

BlueSender marks voice messages with the literal string bsvm1 (BlueSender Voice Message version 1). This is what distinguishes voice messages from generic audio attachments, in both directions and across both message bodies and attachment filenames.

SurfaceWhere bsvm1 appears
Message bodyA line containing bsvm1 somewhere in the body.
Attachment filenamePattern: <guid>-bsvm1.wav.

A CRM should treat the message as a voice message if either surface carries the identifier. Some intermediate file-storage layers strip filename suffixes, so the body identifier is the more reliable of the two.

Inbound: Mac → CRM​

When the user records and sends a voice message on the Mac, BlueSender forwards it via POST /conversations/messages/inbound with:

  • The audio uploaded as a WAV attachment in attachments[].
  • The message body containing the GUID, optional transcription, and the bsvm1 marker.

Body format​

With transcription:

<message-guid>
IMAudioTranscription
<transcription text, possibly multi-line>
bsvm1

Without transcription:

<message-guid>
bsvm1

The metadata footer (when applicable, e.g. for group voice messages) is appended after bsvm1 separated by a blank line — see bluesendr-metadata:v1 footer.

Inbound example (with transcription, group)​

POST /conversations/messages/inbound
{
  "type": "SMS",
  "contactId": "<crm contact id>",
  "locationId": "<crm location id>",
  "message": "60B0114A-35A1-41B2-8135-A98B084B62BD\nIMAudioTranscription\nHello world\nbsvm1\n\n-- bluesendr-metadata:v1 --\n{\"chat_id\":646,\"is_group\":true,\"message_guid\":\"60B0114A-35A1-41B2-8135-A98B084B62BD\",\"recipients\":[\"+32456791066\",\"+32483119453\"],\"sender\":\"+32487444733\"}\n-- end bluesendr-metadata --",
  "attachments": [
    "https://.../60B0114A-35A1-41B2-8135-A98B084B62BD-bsvm1.wav"
  ]
}

Detecting voice messages​

function isVoiceMessage(msg) {
  // Body check (most reliable)
  if (msg.text && msg.text.includes('bsvm1')) return true;

  // Filename check (some storage layers strip the suffix)
  return (msg.attachments || []).some(url => url.includes('-bsvm1.'));
}

Outbound: CRM → Mac​

To send a voice message from your CRM through BlueSender, POST to /crm/webhook with:

  • A WAV attachment URL in the attachments array.
  • The string bsvm1 in the message body.
  • Optionally, the <guid>-bsvm1.wav filename pattern (preserved if your storage layer permits).

The Mac transcodes the WAV to the iMessage voice-bubble format internally and presents it as a proper voice message in the recipient's Messages app — not as a generic audio attachment.

Outbound examples​

Voice message with transcription:

POST /crm/webhook
{
  "locationId": "<crm location id>",
  "contactId": "<crm contact id>",
  "messageId": "<crm correlation id>",
  "phone": "+15555550100",
  "message": "Hello world\nbsvm1",
  "attachments": ["https://.../voice-message-bsvm1.wav"]
}

Voice message without transcription:

POST /crm/webhook
{
  "locationId": "<crm location id>",
  "contactId": "<crm contact id>",
  "messageId": "<crm correlation id>",
  "phone": "+15555550100",
  "message": "bsvm1",
  "attachments": ["https://.../voice-message-bsvm1.wav"]
}

File format​

DirectionFormat
Mac → CRMWAV (PCM).
CRM → MacWAV. The Mac transcodes internally before delivery.

CRM responsibilities checklist​

  • Detect inbound voice messages by checking for bsvm1 in message (or -bsvm1 in attachment filenames).
  • Render voice messages with appropriate UI (waveform, duration, play button) — don't show them as generic audio attachments.
  • Preserve transcription text (lines between IMAudioTranscription and the trailing bsvm1) if present.
  • Tag outbound voice messages with bsvm1 in the body. Preserve -bsvm1 in the filename if your storage layer allows.
  • Send WAV, not other audio formats — the Mac's transcoder expects WAV input.

Caveats​

  • Filename suffix stripping: some CRM media-storage layers rename uploaded files server-side and remove the -bsvm1 suffix. The body identifier is unaffected; treat it as the primary signal.