Configuring the VICIdial agent screen: scripts, labels, colors, and dispositions explained

The VICIdial agent screen is the single window your team stares at for an entire shift. Every call your dialer connects, every customer record that pops, and every choice an agent makes flows through it. Get that screen right and your people talk more and fumble less. Get it wrong and you pay for it in dead air, mis-keyed dispositions, and agents toggling between browser tabs to find a phone number. This guide walks through how the agent screen is assembled, with a deep focus on the part you control most directly: VICIdial Scripts.

We use the word agent a lot here, so let's anchor it. An Agent is the logged-in user who handles live calls inside the web interface. Whether they sit in your office or work as a remote agent from home, they share the same on-screen layout: customer information at the top, call controls, a script area, and a set of disposition buttons that close out each contact.

What the agent sees on a live call

When the dialer hands a connected call to a logged-in person, the screen fills with that contact's record. The phone number, name, address, and any Custom field data you loaded with the Lead all surface in labeled boxes. The agent reads the script, talks, and when the conversation ends they pick a Disposition that records the outcome: sale, no answer, callback, do-not-call, and so on. That outcome drives everything downstream, from Lead recycling to your reporting.

Three configurable surfaces shape the experience. First, the data layout, which is largely defined by your campaign and list fields. Second, the disposition buttons, which you define per campaign. Third, the script area, which is where most of your customization energy should go. Because scripts are where agents get their words, their links, and their embedded tools, the rest of this guide treats scripts as the centerpiece and connects the other pieces around them.

VICIdial Scripts: the core building block

A VICIdial script is a block of text and HTML that renders in a tab on the agent screen, with live customer data poured into it. It is the talk track, the rebuttal sheet, and increasingly a small application embedded right in the call window. An Agent script can be as simple as a greeting or as complex as an HTML form that writes back to your own system. If you have never built one, start with what a VICIdial script is before you wire anything to a campaign.

You manage scripts from the SCRIPTS section of the admin interface, which opens with a list of every script in the system and a link into each one. Creating a script is quick, but a few rules trip people up. Our step-by-step on adding a VICIdial script covers the create flow, and the companion piece on modifying an existing script covers edits. When a script outlives its usefulness, deleting a script is a deliberate two-step confirmation so nobody wipes a talk track by accident.

The fields that define a script

Every script is built from a small set of fields. Knowing what each one does, and its limits, saves you from rejected submissions and broken layouts.

Script ID

The Script ID is the short, unique key for the script. It must be between 2 and 20 characters, contain only letters and numbers, and carry no spaces or punctuation. The one rule that bites people: once a script is created, you cannot rename its ID. The only way to change it is to delete the script and recreate it under a new ID. That permanence is intentional, since campaigns and lists reference scripts by ID, but it means you should pick a clean naming convention up front. See the Script ID naming rules for a convention that scales, and why the Script ID cannot change for the reasoning behind the lock.

Script Name and Comments

The Script Name is the human-readable title, a short summary up to 50 characters with no spaces or punctuation. It is what you scan in the script list, so make it descriptive. The Comments field, up to 255 characters, is your changelog: a place to jot notes like the date you swapped an offer or who approved the wording. Teams that treat Comments as a discipline rarely lose track of why a script reads the way it does. Read more on the Script Name field and the Comments field.

Active flag and Admin User Group

The Active flag decides whether a script can be selected for use by a campaign. Flip it off and the script stays in the system but drops out of the picker, which is handy for retiring a talk track without deleting it. The Admin User Group field controls which admins can view the script; it defaults to --ALL--, meaning any admin can see it, but you can scope it to a single User group when different teams should not edit each other's content. Details live in the Active flag guide and the Admin User Group guide.

Script Color

Script Color sets the background color of the script as it renders on the agent screen. The default is white. You can type an HTML-safe color name, but spell it correctly or it will silently fail to apply, or pick a shade with the built-in color chooser. Color is more than decoration: distinct backgrounds for inbound versus outbound, or for a compliance-sensitive offer, give agents an instant visual cue about which conversation they are in. Our walkthrough on setting script color shows how to use it without making the screen unreadable.

Script Text and lead variables

The Script Text field is the heart of the whole thing. It holds the content the agent reads, and it accepts HTML so you can bold key lines, build a layout, or drop in a form. What makes scripts feel alive is the lead-variable syntax. Anywhere you write --A--field--B--, VICIdial replaces it at display time with the matching value from the current record.

A line written as Hello, can I speak with --A--first_name--B-- --A--last_name--B-- please becomes Hello, can I speak with John Doe please on the agent's screen. You can pull from a long list of fields: phone_number, title, first_name, last_name, address1, city, state, postal_code, email, comments, the Vendor lead code, list_id, lead_id, campaign, and many more, including any user_custom fields you defined. The full field reference is laid out in script variables explained and a quick-scan version in the lead fields list. For the single most common request, see adding the lead name to a script.

Before you push a script live, preview it. The script modification page has a Preview Script link that renders the layout with sample data filled into the variables, so you catch a typo'd field name or a broken tag before an agent does. The habit takes ten seconds and is covered in previewing a VICIdial script.

