How to Add an Agent in ViciDial — User Setup & Phone Config

Master the complete process of creating and configuring a new agent in ViciDial, from database entry through SIP registration and phone extension setup.

Prerequisites

Before adding an agent to your ViciDial system, ensure you have:

• ViciDial 2.x or 3.x installed and running (tested on 2.14+ through 3.x)
• Root or sudo access to the ViciDial server
• Access to the ViciDial web admin panel (http://your-server/vicidial/admin.php)
• An existing campaign configured in the system
• A SIP phone or softphone application ready for the agent
• MySQL database access (for manual verification)
• Asterisk running and accessible via CLI
• Basic familiarity with Linux command line

Understanding ViciDial Agent Architecture

Agent vs. User vs. Extension

ViciDial uses three interconnected concepts:

• User: The administrative login account in the ViciDial system
• Agent: The voice channel and phone configuration tied to that user
• Extension: The SIP endpoint (phone) that registers to Asterisk

One user can have one active agent, though multiple extensions can exist. The agent record defines which campaign the user can access, pause codes, and phone behavior.

Database Tables Involved

Three primary tables interact when adding an agent:

vicidial_users           — User login credentials and permissions
vicidial_agents          — Agent configuration (user_id, phone, campaign)
asterisk_sip_peers       — SIP phone registration details (generated from sip-vicidial.conf)

Step 1: Create the User Account in ViciDial Web Admin

The fastest and recommended method is through the web interface.

Access the User Management Panel

1. Log in to /vicidial/admin.php as an administrator
2. Navigate to Users → Add User
3. Fill in the required fields:

Configure User Permissions

Under the User Permissions section:

• Group: Assign to ADMIN, QA, SALES, or custom group
• User Level: Set to 1 for agent, 7 for manager, 8 for admin
• Confirm Password Changes: Check if agent must change password at login
• Inbound Only: Check to restrict to inbound calls only
• Outbound Only: Check to restrict to outbound calls only

Leave blank for both inbound and outbound access.

Save and Note the User ID

After saving, ViciDial assigns a unique user_id. You'll need this for the agent configuration.

Step 2: Create the Agent Record

Via Web Admin (Recommended)

1. Navigate to Agents → Add Agent
2. Complete the agent setup form:

Via MySQL (For Scripted Deployments)

If you're automating agent creation, use SQL directly:

USE asterisk;

INSERT INTO vicidial_agents 
(user_id, agent_id, user, phone_number, phone_type, status, 
 campaign_id, closer_group, email, active, last_login, last_call_time)
VALUES 
(123, 100001, 'agent001', '1001', 'SIP', 'ACTIVE', 
 'SALES_OUTBOUND', 'SALES', '[email protected]', 'Y', NOW(), 0);

-- Verify insertion
SELECT user_id, agent_id, user, phone_number, status FROM vicidial_agents 
WHERE user = 'agent001';

Replace:

• 123 with the actual user_id from step 1
• 100001 with your agent ID scheme
• SALES_OUTBOUND with your campaign name

Step 3: Configure the SIP Phone Extension

Generate SIP Configuration

ViciDial typically generates SIP extensions automatically in /etc/asterisk/sip-vicidial.conf when you add an agent. However, you may need to generate or verify it manually.

Manual SIP Peer Configuration

If auto-generation doesn't work, add the extension to /etc/asterisk/sip-vicidial.conf:

[1001]
type=friend
context=from-vicidial-agents
callerid="Agent 001" <1001>
host=dynamic
secret=YourSecurePassword123
qualify=yes
port=5060
nat=yes
insecure=port,invite
canreinvite=no
disallow=all
allow=ulaw,alaw,gsm
directmedia=no
username=1001
mailbox=1001@default

Key settings explained:

• type=friend — Allows bidirectional calling
• context=from-vicidial-agents — Routes to ViciDial context (verify in extensions.conf)
• secret — SIP password; must match phone config
• nat=yes — Accommodates agents behind NAT
• insecure=port,invite — Relaxes authentication (production: tighten this)
• disallow=all; allow=ulaw — Codec restriction for bandwidth

Reload Asterisk Configuration

After editing the SIP config:

sudo asterisk -rx "sip reload"

Verify the extension loaded:

sudo asterisk -rx "sip show peers"

Output should show:

1001/1001                        (Unregistered)

Once the phone registers, it will show an IP:

1001/1001                        192.168.1.105:5064    OK (42 ms)

Step 4: Configure the Phone/Softphone

SIP Phone Credentials

Provide the agent with:

• Username: 1001
• Password: (matching the SIP secret from config)
• Server/Domain: your-vicidial-server.com or IP address
• Port: 5060 (or custom if changed)
• Display Name: Agent 001 (or agent's name)

Popular Softphone Clients

Zoiper (iOS/Android/Windows/Mac)

1. Add Account → SIP Account
2. Enter extension (e.g., [email protected])
3. Password: SIP secret
4. Server: ViciDial server IP/hostname
5. Enable "Use SIP directly" if behind NAT

Grandstream GrandStream Desktop (Windows/Mac)

1. Settings → Accounts
2. Create SIP Account
3. Configure with above details
4. Enable "Behind NAT"

Physical SIP Phones (Yealink, Polycom, Cisco)

1. Web admin interface of phone
2. Network settings → VoIP > Accounts
3. Server address, username, password, port
4. Enable NAT (usually labeled "Symmetric RTP")

Test SIP Registration

After phone configuration, check Asterisk:

sudo asterisk -rx "sip show peer 1001"

Output should show:

  Name       : 1001
  Exten      : 1001                   ACTIVE
  Context    : from-vicidial-agents
  Callid     : [email protected]
  ChanObjectType : SIP
  Useragent  : Zoiper 5.3.18
  Status     : OK (42 ms)

If status is UNKNOWN or Unreachable, check firewall rules on port 5060/5061.

Step 5: Configure ViciDial Phone Settings

Access Phone Configuration

In the web admin, navigate to System → Phones or Agents → Phone Settings for the agent.

Essential Phone Parameters

Phone Codec:          ULAW (or ALAW if EU-based)
Inbound Context:      from-vicidial-agents
Outbound Context:     from-vicidial-agents
Recording:            ENABLED
Recording Format:     MP3 or WAV
Voicemail Enabled:    YES (optional)
Inbound Answering:    AGENT_ONLY
Ringback:             ENABLED
Ringback Timeout:     30 seconds

Agent-Specific Settings

If your ViciDial uses Vicidial Phone Screen, configure:

Vicidial Phone Type:  SIP
VoiceGain:            0 (0-10 scale; increase if audio is low)
MicGain:              0 (0-10 scale)
Monitoring:           ENABLED (for QA supervisors)
Blind Transfers:      ALLOWED
Attended Transfers:   ALLOWED

These may be set at campaign level (overrides) or globally.

Step 6: Set Campaign Access and Permissions

Assign Agent to Campaign

In the agent record or via the Campaigns panel:

1. Go to Campaigns → Edit campaign (e.g., SALES_OUTBOUND)
2. Add agent agent001 to the agent list, or
3. Add to the agent's campaign_id field in the database:

UPDATE vicidial_agents SET campaign_id = 'SALES_OUTBOUND' WHERE user = 'agent001';

Verify Campaign Settings

Ensure the campaign has the correct:

• Dial Method: MANUAL, PREVIEW, or POWER (affects agent workflow)
• Call Recording: ENABLED for compliance
• Auto-Dial Level: 0.8 - 1.5 (for POWER dial)
• Lead Pool: Campaign's lead source

Optional: Restrict to Specific Queues

If using inbound queues:

UPDATE vicidial_agents 
SET closer_group = 'SALES' 
WHERE user = 'agent001';

This restricts the agent to inbound calls routed to the SALES queue.

Step 7: Test the Agent Login

Via Vicidial Agent Screen

1. Direct agent to /agc/vicidial.php
2. Log in with username and password
3. Select the Phone field (should show extension, e.g., 1001)
4. Agent should see a "READY" or "PAUSED" status

Via CLI – Verify Agent in System

sudo asterisk -rx "vicidial show agents"

This ViciDial-specific command (if installed) shows:

Agent ID     User         Extension  Status    Campaign
100001       agent001     1001       READY     SALES_OUTBOUND

Alternatively, query the database:

mysql -u root -p asterisk -e "SELECT agent_id, user, phone_number, status FROM vicidial_agents WHERE user = 'agent001';"

Make a Test Call

1. Agent logs in and changes status to READY
2. Dial the agent extension: asterisk -rx "console dial 1001@from-vicidial-agents"
3. Agent's phone should ring
4. Verify audio quality and recording

Step 8: Configure Advanced Features (Optional)

Blind and Attended Transfers

Edit the agent's User Profile to enable transfer permissions:

UPDATE vicidial_users 
SET blind_transfer_enabled = 'Y', 
    attended_transfer_enabled = 'Y'
WHERE user = 'agent001';

Call Recording Configuration

ViciDial records calls by default. Verify:

ls -la /var/spool/asterisk/monitor/

Recordings stored as: YYYY-MM-DD-HH-MM-SS_<extension>_<direction>.wav

To set recording path per agent, edit campaign settings or globally in:

/etc/asterisk/extensions-vicidial.conf

Look for:

exten => 1001,1,MixMonitor(${MYFILENAME}.wav,b)

Voicemail Setup (Optional)

If agents need voicemail:

sudo asterisk -rx "voicemail show users"

Add voicemail to agent extension:

; In /etc/asterisk/sip-vicidial.conf
[1001]
mailbox=1001@default

Create voicemail box:

; In /etc/asterisk/voicemail.conf
[default]
1001 => 1234,Agent 001,[email protected]

Reload:

sudo asterisk -rx "voicemail reload"

Troubleshooting

Agent Cannot Log In

Symptom: "Invalid username or password" error

Solutions:

1. Verify user exists and status is ACTIVE:

   SELECT user_id, user, password, status FROM vicidial_users WHERE user = 'agent001';
   

2. Check agent record exists:

   SELECT agent_id, user, status FROM vicidial_agents WHERE user = 'agent001';
   

3. Verify password (ViciDial may hash it):

   UPDATE vicidial_users SET password = MD5('NewPassword123') WHERE user = 'agent001';
   

4. Check web server logs:

   tail -f /var/log/apache2/error.log
   tail -f /var/log/asterisk/messages
   

SIP Phone Not Registering

Symptom: Extension shows "Unregistered" or "Unreachable"

Solutions:

1. Verify firewall allows SIP (port 5060/5061):

   sudo ufw allow 5060/udp
   sudo ufw allow 5061/udp
   # Or for iptables:
   sudo iptables -A INPUT -p udp --dport 5060 -j ACCEPT
   

2. Check SIP config syntax:

   sudo asterisk -rx "sip show peers"
   sudo asterisk -rx "sip reload"
   

3. Verify phone has correct credentials and server:

   • Check phone's SIP logs (usually in phone settings)
   • Test with a different softphone (e.g., Zoiper)

4. Check Asterisk SIP debug:

   sudo asterisk -rx "sip set debug peer 1001"
   # Watch registration attempts in /var/log/asterisk/messages
   sudo tail -f /var/log/asterisk/messages
   # Then disable:
   sudo asterisk -rx "sip set debug off"
   

5. Verify NAT settings if agent is remote:

   nat=yes
   directmedia=no
   insecure=port,invite
   

Poor Audio Quality or One-Way Audio

Symptom: Agent or caller cannot hear the other party, or audio is choppy

Solutions:

1. Check codec compatibility:

   sudo asterisk -rx "sip show peer 1001"
   

   Ensure codec is ulaw or alaw, not gsm for production.

2. Enable media bypass correctly:

   directmedia=no    ; Force media through Asterisk (recommended)
   

3. Increase jitter buffer on phone (if supported)

4. Check packet loss and latency:

   ping -c 10 <agent-phone-ip>
   mtr <agent-phone-ip>
   

5. Verify RTP ports are open (5000-20000 UDP):

   sudo ufw allow 5000:20000/udp
   

Agent Logged In But No Calls Received

Symptom: Agent shows "READY" but doesn't receive inbound calls

Solutions:

1. Verify agent is assigned to a campaign:

   SELECT campaign_id FROM vicidial_agents WHERE user = 'agent001';
   

2. Check campaign has available leads:

   SELECT COUNT(*) FROM vicidial_list 
   WHERE campaign_id = 'SALES_OUTBOUND' AND status = 'NEW';
   

3. Verify closer group or queue assignment:

   SELECT closer_group FROM vicidial_agents WHERE user = 'agent001';
   

4. Check call routing in dialplan (/etc/asterisk/extensions-vicidial.conf):

   sudo asterisk -rx "dialplan show from-vicidial-agents@1001"
   

5. Verify campaign is active and not paused:

   SELECT campaign_id, active, dial_method FROM vicidial_campaigns 
   WHERE campaign_id = 'SALES_OUTBOUND';
   

Agent Cannot Dial Out

Symptom: Agent clicks dial but call doesn't complete

Solutions:

1. Check outbound context in extensions.conf:

   grep -n "from-vicidial-agents" /etc/asterisk/extensions-vicidial.conf | head -20
   

2. Verify SIP trunk configuration if using external dialing:

   sudo asterisk -rx "sip show peers" | grep -i trunk
   

3. Check campaign dial method:

   SELECT dial_method FROM vicidial_campaigns 
   WHERE campaign_id = 'SALES_OUTBOUND';
   

   Should be MANUAL, PREVIEW, or POWER.

4. Review call logs for errors:

   tail -f /var/log/asterisk/messages | grep -i agent001
   

5. Verify dial plan has outbound rules:

   exten => _X.,1,Dial(SIP/${EXTEN}@trunk)
   

Security Best Practices

When adding agents, follow these security measures:

1. Use Strong Credentials

UPDATE vicidial_users 
SET password = MD5('Tr0pic@l!Mang0#2024SecurePass') 
WHERE user = 'agent001';

Enforce complexity in /usr/share/astguiclient/vicidial_passwd_requirements.php if available.

2. Restrict SIP Access

In /etc/asterisk/sip-vicidial.conf, use insecure carefully:

; Production: More restrictive
insecure=no

; Development/Testing: More permissive
insecure=port,invite

3. Enable User-Level Restrictions

UPDATE vicidial_users 
SET user_level = 1,
    admin = 'N',
    active = 'Y'
WHERE user = 'agent001';

4. Change Default Passwords

Always require agents to change their initial password on first login:

UPDATE vicidial_users 
SET force_password_change = 'Y' 
WHERE user = 'agent001';

5. Monitor Agent Activity

SELECT user, last_login, active, status 
FROM vicidial_users 
WHERE user = 'agent001';

Log all administrative changes for compliance.

Summary

Adding an agent to ViciDial involves a coordinated sequence of steps:

1. Create User Account — Web admin or MySQL
2. Create Agent Record — Link user to phone and campaign
3. Configure SIP Extension — sip-vicidial.conf or auto-generated
4. Configure Phone/Softphone — Provide credentials and server details
5. Test SIP Registration — Verify in Asterisk CLI
6. Configure Phone Settings — Codec, recording, voicemail
7. Assign Campaign Access — Link agent to campaigns and queues
8. Test Login and Calling — Verify agent can log in and make/receive calls
9. Apply Security Measures — Strong passwords, restricted access

For production environments, automate this process with scripts or configuration management tools. Always test new agents with a sample campaign before full deployment.

Key files to remember:

• /etc/asterisk/sip-vicidial.conf — SIP phone definitions
• /etc/asterisk/extensions-vicidial.conf — Dialplan and call routing
• /var/log/asterisk/messages — Debug logs
• ViciDial database: asterisk — Agent and user tables
• /agc/vicidial.php — Agent login screen
• /vicidial/admin.php — Administrative interface

Regular monitoring of agent status, call logs, and system health ensures smooth operation in your ViciDial deployment.