Test a VICIdial Agent API request

01 / 04

1. Pick the active session

The idle workspace below is a real demo capture; it does not show a live call.

1. Sign in to the Agent interface with the test station and test user, and select the test campaign.
2. Confirm the session is idle and note the exact agent user ID. Do not use a customer session.
3. In Users → Show Users, inspect Agent API Access and API Allowed Functions for the approved API user. Compare its permissions and the desired function with the Agent API reference shipped with your installed revision.

Agent API Access

Open to enlarge

You should seeAn Agent API request targets an agent session; successful authentication alone does not prove a station is registered or a call works.

02 / 04

2. Form one request

Create a new local private exercise directory and save only form credentials there. The Python prompts use the terminal, not a shell argument; urlencode serializes punctuation safely. The config contains no URL, redirect or additional operation.

This step writes a local credential file only. Keep this shell open so API_EXERCISE_DIR still names it, and never publish the file. The actual API read is the following section.

1. In the private workstation terminal, run the protected-file block below. It creates a new mode 0700 directory and a mode 0600 config with exclusive creation.
2. At the hidden prompts enter the approved API username and password. Do not use the agent phone-login password or paste credentials into a URL.
3. Read the printed owner/mode check. Keep the config only as long as the credential policy permits; removing a local file does not revoke the server account.

API_EXERCISE_DIR=$(mktemp -d "${TMPDIR:-/tmp}/vicigeek-api.XXXXXXXX")if [ -n "$API_EXERCISE_DIR" ] && [ -d "$API_EXERCISE_DIR" ]; then  chmod 700 "$API_EXERCISE_DIR"  python3 - "$API_EXERCISE_DIR/api.curl" <<'PYCONFIG'import getpass,os,pathlib,sys,urllib.parsepath=pathlib.Path(sys.argv[1])user=getpass.getpass('Approved API username (hidden): ')password=getpass.getpass('Approved API password (hidden): ')if not user or not password or any(c in user+password for c in '\r\n\0'):    raise SystemExit('STOP: empty or unsupported credential input')body=urllib.parse.urlencode({'user':user,'pass':password})fd=os.open(path,os.O_WRONLY|os.O_CREAT|os.O_EXCL,0o600)with os.fdopen(fd,'w',encoding='ascii') as config:    config.write('data = "'+body+'"\n')print('Private config created; no credentials printed.')PYCONFIG  stat -c '%U %a %n' "$API_EXERCISE_DIR/api.curl"else  printf '%s\n' 'STOP: private directory creation failed.' >&2fi

You should seeThe authenticated request now has a concrete protected-file prerequisite; no API permission has been proven.

03 / 04

3. Send one idle-session queue-count read

Replace the hostname and TESTUSER below with the approved HTTPS endpoint and exact idle synthetic agent. The curl config supplies user/pass; the command supplies only the documented function parameters. No retry or redirect following is enabled.

The documented success example is SUCCESS: calls_in_queue_count - 0. Zero is a valid count, not a failed call. Compare the full returned contract with the installed reference; eligible queued calls are not the outbound hopper population.

(  test -n "${API_EXERCISE_DIR:-}" && test -r "$API_EXERCISE_DIR/api.curl" || exit 1  response=$(curl --fail --silent --show-error --connect-timeout 10 --max-time 20 \    --config "$API_EXERCISE_DIR/api.curl" \    --data-urlencode 'source=lab' --data-urlencode 'function=calls_in_queue_count' \    --data-urlencode 'value=DISPLAY' --data-urlencode 'agent_user=TESTUSER' \    'https://YOUR_HOSTNAME/agc/api.php') || exit 1  if [[ "$response" =~ ^SUCCESS:\ calls_in_queue_count\ -\ [0-9]+$ ]]; then    printf '%s\n' "$response"  else    printf '%s\n' 'STOP: no accepted queue-count contract; inspect the private response with the owner.' >&2    exit 1  fi)

You should seeYou have one accepted bounded queue read or a specific unresolved transport/access/session/contract failure.

04 / 04

4. Resolve the failure and retire the local credential safely

1. If authentication fails, check API access and the API user's permissions with the administrator; never paste secrets into a ticket.
2. If the agent is unavailable, verify the exact user, campaign and current session in the Agent UI.
3. If a function is unsupported or the response is ambiguous, stop and compare the installed API version and function documentation before retrying.

You should seeOnly run call-control actions after an operator has explicitly prepared a test call and documented the expected effect.