How a script renders: from lead to screen

flowchart TD
  A[Lead record selected] --> B[Campaign or in-group resolves which script]
  B --> C[Script Text loaded]
  C --> D[Replace --A--field--B-- with lead values]
  D --> E[Apply Script Color and HTML]
  E --> F[Render in script tab on agent screen]
  F --> G[Agent reads talk track]
  G --> H[Agent selects disposition]

The flow above is worth internalizing. The script you write is a template; the agent never sees raw --A--field--B-- markers because they are substituted the instant the record loads. If a variable shows up literally on screen, you almost always misspelled the field name, which is exactly what the preview step catches.

HTML scripts, iframes, and IGNORENOSCROLL

Because Script Text accepts HTML, a script can be far more than a paragraph of prose. You can build a structured layout, a checklist, or a small data-entry form. Our guide to building an HTML script shows how to format cleanly so the script reads well at a glance under the pressure of a live call.

The bigger lever is the iframe. You can embed a separate page inside the script tab and pass live data to it through the URL, so a record's lead_id, phone_number, name, and address travel straight into your own application or external page. That turns the script area into a bridge between VICIdial and your CRM, an order form, or a knowledge base, with no tab-switching for the agent. The mechanics, including how to feed variables through the query string, are in embedding an iframe in a script.

One quirk to know: an iframe can swallow the script tab's own scroll bars, leaving agents unable to reach content below the embed. The special variable IGNORENOSCROLL forces scroll bars to appear on the script tab even when an iframe is present. If your embedded page ever feels stuck or cut off, that flag is the fix, and it is explained in the IGNORENOSCROLL guide.

How scripts attach to campaigns, lists, and in-groups

Writing a script does nothing until something points an agent at it. There are three places a script can be assigned, and they form a clear hierarchy.

The most common attachment is at the campaign level. You set a default script for the whole outbound Campaign, and every call on that campaign shows it unless something more specific overrides. Walk through it in assigning a script to a campaign.

You can also assign a script per list. A list-level script overrides the campaign default for the leads in that list, which is how you run one offer for fresh leads and another for an aged or recycled segment inside the same campaign. The how-to is assigning a script to a list.

Inbound traffic works differently. An inbound call arrives through an Ingroup, so the script is attached to the in-group rather than to a campaign. That is what lets a single agent answer several queues and see the correct talk track for each one. See assigning a script to an in-group.

camp_script versus in_script

VICIdial exposes two related variables you can reference inside script content: camp_script and in_script. The camp_script value is the script tied to the active outbound campaign; in_script is the script tied to the in-group an inbound call came through. They exist because a single agent in a blended operation can take outbound and inbound calls in the same session, and the two paths resolve their scripts independently.

In practice this means your outbound talk track and your inbound talk track can coexist without stepping on each other, and an advanced script can even branch on which one is populated. If you run blended teams, the distinction is the difference between an agent always seeing the right words and an agent reading a sales pitch to someone who called in for support. The full comparison, with examples, is in camp_script versus in_script.

flowchart LR
  A[Call to agent] --> B{Outbound or inbound}
  B -->|Outbound| C[camp_script from campaign]
  B -->|Inbound| D[in_script from in-group]
  C --> E[Script tab on agent screen]
  D --> E
  E --> F[List-level script overrides campaign default]

Multiple script tabs

A single tab is not always enough. You can present more than one script on the agent screen at once, for example a primary talk track beside a rebuttal sheet or a compliance disclosure. Multiple tabs keep reference material one click away instead of buried in another browser window, which matters when an agent is talking and reading at the same time. The setup is covered in adding multiple script tabs.

How this fits agent productivity

Pull back from the field list and the point becomes clear: the agent screen is a productivity surface. Every second an agent spends hunting for a phone number, re-reading a clumsy sentence, or alt-tabbing to a separate system is a second not spent talking, and it compounds across thousands of calls a day.

• Lead variables remove copy-paste. The customer's name and details are already in the words, so the agent reads instead of looks up.
• Color coding cuts mistakes. A distinct background tells an agent at a glance whether they are inbound or outbound, sales or service.
• Iframes keep work in one window. An embedded order form or CRM view means no tab-switching mid-conversation.
• List and in-group overrides keep the right words in front of the right call, which protects compliance and lifts conversion.

A clean script also shortens Wrap-up time, because an agent who was guided through the conversation knows exactly which disposition to pick when it ends. The screen and the script are not separate from your numbers; they are upstream of them.

Putting it together

Start with a clean Script ID and a descriptive Script Name. Write your Script Text with lead variables so it speaks to each customer by name. Set a color that signals the call type. Preview it, then attach it where it belongs: campaign default, list override, or in-group for inbound. Use iframes when you need a real tool in the tab, and remember IGNORENOSCROLL if the embed eats your scroll bars. Done well, the agent screen stops being a form to fill and becomes a guided path through the call.

If you are weighing a hosted VICIdial setup that comes tuned for this kind of agent experience, take a look at our plans and pricing to see what is included out of the box.

Ready to put a polished agent screen in front of your team without wrestling the server yourself? Compare VICIfast pricing and get a configured dialer running fast.