Sending DTMF tones from the agent screen with send_dtmf

Sometimes an agent needs to send touch-tones down the line, an account number into a phone tree, a PIN, a menu choice, without typing them by hand. send_dtmf is the Agent API function that pushes a string of DTMF tones into an agent's live session. It is a small, single-purpose endpoint, and it pairs well with the rest of the call-control family covered in the VICIdial API overview.

When you'd use it

Reach for it when a workflow needs tones sent on the agent's behalf. A custom button on a soundboard or a CRM panel that walks an IVR for the agent, an automated PIN entry, or a quick way to navigate a carrier's menu are all good fits. Because it operates on the agent's session (Agent session), the tones land on whatever call that agent currently has up. There is nothing to schedule and nothing to confirm beyond the success line.

How the call works

sequenceDiagram
  participant App
  participant API as api.php
  participant V as VICIdial
  participant Caller
  App->>API: send_dtmf (agent_user, value)
  API->>V: queue tones for the session
  V->>Caller: play DTMF on the line
  V-->>API: SUCCESS function set
  API-->>App: confirmation line

You pass the digit string in value, VICIdial drops it into the agent's session, and the tones play out on the active call. The acknowledgement comes back immediately; the actual audio plays as the tones are sent. Like every agent endpoint, the call still starts with the standard pieces covered in the source parameter.

Parameters

• agent_user - the agent's login whose session receives the tones.
• value - the DTMF string. It accepts only valid DTMF characters, with three special replacements.

The replacements matter because URLs choke on raw # and *. Use P for # (pound or hash), S for * (star), and Q for one second of silence. So a string of QQQQ means pause four seconds before dialing the rest, useful for waiting out a greeting before sending digits.

An example call

http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=send_dtmf&value=QQQQ1234SQQQQQ6654P

That string waits four seconds, sends 1234, presses star, waits five seconds, sends 6654, and finishes with pound. A clean run returns SUCCESS: send_dtmf function set - QQQQ1234SQQQQQ6654P|6666. If the agent isn't on session you get ERROR: agent_user is not logged in - 6666, and a malformed string returns ERROR: send_dtmf not valid - QQ|6666.

The gotcha

Two things trip people up. First, you must encode # and * as P and S; sending the literal characters in the URL will either break the request or send the wrong tones. Second, timing is your responsibility, the function blasts the digits as fast as it can, so if the far end needs a beat to register each tone, sprinkle Q characters between them. Most IVR-entry bugs come down to too little silence rather than wrong digits. For sending the call somewhere else once the IVR is done, see driving transfers with transfer_conference.

Wiring custom call-control buttons works best on a dialer you control end to end. VICIfast provisions a single-tenant VICIdial box with the API ready in under 40 seconds. See the plans to spin one up.