Skip to content
SIP.IO
DocsStart free

Voicemail

Voicemail in SIP.IO is a route target like any other: a voicemail box you can send calls to from a flow, a number, or a queue/ring-group overflow.

A voicemail row configures a mailbox:

{
"id": "vm_01jg8asp59ps9rtt7azhrhvcre", "account_id": "acc_01jf18ah3jeb5w6dfp27sgjsbt", "name": "Support after-hours",
"greeting_media_id": "media_01j22nfknpx47prkr1dpm4yxtk",
"skip_instructions": 0,
"quota_mb": 200,
"notify_email": "support@acme.example",
"pin_secret_ref": "kv:vm:7:pin"
}
FieldPurpose
greeting_media_idA media_file greeting. Omit to use the system vm-greeting prompt in the account language.
skip_instructionsSkip the “record after the beep” instructions.
quota_mbStorage quota for the box.
notify_emailWhere to send new-message notifications.
pin_secret_refPIN to retrieve messages: a key-value secret reference, never stored plaintext.

A sip_user can have a default mailbox via voicemail_id.

When a caller leaves a message, the media engine edge records it and uploads it to the private object storage bucket via the edge runtime’s /media endpoint, keyed as <account>/vm/<callId>.wav. A voicemail_message row is written so the box can list and play messages (caller, duration, timestamp). Because the bucket is private and served only through the IP-gated media proxy, recordings are never world-readable.

Each new message is also delivered as a conversation to the mailbox’s destination in the omnichannel inbox: a user or a team inbox, set per box. Agents work a voicemail like any other message (assign it, read it, close it), and a team-routed box is answered by whoever staffs that inbox.

  • A voicemail is a message on its own receive-only voicemail channel, so your message.received webhook sees it with channel: "voicemail" and a signed link to the audio.
  • Each caller gets their own conversation, separate from their SMS or WhatsApp thread. A withheld caller gets one per recording, never a shared “anonymous” thread.
  • Every recording records its delivery outcome (pending, delivered, no_destination, failed) on GET /v1/voicemails/{id}/messages, so a box with no destination never drops messages silently.
  • Changing a box’s destination moves only new messages; conversations already in an inbox stay where they are.

There are three common ways a call reaches a mailbox:

  1. From a flow: a voicemail node, typically on a menu timeout/invalid edge or a timeCondition’s out_of_hours edge.

    { "id": "vm", "type": "voicemail", "data": { "kind": "voicemail", "mailboxId": "vm_01jg8asp59ps9rtt7azhrhvcre" } }
  2. Directly from a number: set a DID/extension dest_kind: "voicemail", or use the closed/holiday override to send after-hours calls to voicemail:

    { "e164": "12025550123", "dest_kind": "flow", "dest_id": "flow_01jzqwjn803wtnhc445bvjenzc",
    "schedule_id": "sch_01j0jvpe0wzc6g05bktfew0xyx", "closed_dest_kind": "voicemail", "closed_dest_id": "vm_01jg8asp59ps9rtt7azhrhvcre" }
  3. As queue/ring-group overflow: set a queue’s timeout_dest/abandon_dest/no_agents_dest (or a ring group’s exit_dest) to a voicemail. See Overflow & Exit Destinations.

For a step-by-step, see Route after-hours calls to voicemail.