agc_2-X/docs/Email_user_manual.txt

EMAIL HANDLING DOC		Started: 2012-12-23	Updated: 2022-12-08

(example of how to set up an email account with Gmail is at the bottom)


INSTALL:

   Perl CPAN modules required for email to function:
cpan
install LWP::UserAgent
install HTML::Entities
install HTML::Strip
install HTML::FormatText
install HTML::TreeBuilder
install Switch
install Time::Local
install MIME::Decoder
install Mail::POP3Client
install Mail::IMAPClient
install Mail::Message
install Mail::Box
install IO::Socket::SSL
install MIME::Base64
quit



DESCRIPTION:

In order to use this feature, the very first thing you need is an email account 
to handle your incoming emails.  This account must operate under either the IMAP 
or POP3 mail protocols, as these are currenty the only two that Vicidial 
supports.  You can sign up for a free Gmail account, which uses the IMAP 
protocol, or a Yahoo! account, which uses POP3.  People using this feature may 
find it more feasible to use an email that operates under the IMAP protocol.  
The reason for this is that if you use a POP3 account, messages sent to it will 
be erased upon discovery by your Vicidial installation.  This is because the 
programming involved does not allow POP3 accounts to have their email messages 
marked to prevent repeat pullings from the mailbox, and therefore the email 
message must be erased once imported, whereas IMAP accounts are supported such 
that they can be marked as read.

Once you have created your new email account, you must set it up in the dialer 
so that the dialer will be able to connect to it and collect any emails in it 
and import those into the dialer.  First, the dialer must have the "Emails 
Enabled" setting turned on under the "System Settings" page in the "Admin" 
section.  Ensure that this value is set to "1" and if not, switch it to that and 
submit the changed system settings.  Now, you must also turn on the modification 
privileges for the users who will be able to modify email accounts.  This can be 
found under the "Admin Interface Options" section on the user's account page and 
is called "Modify Email Accounts".    

With the email settings enabled and having users who can update email 
account-related information, you must now create an email group that Vicidial 
will "file" incoming emails under so that they can be routed to the appropriate 
agents in the appropriate campaigns.  This is done by clicking on the "Inbound" 
link at left.  From the list of links that appear beneath the "Inbound" link, 
click on the "Add New Email Group".  This will take you to a form that you must 
fill out.  All new email groups must be given a group ID and a group name.  
Click the "SUBMIT" button and if the form was filled out correctly, you will 
have created an inbound group that will handle email messages, as opposed to the 
"regular" in-groups which handle phone calls.  Remember to set the "Active" 
setting to "Y" once you're ready to have email messages collected and stored.

When the email setting is enabled and the email in-group is created, you can 
create the email account settings that will tell the dialer where and how to 
connect to your email account and the in-group to file them under.  Under the 
"Admin" section, click on the "Email Accounts" setting.  Click on the "Add a New 
Account" link at the top of the page and you will be taken to the form you must 
fill out with all the necessary information for Vicidial to connect to your 
email account.  You must set an email account ID and an email account 
description, both of which are relatively arbitrary.  More importantly, make 
sure the proper protocol (IMAP or POP3) is selected, and that the email reply-to 
address (which is just the actual email address on the account) and the email 
account server is entered properly (ex: gmail is imap.gmail.com).  You also need 
to enter the username and password that is used to access the account, and also 
the frequency that Vicidial should check your account for new emails.  Some 
email accounts do not allow more than a few logins over a set amount of time, so 
at the moment the highest rate of frequency that Vicidial will allow is one 
login attempt every five minutes.  Fill out the remaining fields (click the "?" 
button by any field that needs explaining - if you are familiar with inbound 
groups, most of these fields work in the same way) and submit the new email 
account.  When you are ready to have Vicidial start checking it for emails, be 
sure the "Active" setting is set to "Y".

Also make sure that any campaigns that you want to have email handling active on
should have the "Allow Emails" setting set to Y.

The checking of email accounts is handled by a cron job that should only be 
active on ONLY ONE server on your Vicidial installation:

* * * * * /usr/share/astguiclient/AST_inbound_email_parser.pl

other allowed run time options for this script:
  [--debug] = verbose debug messages
  [--debugX] = extra verbose debug messages
  [--force-check] = forces check of email
  [--ssl-no-cert] = ignores ssl cert verification

