VICIdial inbound email and chat, explained

Most people think of VICIdial as a phone system, and it is. But the same machinery that pulls up a customer record and ties an agent to a live call can do the same thing for an incoming email or a website chat. An inbound email arrives, VICIdial finds the matching customer, drops their record on the agent's screen, and locks that agent so no call jumps the queue. The agent replies, picks a Disposition, and is free again. Chats work the same way. This guide walks through how inbound email and chat actually function, the fields you set on each group, and how VICIdial decides which agent gets the next one.

The whole point of folding email and chat into the dialer is that you stop running three separate tools. One agent, logged into one screen, can handle a call, then an email, then a chat, with the same Lead record and the same dispositions behind all three. That is what a Blended dialing floor looks like, and email and chat groups are how you build the non-voice half of it.

How inbound email works in VICIdial

An Email Group lets agents handle inbound emails exactly the way they handle inbound calls. When a new email lands, VICIdial automatically pulls up the customer's lead information on the agent's screen and locks that lead, so the agent will not also be sent a call or a second email while they are working it. Once the agent responds and dispositions the lead, like any other call, they are immediately available again for the next call or email.

There is a server-side piece that has to be in place first. The feature has to be enabled in Admin, an extra keep-alive flag has to be added to one of your servers, and a parser process has to run on a schedule. That parser, AST_inbound_email_parser.pl, runs once a minute and must be added to the crontab of only one server in your setup. It is the part that checks the mailboxes, decodes each message, matches it to a lead, and hands it to the routing logic. Running it on more than one box would mean two servers fighting over the same inbox, so it stays on a single server.

Here is the flow, end to end, from an inbound message to an agent's screen.

sequenceDiagram
  participant C as Customer
  participant M as Mailbox
  participant P as Email Parser
  participant V as VICIdial
  participant A as Agent
  C->>M: Sends email
  P->>M: Polls once per minute
  M-->>P: New message
  P->>V: Match lead and queue
  V->>V: Route to next agent
  V->>A: Pull lead and lock
  A->>C: Reply and disposition

Notice that the agent never goes hunting for the email. The same way a call rings into an Ingroup and gets handed to whoever the dialer picks, an inbound email is queued and pushed to an available Agent. The lead lock is the key behavior: while one agent owns that record, nobody else can be sent a call or email tied to it.

Email Groups and their fields

You create an Email Group from the Inbound section, the same place you manage your ingroups. The walkthrough for that lives in how to add a VICIdial Email Group, and once a group exists you edit everything else on the modification screen, covered in how to modify a VICIdial Email Group. The Group ID, Group Name, and Group Color are required before you can submit; everything else is optional and can be added later.

The first thing to get right is naming. The Group ID is the short name of the group and has to be 2 to 20 characters with no spaces, and it cannot match any other ingroup or campaign ID in the system. Once you submit it, you can never edit it; the only way to change a Group ID is to delete the group and re-create it. The Group Name is the full label and runs 2 to 30 characters. The rules and the why-it-matters are spelled out in the VICIdial Email Group ID and Name.

Group Color is the color that shows in the agent client app when an email comes in on this group, so agents can tell at a glance which queue a message belongs to. It must be 2 to 7 characters, and if you use a hex value you have to put a # at the front or the agent screen will not render correctly. The gotcha and a few sane color choices are in the Email Group color on the agent screen.

The Active field decides whether the group is live or parked; it defaults to Y. Setting it to N is how you take a queue out of service without deleting it, and the trade-offs are covered in the Email Group Active field. You will also see the In-Group Email Date, which simply records the last time an email was directed to the group, handy for spotting a queue nobody is feeding.

Three Web Form slots, Web Form, Web Form Two, and Web Form Three, hold custom addresses that open when the matching button is clicked on the agent's screen. These let an agent jump from the email into your CRM or a reply tool with the lead's data already filled in. To pass your custom fields into the URL you add &CF_uses_custom_fields=Y to the address. Setting these up well is the difference between a useful workflow and an agent retyping data, and the Email Group web forms walks through it. A Web form that carries the lead's fields turns a reply into one click.

Two URL fields run quietly in the background. The Start Email URL is hit each time an agent receives an email, and the Dispo Email URL is hit each time an agent dispositions one; neither is ever shown to the agent. They use the same variables as the web form fields and scripts, and the dispo URL can also pass dispo and talk_time so an external system learns the outcome and how many seconds the agent spent. That is how you wire VICIdial to a downstream system, and it is the same mechanism that lets a SALE lead get moved to a follow-up list for quality control later.

The remaining fields, Status Group Override, QC Enabled and the QC settings, are about dispositions and quality review. The override lets this group use its own status set instead of the campaign statuses, though system statuses always still appear. The single most important routing field, Next Agent Email, gets its own section below.

Routing the next email to an agent

Next Agent Email is the field that decides which available agent receives the next message, and it works just like the next-agent setting on a voice ingroup. You are really choosing a fairness policy: spread the work evenly, reward your best people, or honor a priority order. The full menu and when to use each is in VICIdial next agent email routing. This is VICIdial's flavor of Skills-based routing, layered on top of the same Next agent call logic that distributes calls.

