How to change campaign settings with update_campaign

update_campaign lets you change settings on a campaign from a script instead of clicking through the admin screen. It writes directly to the vicidial_campaigns table, so a single HTTP call can flip a campaign active, raise its dial level, swap its dialing method, or reset its hopper. That makes it the workhorse behind any time-of-day pacing automation.

Permissions and required fields

The API user must have a user_level of 8 or higher with "modify campaigns" enabled. Two fields are always required:

• campaign_id - 2 to 8 characters, the Campaign you're editing.
• source - a short label (max 20 characters) describing the caller for logs.

Everything else is optional - you send only the fields you want to change. New to this endpoint? Start with how to call the non-agent API and lock down access first with how to secure the VICIdial API.

The fields that change pacing

A handful of editable fields control how aggressively the dialer pulls leads:

• auto_dial_level - the Auto dial level, how many lines to dial per available agent. Valid from 0 to 18.
• dial_method - the Dial method: MANUAL, RATIO, INBOUND_MAN, ADAPT_AVERAGE, ADAPT_HARD_LIMIT or ADAPT_TAPERED.
• adaptive_maximum_level - the ceiling for adaptive dialing, 3 to 20 digits.
• hopper_level - how many leads to keep queued, 1 to 2000. Pass reset_hopper=Y to flush it.
• dial_timeout - ring time in seconds, 1 to 120.
• list_order - the List order, the order leads are pulled (UP, DOWN, RANDOM, DOWN COUNT). Mind the proper casing.

Other editable fields cover active (Y/N), campaign_name, outbound_cid, lead_filter_id, the five transfer conference numbers, and the dispo/webform URLs.

Which setting changes pacing

flowchart TD
  Call[update_campaign call] --> DialMethod[dial_method]
  Call --> DialLevel[auto_dial_level]
  Call --> AdaptMax[adaptive_maximum_level]
  Call --> Hopper[hopper_level]
  DialMethod --> Pacing[Dialer pacing]
  DialLevel --> Pacing
  AdaptMax --> Pacing
  Hopper --> Pacing

Example calls

Bump the dial level and rename the campaign:

http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=update_campaign&campaign_id=TESTOUT&campaign_name=Updated+test+API+campaign&auto_dial_level=3.0

Pause a campaign:

http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=update_campaign&campaign_id=TESTOUT&active=N

Reset the hopper:

http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=update_campaign&campaign_id=TESTOUT&reset_hopper=Y

Success and error responses

A clean run returns:

SUCCESS: update_campaign CAMPAIGN HAS BEEN UPDATED - 6666|1101

If you send no editable fields you get NOTICE: update_campaign NO UPDATES DEFINED. A bad value names the offending field, for example:

• ERROR: update_campaign USER DOES NOT HAVE PERMISSION TO UPDATE CAMPAIGNS - 6666
• ERROR: update_campaign CAMPAIGN DOES NOT EXIST - 6666|1000
• ERROR: update_campaign AUTO DIAL LEVEL MUST BE FROM 0 TO 18, THIS IS AN OPTIONAL FIELD - 6666|012
• ERROR: update_campaign DIAL METHOD IS NOT VALID, THIS IS AN OPTIONAL FIELD - 6666|12

Note the optional-field errors don't abort the whole call - the valid fields still apply, so always check the response rather than assuming everything went through.

Where to go next

Dial presets live in a separate function - see editing campaign dial presets with update_presets. For the broader map of what the API can do, read the VICIdial API and AGI overview.

Every VICIfast server comes provisioned in under 40 seconds with this API ready to drive. See what each plan includes on the pricing page.