How to Create Inbound Campaign in VICIdial — Complete Technical Guide
Introduction
How to create an inbound campaign in vicidial is a common task for VoIP engineers, call-center system admins, and telephony consultants. This guide walks you through prerequisites, exact admin steps, dialplan examples, SIP trunk / DID routing, testing and troubleshooting, advanced routing patterns (sticky-agent, skills-based), monitoring, and production hardening. The instructions are technical, step-by-step, and aimed at production-ready setups.
Quick note: this guide assumes you have admin access to your VICIdial server and basic Asterisk/SIP knowledge. For regulatory or legal compliance questions, consult a qualified expert.
how to create inbound campaign in vicidial — prerequisites and architecture overview
Before you configure anything in VICIdial, verify the following components are in place:
- A working VICIdial installation (web admin and AGC agent GUI access).
- Asterisk reachable and peered SIP trunk(s) from your carrier/provider.
- Administrative access to Admin → Carriers, Admin → DIDs, Inbound → In-Groups, Campaigns and Users pages.
- SSH access to the VICIdial server for dialplan/AGI changes when required.
- A test phone or a carrier test number to validate inbound calls end-to-end.
Network and telephony checklist:
- The carrier must peer to your server IP (or authenticate using credentials). Set context=trunkinbound in the carrier settings for inbound DID delivery.
- The provider sends the DID numbers in a consistent format (E.164 vs local); plan for number normalization in dialplan if needed.
- Confirm RTP port range, NAT settings, and codecs between carrier and server to avoid one-way audio.
Security and compliance:
- Use strong firewall rules (allow only carrier IPs to SIP ports) and enforce TLS/SRTP where supported.
- For US outbound/inbound contact centers ensure regulatory compliance is implemented separately; this guide does not provide legal advice. Disclaimer: This is technical guidance only; consult legal counsel for compliance requirements.
High-level flow — how VICIdial handles an inbound call
VICIdial handles inbound calls differently from simple PBX routing. Typical flow:
- Carrier -> SIP trunk -> Asterisk trunk inbound context -> VICIdial DID record (Admin -> Inbound -> DIDs) -> Route type: IN_GROUP or EXTEN -> In-Group queue or custom dialplan -> Agent (via meetme/bridge) or IVR.
Key terms and components:
- In-Group (Ingroup): VICIdial queue/skill group that holds calls for agents. Use this for standard queueing and skill-routing.
- DID: Public number (digit) delivered by the carrier; associated with an In-Group or extension.
- AGI: Asterisk Gateway Interface scripts used for custom logic (sticky-agent, lookup, external CRM pop).
- Campaign: VICIdial entity that binds agents to dialing modes and inbound allowances.
Visualizing the flow helps when troubleshooting: if the call never reaches the trunkinbound context, Asterisk will show no matching dialplan — start debugging at the carrier level.
Step-by-step — Create an inbound campaign in VICIdial (practical steps)
Follow this checklist to create and validate an inbound campaign in a standard VICIdial installation.
Step 1 — Add or verify your Carrier (SIP trunk)
- Admin → Carriers → Add a New Carrier.
Fill required fields: Carrier ID, Carrier Name, Account Entry (e.g., [MYCARRIER]), type=peer or user depending on provider, host=IP_or_FQDN. - Important: set context=trunkinbound in the carrier configuration so inbound calls use VICIdial inbound routing. Also set insecure=port,invite if carrier uses IP auth.
- If you use PJSIP or chan_sip, check register/auth parameters. Test registration: asterisk -rx “sip show peers” or pjsip show endpoints.
- Confirm connectivity by placing a test outbound call via that trunk (if allowed) or ask carrier to send test inbound calls.
Example Carrier snippet (chan_sip Account Entry):
[MYCARRIER]
type=peer
host=203.0.113.22
dtmfmode=rfc2833
context=trunkinbound
insecure=port,invite
disallow=all
allow=ulaw
Step 2 — Create In-Group(s)
- Inbound → Add a New Ingroup.
- Assign In-Group ID and In-Group Name (e.g., SUPPORT, SALES).
- Configure Handle Method (CID, RANDOM, etc.), Next Agent Call (ringall, roundrobin, oldest_call_finish), Drop Action, Drop Transfer Group and No Agents No Queueing policy.
- Set Queue Timeout and Priority depending on SLA.
Why this matters: The In-Group defines how calls are queued and who will see them in the agent GUI. Proper settings reduce hold time and minimize call loss.
Step 3 — Create the DID and route to In-Group (or EXTEN)
- Inbound → Add a New DID.
- DID Extension = number from carrier; normalize formatting (no plus signs unless configured).
- DID Route = IN_GROUP (recommended for standard queueing) or EXTEN (if you need custom dialplan/AGI logic).
- If IN_GROUP, select In-Group ID and Server IP. If EXTEN, set Extension and Extension Context to point to a custom dialplan that can call AGI scripts.
Sample DID settings for IN_GROUP:
- DID Extension: 12025550123
- DID Route: IN_GROUP
- In-Group ID: SUPPORT
- In-Group Call Handle Method: CID
- Server IP: 0.0.0.0 (ALL_SERVERS) or specific server IP
EXTEN route example: You might route to EXTEN if you need sticky-agent logic that determines the ingroup dynamically before handing off to the inbound AGI.
Step 4 — Configure Campaigns for inbound handling
- Admin → Campaigns → Add / Modify Campaign.
- Dial Method: choose INBOUND_MAN, MANUAL, RATIO or INBOUND as appropriate.
- Allow Inbound and Blended = Y to enable inbound handling and blended operations.
- Allowed Inbound Groups: tick the ingroups agents should handle. Submit and save.
Important campaign settings to review:
- Agent Wrapup, Auto Wrapup, Inbound Queue No Dial, Agent Display Queue Count, View Calls in Queue Launch — these directly affect agent UX and queue performance.
Step 5 — User & Phone settings (agents)
- Users → Show Users → Modify User: set Agent Choose Ingroups (0 = admin assigns, 1 = agent chooses).
- Ensure Agent Choose Blended is set to 1 if agents should switch between inbound/outbound.
- Admin → Phones: ensure extensions exist and softphones register correctly.
- Train agents to use the AGC/VICIdial agent GUI to grab calls if Agent Grab Calls in Queue = Y is set.
Step 6 — Optional: Implement Sticky-Agent or custom routing
For continuity (caller returns to same agent):
- Set DID Route to EXTEN and make the extension call an AGI (e.g., stickyagent.agi) that queries vicidial_list or recent call logs to find the last agent for that caller. If agent found and available, route to AGENTDIRECT ingroup; otherwise, fallback to default ingroup.
Minimal Dialplan example for EXTEN route:
exten => 999888777,1,Answer()
exten => 999888777,n,AGI(stickyagent.agi,${CALLERID(num)},48)
exten => 999888777,n,NoOp(agent ${agentid} ingroup ${ingroup})
exten => 999888777,n,AGI(agi-VDAD_ALL_inbound.agi,params...)
exten => 999888777,n,Hangup()
Reload dialplan after changes: asterisk -rx “dialplan reload”
Asterisk dialplan notes — commonly required tweaks
- Normalize caller ID/DID format: remove leading + or country codes if your provider includes E.164. Example: use Set() or string manipulation in dialplan before handing to VICIdial.
- Ensure trunkinbound context contains AGI(agi://127.0.0.1:4577/call_log) if you use call logging AGI calls from the carrier dialplan.
- For SIP one-way audio: verify RTP ports (10000-20000) and NAT / interfacing settings; check rtp.conf and Asterisk RTP diagnostics.
- For carriers using PJSIP: validate pjsip.conf endpoint and nat settings; review pjsip show endpoints for registration status.
Testing checklist — verify end-to-end inbound flow
- From an external phone (or carrier test console), dial the DID. Observe Asterisk CLI (asterisk -rvv) for the call flow.
- Confirm the DID hits the expected extension or In-Group and that VICIdial places the call in the queue.
- Log an agent into the assigned campaign and verify the call is offered to agent GUI and audio is bridged.
- Test edge cases: no agents available, multiple agents busy, overflow routing to backup ingroup, voicemail.
- If calls are received but voice is missing, check codecs, NAT, and SIP ALG on provider firewall.
Troubleshooting quick tips:
- asterisk -rvv during call to see if dialplan matches expected extension.
- asterisk -rx “sip show peers” or pjsip show endpoints to verify trunk status.
- Check VICIdial logs under /var/log/asterisk and the vicidial log tables.
- Validate DID Route in Admin → DIDs is set (IN_GROUP vs EXTEN).
Advanced design patterns and recommendations
Blended campaigns
- Blended campaigns let agents take inbound and outbound calls in the same session.
- Set Allow Inbound and Blended = Y and ensure Agent Choose Blended is set appropriately in user settings.
- Monitor agent occupancy to avoid burnout; use Agent Wrapup and queue limits.
Sticky Agent
- Useful for support desks that benefit from continuity.
- Implement using AGI lookup of prior vicidial_list entries and route to AGENTDIRECT ingroup or set a User variable.
- Test for false positives, and plan for failover to an alternate ingroup when the original agent is unavailable.
Multi-server / Cluster considerations
- If running VICIdial across multiple servers, ensure Server IP in DID and Ingroup matches the server handling the ingroup.
- For high availability, use load-balancing, database replication, and SIP trunk failover.
Security, monitoring and operational SOPs
- Monitor inbound call quality and trunk errors with periodic test calls.
- Keep backups of /etc/asterisk/ dialplans and astguiclient.conf.
- Log and rotate VICIdial logs. Keep 90–180 day archival storage depending on regulations.
- Implement rate-limiting or call-limits on carrier inputs to avoid toll fraud.
Example quick configuration summary (cheat sheet)
- Admin → Carriers: Add carrier; set context=trunkinbound.
- Inbound → In-Groups: Create SUPPORT with desired queue behavior.
- Inbound → DIDs: Add DID; DID Route = IN_GROUP; select In-Group.
- Admin → Campaigns: Allow Inbound; pick allowed ingroups.
- Users → Phones/Users: Ensure agent phone logins and ingroup access.
- (Optional) For sticky routing: DID route = EXTEN → custom AGI call → route to ingroup.
Common pitfalls and fixes
- Calls land in VICIdial but play IVR “you are the only one connected in conference”: check dialplan AGI call_log and whether the call reached VICIdial properly. Often a carrier format mismatch causes this.
- No audio: check codec negotiation, RTP ports, NAT, and SIP ALG. Use rtp set debug on and SIP debug for diagnostics.
- DID not mapped: ensure DID record exists and DID Route is correct (IN_GROUP or EXTEN).
Further reading & official references
- VICIdial forums and official docs for inbound configurations and community assistance.
- Tutorials and practical AGI examples for sticky agent and custom dialplan routing.
- Vendor blogs for cluster and scale recommendations.
Field-by-field explanation — In-Group and DID settings (admin reference)
Below are the key admin fields you will see when creating In-Groups and DIDs, with practical recommendations.
In-Group fields (explanations)
- In-Group ID: Short identifier used in scripts and configs. Use uppercase alphanumeric, e.g., SUPPORT.
- In-Group Name: Human-readable label shown to agents (Support — English).
- Handle Method: How call data is matched — CID is common and uses Caller ID lookup.
- Next Agent Call: Queue policy. ringall rings all agents; oldest_call_finish gives priority to the longest waiting call. Choose based on SLA and agent distribution.
- Drop Action / Drop Transfer Group: Where calls go when dropped or abandoned (voicemail, failover ingroup).
- No Agents No Queueing: Y (yes) means if no agents are available the call bypasses the queue to a fallback action. Use N to put callers on hold music.
- List ID: Optional: attach a list_id for lead matching and CRM lookups.
- Max Queue Time: Controls maximum wait before transfer/voicemail.
DID fields (explanations)
- DID Extension: The phone number string delivered by the carrier; must match what the carrier sends, or be normalized.
- DID Route: IN_GROUP (standard), EXTEN (custom dialplan), VOICEMAIL, or Hangup.
- Extension / Context (for EXTEN): The asterisk dialplan extension and context to be called (e.g., 999888777 in default).
- In-Group ID: If IN_GROUP route is chosen, point to the correct ingroup queue.
- Server IP: If you have multiple servers/clusters, set which server will own this DID’s queue.
These field explanations map to the web admin UI and to the underlying dialplan behavior observed during debugging.
Detailed AGI example — Sticky agent (annotated)
Below is a compact, annotated AGI-like pseudocode (simplified) to illustrate the steps used by sticky agent scripts. Use this as a conceptual template; adapt for your environment and secure DB credentials.
#!/usr/bin/perl
# stickyagent.agi (conceptual)
use Asterisk::AGI;
use DBI;
my $agi = new Asterisk::AGI;
# read caller number from AGI args
my $caller = $ARGV[0];
# open DB using config from /etc/astguiclient.conf
# query last call for this caller within X hours
my $sql = "SELECT user, modify_date FROM vicidial_list WHERE phone_number=? AND modify_date > now() - interval 48 hour ORDER BY modify_date DESC LIMIT 1";
# if row found -> $agentid = user; set ingroup to AGENTDIRECT
# if not found -> set ingroup to default INBOUND
$agi->set_variable("agentid",$agentid);
$agi->set_variable("ingroup",$ingroup);
exit 0;
After AGI returns, the dialplan can call agi-VDAD_ALL_inbound.agi to continue the standard VICIdial inbound flow. This pattern is used in production to improve the customer experience by reconnecting a returning caller to their last agent.
SQL and monitoring queries (quick references)
Use these queries to get live status and historical tracing.
- Live agents in a campaign:
SELECT user, campaign_id, status, last_state_change FROM vicidial_live_agents WHERE campaign_id='SUPPORT';
- Calls in queue for an ingroup:
SELECT COUNT(*) FROM vicidial_auto_calls WHERE lead_id IS NOT NULL AND campaign_id='SUPPORT' AND status='LIVE';
- Recent calls for a phone number (for sticky lookup):
SELECT lead_id, user, call_date FROM vicidial_log WHERE phone_number='12025550123' ORDER BY call_date DESC LIMIT 5;
Monitoring these tables helps build dashboards and alert for inbound performance.
Hardware and sizing (recommended baseline)
Below are ballpark recommendations for server sizing for inbound-heavy VICIdial deployments. Actual needs depend on concurrent calls, recording, and additional services (IVR, AGIs, realtime analytics). These are typical baselines used by operators and vendors.
- Small (10–30 agents): 4 vCPU, 8–16 GB RAM, 500 GB SSD (recording offload optional)
- Medium (30–100 agents): 8–16 vCPU, 16–64 GB RAM, 1–3 TB storage (fast IO)
- Large (100+ agents): Clustered architecture: separate DB, web, and telephony nodes; load-balanced trunks and redundant SIP carriers.
Storage note: allocate dedicated disks for call recordings; consider compression and archiving to lower costs.
Integration tips — CRM, screen-pop and CTI
- Use VDAD AGI hooks and campaign webhooks to trigger CRM screen-pop on agent answer events.
- For inbound IVR options, use Call Menu (IVR) configuration treated via Inbound → Call Menus or via custom dialplan that sets DIALSTATUS and ingroup variables.
- Securely pass lead metadata to CRM via HTTP callbacks or direct DB lookups; avoid exposing DB credentials on public networks.
FAQ
Q1: Do I need a separate DID per agent?
No — map multiple agents to the same In-Group. The In-Group handles distribution across agent phones.
Q2: Why does VICIdial say ‘no agents’ though agents are logged in?
Check campaign allowed ingroups, user ingroup assignment, and that agents selected blended if campaign requires it. Also validate agent phone registration.
Q3: Can I use Twilio or Telnyx as SIP trunk for inbound DIDs?
Yes. Many cloud SIP providers work; configure carrier accounts and map DID entries correctly. Use provider docs for SIP auth and necessary dialplan patterns.
Q4: How to test inbound routing without a traditional carrier?
Use a SIP softphone registered to a different account and call the DID from an external PSTN test number, or request a test call from your provider. CLI asterisk -rvv helps see the flow.
Q5: Does VICIdial support skills-based routing?
VICIdial supports prioritized ingroups and queue behaviors; for more advanced skill-based routing you may script custom logic or supplement with third-party ACD frameworks.
Conclusion
Setting up an inbound campaign in VICIdial might seem challenging at first, but with the right step-by-step approach, it becomes a structured and efficient process. From configuring your SIP trunks and DIDs to setting up in-groups, call menus, and routing strategies — every element plays a critical role in ensuring seamless inbound call flow and professional customer handling.
By mastering VICIdial inbound campaign setup, you gain complete control over call management, improve response times, and elevate caller satisfaction levels. Remember, the key is consistency — regularly monitor logs, analyze reports, and fine-tune your inbound strategy for optimal results.
Whether you’re a VoIP engineer, call-center admin, or technical consultant, understanding how to create an inbound campaign in VICIdial ensures that your contact center operates efficiently and professionally.
Disclaimer: The information provided is for educational purposes only. Configuration steps may vary based on your VICIdial version and telephony setup. Always perform testing before deploying changes in a live environment.