Queueing a voicemail with the vm_message function

Leaving a voicemail manually means the agent stays on the line while a message plays, tying up their session for 30 to 60 seconds per call. Voicemail drop solves this by letting the agent click one button and move on, with a pre-recorded message playing in the background. The vm_message function in the Agent API is how you control which audio file gets dropped from outside the agent screen.

This function sets a custom voicemail message that plays when the Agent clicks the VM button during a live call. It works in combination with campaign-level settings: the campaign's Answering Machine Message setting must be set to LTTagent for this to take effect. Without that, the function call will succeed but the agent's VM button will use whatever the campaign default is.

How vm_message loads an audio file

sequenceDiagram
  participant App as Your App
  participant API as agc/api.php
  participant Session as agent_session
  participant Agent as Agent Screen
  App->>API: vm_message agent_user value=audio_file
  API->>Session: verify agent is logged in with live call
  API->>Session: store vm audio file reference
  Session-->>API: confirmed
  API-->>App: SUCCESS vm_message function set
  Agent->>Session: agent clicks VM button
  Session->>Agent: plays stored audio file to answering machine

Your application calls vm_message before the agent reaches the answering machine stage. The function stores the audio file reference in the agent's session. When the agent hits the VM button, VICIdial plays the stored file rather than the campaign default.

Parameters and example calls

The required parameter is value, which holds one or more audio file names separated by pipe characters. The file names reference files already in the VICIdial audio store — do not include the file extension. You can chain multiple files by separating them with | and VICIdial will play them in sequence.

The optional lead_id parameter adds a validation check: if you supply it, the API confirms that the agent is currently on a call with that exact Lead before storing the message. This prevents a race condition where your CRM sends a vm_message for one call while the agent has already moved to a different lead.

# Multiple audio files played in sequence
curl "https://your-server/agc/api.php?source=crm&user=6666&pass=1234&agent_user=1000&function=vm_message&value=EXship01|EXship02|EXship03"

# Single file with lead validation
curl "https://your-server/agc/api.php?source=crm&user=6666&pass=1234&agent_user=1000&function=vm_message&lead_id=12345&value=appointment_reminder2"

A successful response confirms the agent, lead, and file list:

SUCCESS: vm_message function set - 6666|12345|EXship01|EXship02|EXship03

Campaign settings that interact with this function

Two campaign settings can override what vm_message sets. AM Message Wildcards and VM Message Groups both take priority if they are enabled. To make vm_message effective, disable both of those settings on the campaign. If you leave them on, the API call succeeds but the agent may hear a different file than you intended.

This function pairs well with a CRM integration that picks the appropriate message based on lead data — for example, sending a product-specific reminder to one segment and an appointment confirmation to another, all handled automatically before the agent even knows the call connected. The Non-agent API and Agent API together give you enough control to build that kind of flow without any changes to the agent interface itself.

To understand how inbound and outbound API functions divide their responsibilities, see Non-Agent API vs Agent API. The full function catalogue is in the VICIdial API and AGI overview. Every VICIfast plan ships a VICIdial server with the Agent API enabled and audio store ready to use, provisioned in under 40 seconds.