The two methods people reach for first are the oldest and fewest families. The oldest options order agents by time: oldest_call_finish and oldest_inbound_call_finish send the next email to whoever has been waiting longest since they finished one, while the oldest_call_start variants order by who was last sent an email and tend to even out totals over a shift. The fewest options count instead: fewest_calls sends to whoever has taken the least emails from this specific group, and fewest_calls_campaign counts across the whole campaign. The practical difference between counting messages and timing waits is the subject of email routing, oldest versus fewest. There is also longest_wait_time, which orders by how long an agent has actively been waiting for an email.

If you want some agents to simply handle more volume than others, two methods skew the distribution. overall_user_level orders by the user_level set on each agent in the users table, so a higher level pulls more emails; this is the lever for email routing by user level. The grade_random methods, ingroup_grade_random and campaign_grade_random, give higher-graded agents a higher probability of getting the next email without making it a hard rule, which keeps a little randomness in the mix; that softer approach is covered in email grade-random routing.

When you want explicit control, the rank methods follow an order you set by hand. inbound_group_rank orders agents by the rank given to them for that specific group, highest to lowest, and campaign_rank does the same across the campaign. You assign those numbers at the bottom of the modification screen, where VICIdial shows every agent's rank, grade, and the count of emails they have taken from the group today. That panel is explained in Email Group rank, grade, and count, and the step-by-step of assigning ranks is in how to rank agents for an Email Group. Ranking is how you build an Agent rank order so your strongest people see the most messages.

There is also random, which simply orders by the random value in the live_agents table, and ring_all, which rings every available agent at once and gives the email to the first to answer. ring_all ignores wait time and ranking entirely, so it is meant for a handful of agents on a low-volume group, not a busy queue. The chart below is a quick way to pick a method.

Sitting above all of these is Queue Priority. It defines the order in which emails from this group are answered relative to calls and emails from the other groups an agent is logged into. If you set this group's priority even one digit higher than the campaign or the other groups, it always takes precedence. That makes it a blunt but effective way to say a high-value queue gets served first; the details are in Email Group queue priority. This is the same idea as Queue priority on a voice ingroup, and the two interact: priority decides which queue gets served, Next Agent Email decides who in that queue gets the message.

A short way to choose: if fairness is the goal, use a fewest or oldest method; if you want your strongest people busy, use rank or user_level; if you want a soft skew, use grade_random. Reserve ring_all for tiny queues.

Inbound chat groups

Chat Groups let agents handle inbound website chat sessions the same way they handle inbound calls. An incoming chat pulls up the customer's lead, locks it so the agent will not also be sent a call or chat, and when the session ends the agent dispositions the lead and is free again. The feature is enabled in Admin System Settings. If you have already set up an Email Group, the chat screens will feel familiar; most of the fields are the same.

Naming follows the same rules: Chat Group ID and Name are 2 to 20 characters with no spaces, the ID cannot duplicate any other ingroup or campaign, and once created the ID cannot be changed. Group Color, Active defaulting to Y, the three Web Form slots, Queue Priority, Status Group Override, and the Start Chat and Dispo Chat URLs all behave just like their email counterparts. The Dispo Chat URL can likewise pass dispo and talk_time to a downstream system.

Chat adds a few fields email does not have. Default List ID is the list a new chat customer is dropped into when they are not already found in the system, so a stranger who opens a chat still becomes a real lead in a known place. Customer Chat Screen Colors lets you set the colors and logo the visitor sees on the chat widget, which defaults to a blue scheme. A Customer Chat Survey Link, with matching survey text, can send the customer to a survey after the session ends. Like the email screen, the bottom of the chat group page shows every agent's rank, grade, and chat count for the day.

Putting it together and getting started

The pieces fit together in a predictable order. The parser feeds messages in, Queue Priority decides which queue an agent serves first, and Next Agent Email decides who in that queue is handed the message. Email and chat both ride on the same lead lock and the same Disposition flow as voice, which is what makes a single agent able to flip between a phone call, an email, and a chat without ever leaving the screen. Get the naming right first, since IDs cannot be changed, then pick a routing method, then tune Queue Priority once you see how the queues actually load.

If you are wiring this up for the first time, the most common stumbles are the server-side ones: the feature not enabled, the missing keep-alive flag, or the parser cron line on the wrong number of servers. After that, it is configuration, and the spoke guides above cover each field in detail, from adding a group to setting queue priority.

If the part standing between you and a blended floor is the server itself, that is the easy part to solve. VICIfast provisions a dedicated, secured VICIdial box in under 40 seconds, with the modules and crontab plumbing already in place, so you can spend your time on routing instead of Perl dependencies. You can see plans and pricing and have a working dialer the same afternoon.

Already running calls and want to add email and chat next? The setup above works on any standard VICIdial install, and a managed box keeps the parser and keep-alive flags out of your hands. When you are ready, compare VICIfast plans and bring your own carrier on day one.