Skip to main content
Send an audio clip and the recipient sees the native iMessage voice-note balloon — waveform, play button, scrubber — not a generic file pill.

​
Send a voice note

Pass an audio file directly to sendVoiceNote and the SDK uploads it, then enqueues the send. Any format afconvert can read works — m4a, mp3, wav, caf, aiff. 
import { readFileSync } from "node:fs";
import { createClient } from "@messages-dev/sdk";

const client = createClient();

await client.sendVoiceNote({
  from: "+15551234567",
  to: "+15559876543",
  voiceNote: readFileSync("clip.m4a"),
  mimeType: "audio/mp4",
});
The SDK also accepts a pre-uploaded file ID, so you can reuse a clip without re-uploading: 
await client.sendVoiceNote({
  from: "+15551234567",
  to: "+15559876543",
  voiceNote: "file_abc123",
});

​
Parameters

FieldRequiredDescription
fromYesSender line handle.
toYesRecipient phone number, Apple ID, or chat ID (cht_...).
voiceNoteYesFile ID (file_...) or raw audio bytes (Blob, Buffer, Uint8Array).
mimeTypeNoMime type when passing raw bytes. Default: audio/mpeg.
filenameNoFilename when passing raw bytes.
replyToNoMessage ID or GUID to reply to.

​
Requirements

Voice notes require advanced features on the line’s machine — SIP and AMFI disabled, with the helper dylib injected into Messages.app. Without this, the API returns 400 advanced_features_required. To check whether a machine supports voice notes, run: 
imsg-plus status --json
and look for "voice_note_send": true. iMessage only — SMS lines are rejected.

​
Supported formats

Any format afconvert can decode:
  • m4a / aac
  • mp3
  • wav
  • caf
  • aiff
The audio is transcoded server-side to the format Messages.app renders as a waveform balloon. You don’t need to pre-encode.