This script will check to see if any active email account is due to be checked 
for new messages, per the "Email Frequency Check Rate" setting on the active 
accounts.  If new emails are found in an active account, one of two things will 
happen, depending on the account protocol.  As stated earlier, IMAP accounts 
will have the message marked as read, so it will not be pulled into your 
Vicidial database again, but in POP3 accounts the message will be erased.  When 
this script finds an email to insert into the Vicidial dialer, it will parse out 
the pertininent information from the header and body of the email, and then 
based on the "In-Group Call Handle Method" setting for the associated email 
account, it will insert the data as a new lead in the vicidial_list table or 
check the vicidial_list table for the email address and use the lead_id from the 
found record to create a new lead in the vicidial_email_list table.  Both tables 
can be tied together by the lead_id column.  Also, if the email message has any 
attachments, those will be inserted into the inbound_email_attachments table, 
with the email_row_id column in that table tying back to the column of the same 
name in vicidial_email_list.

You also need to make sure that the "E" keepalive is present in the 
/etc/astguiclient.conf file of ONLY ONE of the servers on your cluster. Without 
this enabled, the calls will not get to agents properly. This runs the 
/usr/share/astguiclient/VD_email_inbound.pl script and keeps it running at all 
times. The determination of the order in which emails are distributed out to 
agents and the determination of the order of which agents are to receive emails 
are both handled by this script.

This is a perpetually-running script that is constantly checking the 
vicidial_email_list and vicidial_xfer_log tables for any email messages that 
need to be queued and handled by an agent.  Emails from transfer in-groups 
always take precedence over regular incoming emails, regardless of the queue 
priority setting.  However, the queue priority is taken into consideration if 
multiple transfer in-groups have emails that need handling.  This script first 
checks the vicidial_xfer_log table for email messages that have been transferred 
by an agent, and then checks the vicidial_email_list table for any new email 
messages that have not yet been handled by any agent.  Once a list of emails to 
queue has been generated, this script go through each email one at a time, and 
will take the in-group the email belongs to and check the system for any agents 
in a READY or CLOSER status who are currently taking emails that in-group.  If 
more than one agent is available, the agents selected to receive the messages is 
determined by the "Next agent call" setting for the group the message belongs 
to.  The script will proceed in this fashion until all email messages have been 
assigned or all active agents have been given a message.  The script will then 
sleep for a brief period and then repeat the process.  

With the email messages being imported into your Vicidial system, you can now 
set up campaigns to distribute the messages out to agents who log in to the 
appropriate campaigns.  This is identical to the procedure for setting up 
inbound calls.  All you do is view the "Detail View" for the campaign(s) that 
is/are to receive these emails, and under the "Allowed Inbound Groups" section, 
check the box next to each email in-group that the campaign will take.  
Campaigns must be set as RATIO, INBOUND_MAN, or any of the ADAPT dial 
methods(?).  Emails can even be transferred to other agents, similar to 
transferring phone calls.  This is done in the same way; set up an email 
in-group, and then under the "Detail View" setting for a campaign, check the box 
for that group under the "Allowed Transfer Group" to allow emails to be 
transferred to that ingroup, and in turn another campaign can be set up to 
accept these transfers by making that in-group an "Allowed Inbound Group".

Once this is all set up, emails will start to come in to your system.  In the 
agent interface, there is now a new tab called "EMAIL" at the top of the screen. 
 This is the default call launch for email messages, and is the screen that will 
automatically be displayed for the agents.  From here, agents can see the sent 
message and the address of the person who sent it (and sometimes the sender 
name), and can even view any attachments the sender included.  Agents can type a 
plain text response to the incoming message, and can also send back attachments 
of their own.  The system will notify the agent if an email attempt is 
successful, and these message "calls" can be terminated in the same way as a 
regular phone call, by clicking the "HANGUP CUSTOMER" button or using HotKeys.

The order in which incoming emails will be distributed to the agents is 
determined by the queue_priority setting on each in-group, and then by the date 
in which the email was sent.  In other words, unless one email-group has a 
higher priority over another, agents will always receive the oldest emails 
first.  In addition, email in-groups will also prioritize agents based on the 
"Next agent call" setting for each ingroup.  Agents can be prioritized based on 
the number of calls/emails they have received, or by rank or by one of the time 
values stored in the vicidial_live_agent table.



PROBLEMS:

If you are having issues with emails going out properly from an agent, you 
should test an email from your webserver using the 'pine' CLI email application. 
If you need to install pine just run the following in OpenSuSE(the Linux distro 
that vicibox uses):

zypper install alpine

If you are still having issues, make sure that postfix email system on your 
webserver is started up.

/etc/init.d/postfix start

If that worked, then it probably isn't starting up on boot, so you need to run 
this command:

chkconfig postfix on



EXAMPLES:

Example configuration instructions with Gmail:

