Editing campaign dial presets with update_presets

Dial presets are the saved numbers an agent can fire off with one click from inside a campaign — a support line, a sales desk, a 3-way bridge. update_presets manages those entries over HTTP. The one function handles all four actions: add a new preset, update an existing one, list them, or delete one.

Permissions and required fields

The API user needs a user_level of 8 or higher with "modify campaigns" enabled — the same permission update_campaign uses. Required fields are:

• campaign_id — 2 to 8 characters, the Campaign the preset belongs to.
• source — a short label (max 20 characters) for the logs.
• preset_name — the name of the preset. If the campaign has only one preset, you can leave this blank.
• action — UPDATE, NEW, DELETE or LIST. Defaults to UPDATE.

The editable fields

Three fields define what the preset does:

• preset_number — digits only, 1 to 50 digits, the number to dial.
• preset_hide_number — Y or N (default N), whether to hide the number from the agent.
• preset_dtmf — DTMF (the touch-tone digits sent after connect) using 0-9 plus P (#-pound), S (*-star) and Q (half-second pause). Set it to --BLANK-- to clear it.

Note that preset_number is the raw destination — it doesn't include the campaign's Dial prefix, which the dialer prepends at call time, so set the preset to the bare number you want reached.

DTMF is handy when a preset has to punch through an IVR menu — dial the number, then send a few digits to land on the right department. If you've never built a non-agent API request before, read how to call the non-agent API first.

Example calls

Add a new SALES preset:

http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=update_presets&campaign_id=ALTTEST&preset_name=SALES&preset_number=3125551212&preset_hide_number=N&action=NEW

Add a SUPPORT LINE preset that hides its number and sends a single DTMF digit:

http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=update_presets&campaign_id=ALTTEST&preset_name=SUPPORT+LINE&preset_number=3125551214&preset_hide_number=Y&preset_dtmf=1&action=NEW

List every preset on the campaign:

http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=update_presets&campaign_id=ALTTEST&action=LIST

Reading the responses

Each action has its own success line:

• SUCCESS: update_presets PRESET HAS BEEN ADDED - 6666|NEW PRESET: SUPPORT LINE|TESTCAMP
• SUCCESS: update_presets PRESET HAS BEEN UPDATED - 6666|1|campaign|TESTCAMP
• SUCCESS: update_presets PRESET HAS BEEN DELETED - 6666|SUPPORT LINE|TESTCAMP

A LIST action doesn't print SUCCESS — it returns pipe-delimited rows:

SALES|ALTTEST|3125551213|N|1234

The columns are preset_name, campaign_id, preset_number, preset_hide_number, preset_dtmf. Common errors include:

• ERROR: update_presets USER DOES NOT HAVE PERMISSION TO UPDATE CAMPAIGNS - 6666
• ERROR: update_presets CAMPAIGN DOES NOT EXIST - 6666|1000
• ERROR: update_presets PRESET DTMF IS NOT VALID, THIS IS AN OPTIONAL FIELD - 6666|

How an action routes

flowchart LR
  Call --> Action
  Action --> NEW
  Action --> UPDATE
  Action --> DELETE
  Action --> LIST
  NEW --> Preset[(presets table)]
  UPDATE --> Preset
  DELETE --> Preset
  LIST --> Output[Pipe rows]

Where this fits

Presets are a small slice of campaign configuration. To change the dialing behaviour itself, use update_campaign, and for the full tour of what the API (application programming interface) exposes, read the VICIdial API and AGI overview.

Spin up a VICIdial box with the API ready in under 40 seconds — see what each plan includes on the pricing page.