If you'd like to use Vicidial's inbound email feature but do not have an email 
account to collect email messages, you will need to create an email account 
first.  Gmail offers free email accounts that can be accessed under either the 
IMAP or POP3 protocols.

To create a new Gmail account, open your web browser and go to: 

www.gmail.com

Assuming that you aren't currently logged into an existing Gmail account, in the 
upper-right corner, there will be a button labeled "CREATE A NEW ACCOUNT", which 
you should click.

On the next page, fill out the form to create your new email account.  The page 
will prompt you on all the necessary fields to fill out, and you should click 
the "Next Step" button at the bottom of the screen when finished.  If you've 
filled out the form properly, Gmail will show a welcome message, and you have 
successfully created your email account.  Remember the user name and password 
for when you set up the email account in Vicidial.

With Gmail, the recommended email account protocol is IMAP and the email account 
server for this is "imap.gmail.com" – this information will also be used during 
the account setup in Vicidial. Gmail has more recently set a maximum email 
frequency checking limit by outside applications of no more than once per 10 
minutes, so you may want to confirm that your VICIdial Email Accounts "Frequency
Check Rate" setting is set to 10 or higher.

You can also use POP3 protocol with Gmail.  For that, the email account server 
is pop.gmail.com.  However, when the POP3 protocol is being used on an account, 
when unread emails are detected, once their information has been imported into 
the database, then the email message is erased.  This is a limitation of the 
software that "sweeps" the email account, which is why IMAP is the preferred 
protocol.

There are several settings within the Gmail "Settings" screen for IMAP settings
that you may need to modify to ensure that VICIdial has access to your mailbox.

You may need to go into your Google Account "Security "settings and enable the
"Less secure app access" setting in order to use the IMAP connection for email.

You may also need to manually verify access a second time through Google logging
in as the user through a web browser to get VICIdial to be able to log in 
successfully.


NOTES:

- You may need to install gcc, make and associated libraries in order for some perl modules to install properly. To do this on Vicibox or OpenSuSE you can use the software management utility in "yast". Just enter 'yast' on the Linux command-line, then go to Software -> Software Management -> Search Phrase, then enter in the perl module name(i.e. "FormatText"), then in the results section you'll highlight the module and press <space>. Then press F10 to accept and confirm the module to be installed, then F10 again to finish. After that you can do it again for any remaining modules that are needed.

- If you see the following error:

*******************************************************************
Using the default of SSL_verify_mode of SSL_VERIFY_NONE for client
is depreciated! Please set SSL_verify_mode to SSL_VERIFY_PEER
together with SSL_ca_file|SSL_ca_path for verification.
If you really don't want to verify the certificate and keep the
connection open to Man-In-The-Middle attacks please set
SSL_verify_mode explicitly to SSL_VERIFY_NONE in your application.
*******************************************************************
at /usr/lib/perl5/site_perl/5.12.1/Mail/IMAPClient.pm line 338

go into the IMAPClient.pm file at the path above and added the following line 
below 338 and the message should go away:

SSL_verify_mode => 'SSL_VERIFY_NONE',




- If you see the following error:

SSL_verify_mode must be a number and not a string at /usr/lib/perl5/site_perl/5.12.1/IO/Socket/SSL.pm line 2251.


Edit the "SSL.pm" file that is shown in the error you received:

Line 2251, change:

die "SSL_verify_mode must be a number and not a string";

To:

$verify_mode = '0';


Save it(since the file is most likely read-only, you might have to force save[in 'vi' that's ':w!'])

Then try running the email script again:

 /usr/share/astguiclient/AST_inbound_email_parser.pl --ssl-no-cert --debugX --force-check




- Email log errors compaining about "Sender address rejected: need fully-qualified address":

You have to give your server a Fully Qualified Domain Name(FQDN), if only locally.
1. On your local DNS server, or your real-world DNS server for a domain you control, add a new A NAME with the IP Address of the server you will be assigning
2. Edit the "/etc/hostname" file on that server and enter in the FQDN that you have added to DNS
3. Edit the "/etc/hosts" file on that server and enter in the new FQDN and the local IP Address, with another entry for the real-world IP Address if there is one
4. Reboot your server.

You may also need to define your FQDN in your email configuration files, for example if you are using Postfix for email, in the “/etc/postfix/main.cf" you will need to change the “myhostname” setting to your FQDN(i.e.: “myhostname = dialer01.dialer-domain.com”). Also, if you are using a mail relay server, you will need to set the “relayhost” setting as well(i.e.: “relayhost = mail.relay-domain.com:587”).