As already written above, CapiSuite comes with default scripts giving you the most used communication functions of an answering machine and a fax device.
This section should help you to use them for your daily needs.
The scripts distributed with CapiSuite give you the following main functions:
multi-user answering machine
different users using different numbers and different announcements are supported
incoming calls are saved and sent to the user by email
the delay until a call is accepted and the maximum record length are freely adjustable
silence is detected and the call terminated after an adjustable silence period
incoming fax calls are automatically detected and received
comfortable, menu-controlled remote inquiry functions are supported telling you the date/time when the call was received and the called and calling numbers.
record your own announcement via the remote inquiry menu
nearly each setting is configurable globally but can be overwritten for each user
fax machine
different users using different numbers are supported
incoming faxes are stored and sent to the user by email
command line tool for faxing PostScript documents included
number of tries and delays for sending faxes freely configurable
currently supports only one ISDN controller for outgoing faxes
As my native language is german, all waves distributed with CapiSuite are in german only. If someone wants to provide waves in english (or any other language), please contact me. Thx!
Here follows a rough overview of how the scripts work in general. I will only explain the behaviour which is important for the user here. If you want to understand the internals, please refer to Section , “Structural overview of the default scripts”.
When an incoming call is received, several lists for the different users are searched for the called number. The different users can define their own numbers in the configuration (see below). So the scripts decide by looking on the called number to which user the call destinates. If they find the number in the voice- or fax-number list of any user, they'll answer the call with this service and give the caller the possibility to leave his message or send his fax.
The received document is then saved to a local directory in some native format and also converted to a well-known format and mailed to the user along with some details of the call. Voice calls are sent as a WAV attachment, while fax calls are sent as PDF documents attached to the mail.
So you'll normally get your incoming calls as a mail to a specified address - but they're also saved in the local filesystem to be on the safe side. It's your task to delete old files you don't need any more. For further instructions, please see Section , “Deleting old files”.
There's also the possibility to do a remote inquiry on the answering machine. The caller is presented a menu where he can choose to record his announcement or to hear the saved voice calls. He will be told how many calls are available, from whom and when they were received and so on. He'll also be able to delete recorded calls he doesn't need any more.
Another script will check special queue directories for fax send jobs regularly. To put jobs in this directory, the commandline tool capisuitefax is provided. See Section , “Using CapiSuite together with the default scripts” for further details on this.
There are some important options which the scripts need to know before you can use them - things like the users' numbers and some details of how to handle the calls.
These options are read from two configuration files. Each configuration file is divided into one or more sections. A section begins with the section name in square brackets like [section] while the options are key="value" lines.
Each file must have a special section called [GLOBAL] and one section for each user called [<username>] (with <username> being a valid system user).
The [GLOBAL]-section defines some global options like pathnames and default settings for options that can be overridden in the user-sections. The user-sections hold all the options which belong to a particular user.
All options for the two files are described in short below. For all details, please see the comments in the sample configuration files installed with CapiSuite.
This file holds all available config options for the fax services (fax receive and send).
It's read from /etc/capisuite/fax.conf or /usr/local/etc/capisuite/fax.conf (depending on the installation).
This directory is used to archive sent (or failed) jobs. It must exist and the user CapiSuite runs as must have write permission to its subdirectories. Two subdirectories are used:
Jobs finished successfully are moved to this directory.
Job which have failed finally end up here.
This option is mandatory.
This directory is used to store fax jobs and received documents to. It must exist and the user CapiSuite runs as must have write permission to it. It will contain one subdirectory for each configured user (named like his userid). The following subdirectories are used below the user-specific dir:
Received faxes are saved here.
Fax files to be sent are queued here by capisuitefax.
This option is mandatory.
When a fax can't be sent to the destination for any reason, it's tried for several times. This setting limits the number of tries. If all tries failed, the job will be moved to the failed dir (see fax_spool_dir) and the user will get a mail.
This option is optional. If not given, it defaults to 10 tries.
When a fax can't be sent to the destination for any reason, it's tried again. This setting specifies the delays in seconds between subsequent tries. The different values are separated with commas and no blanks. The list should have send_tries-1 (see fax_send_tries) values - if not, surplus entries are ignored and missing entries are filled up with the last value. The default should just be ok giving you increasing delays for up to 10 tries.
This option is optional. If not given, it defaults to the list shown above.
If you have more than one ISDN controller installed (some active cards for more than one basic rate interface like the AVM C2 or C4 are also represented as multiple controllers for CAPI applications like CapiSuite), you can decide which controller (and therefore which basic rate interface) should be used for sending your faxes. All controllers are numbered starting with 1. If you're not sure which controller has which number, increase the log level to at least 2 in CapiSuite (see Section , “Configuration of CapiSuite”), restart it and have a look in the log file where all controllers will be listed then. Unfortunately, CapiSuite isn't able to use more than one controller for sending faxes at the moment, so no list is allowed here. If you have only one controller, just leave it at 1
This option is optional. If not given, it defaults controller 1.
This number is used as our own number for outgoing calls. If it's not given, the first number of fax_numbers is used (see Section , “The user sections”). If this one is also empty, the user can't send faxes. Please replace with one valid MSN of your ISDN interface or leave empty. This value can be overwritten in the user sections individually.
This option is optional. If not given, it defaults to empty.
Default setting which defines how many seconds we will wait for a successful connection after dialing the number. This value can be overwritten in the user sections individually.
This option is optional. If not given, it defaults to 60 seconds.
If anything is entered here, it will be used as a prefix which is added to any number given to capisuitefax as prefix. This is e.g. very helpful if your ISDN adapter is connected to a PBX which needs "0" for external calls. It's also possible to disable its usage later for a certain fax document, so setting this will certainly not prevent you from placing internal calls without prefix.
This option is optional. If not given, it defaults to an empty prefix.
Default fax station ID to use when sending a fax document. The station ID is usually the number of your fax station in international format, so an example would be "+49 89 123456" for a number in Munich, Germany. Station IDs may only consist of the "+"-sign, spaces and the digits 0-9. The maximal length is 20. This value can be overwritten in the user sections individually.
This option is mandatory.
Default fax headline to use when sending a fax document. Where and if this headline will be presented depends on the implementation of your CAPI driver. The headline should have a reasonable length to fit on the top of a page, but there's no definite limit given.
This option is optional. If not given, it defaults to an empty headline.
You can set a default originator ("From"-address) for the e-mails CapiSuite sends here.
This option is optional. If you set this to an empty string, the destinator is used as originator (i.e. if "gernot" receives a fax, the mail comes from "gernot" to "gernot").
User specific value for the global option Section , “The [GLOBAL] section” above
User specific value for the global option Section , “The [GLOBAL] section” above
User specific value for the global option Section , “The [GLOBAL] section” above
User specific value for the global option Section , “The [GLOBAL] section” above
User specific value for the global option Section , “The [GLOBAL] section” above
A list containing the numbers on which this user wants to receive incoming fax calls. These numbers are used to differ between users - so the same number must not appear in more than one user section! The numbers are separated with commas and no blanks are allowed. The first number of the list also serves as our own number for sending a fax if outgoing_MSN is not set (see outgoing_MSN).
If you want to use the same number for receiving fax and voice calls, please do not enter it here. Use the voice_numbers option instead (see Section , “The user sections”) - the answering machine has a built in fax detection and can also receive faxes.
When this list is set to *, all incoming calls will be accepted for this user (use with care!). This is only useful for a setup with only one user which wants to receive any call as fax.
If for any reason no destination number is signalled for special MSNs (austrian telecom seems to do this for the main MSN, where it is called "Global Call"), you can use the special sign - which means "no destination number available".
This option is optional. If not given, the user can't receive fax documents.
If given, this string indicates email-addresses where the received faxes will be sent to. More addresses are separated by commas. If it is empty, they will be sent to the user account on the system CapiSuite is running on. The address is also used to send status reports for sent fax jobs to. If you don't want emails to be sent at all, use the action option (see option fax_action) below.
This option is optional. If not given, the mail is sent to the system account.
Here you can define what action will be taken when a call is received. Currently, two possible actions are supported:
The received call will be mailed to the given address (see fax_email above) and saved to the fax_user_dir (see Section , “The [GLOBAL] section”)
The call will be only saved to the fax_user_dir (see Section , “The [GLOBAL] section”)
This option is mandatory.
This file holds all available config options for the answering machine.
It's read from /etc/capisuite/answering_machine.conf or /usr/local/etc/capisuite/answering_machine.conf (depending on the installation).
The answering machine script uses several wave files, for example a global announcement if the user hasn't set his own and some spoken word fragments for the remote inquiry and the menu presented there. These audio files are searched in this directory. If user_audio_files is enabled (see user_audio_files), each user can also provide his own audio snippets in his user_dir (see voice_user_dir).
This option is mandatory.
This directory is used to save user specific data to. It must exist and the user CapiSuite runs as must have write permission to it. It will contain one subdirectory for each configured user (named like his userid). The following subdirectories are used below the user-specific dir:
Here the user may provide his own audio_files (see also option user_audio_files below). The user defined announcement is also saved here.
Received voice calls are saved here.
This option is mandatory.
If set to 1, each user may provide his own audio files in his user directory (see voice_user_dir). If set to 0, only the audio_dir (see voice_audio_dir) will be searched.
This option is optional. If not set, it defaults to not reading own user audio files (0).
Sets the default value for the delay for accepting an incoming call in (in seconds). A value of 10 means that the answering machine accepts incoming calls 10 seconds after the incoming connection request. This value can be overwritten in the user sections individually.
This option is mandatory.
Sets the default name to use for user announcements. The announcements are searched in user_dir/username/announcement then. If not found, a global announcement containing the called MSN will be played. This value can be overwritten in the user sections individually.
This option is optional. If not set, it defaults to "announcement.la".
Default setting for the maximum record length in seconds. This value can be overwritten in the user sections individually.
This option is optional. If not set, it defaults to 60 seconds.
Default setting for the record silence timeout in seconds. When set to a value greater than 0, the recording will be aborted if silence is detected for the given amount of seconds. Set this to 0 to disable it. This value can be overwritten in the user sections individually.
This option is optional. If not set, it defaults to 5 seconds.
You can set a default originator ("From"-address) for the e-mails CapiSuite sends here.
This option is optional. If you set this to an empty string, the destinator is used as originator (i.e. if "gernot" receives a voice call, the mail comes from "gernot" to "gernot").
User specific value for the global option Section , “The [GLOBAL] section” above
User specific value for the global option Section , “The [GLOBAL] section” above
User specific value for the global option Section , “The [GLOBAL] section” above
User specific value for the global option Section , “The [GLOBAL] section” above
User specific value for the global option Section , “The [GLOBAL] section” above
A list containing the numbers on which this user wants to receive incoming voice calls. These numbers are used to differ between users - so the same number must not appear in more than one user section! The numbers are separated with commas and no blanks are allowed. The answering machine script does also automatic fax detection, so a fax can be sent to this number. When this list is set to *, all incoming calls will be accepted for this user (use with care!). This is only useful for a setup with only one user which wants to receive any call.
If for any reason no destination number is signalled for special MSNs (austrian telecom seems to do this for the main MSN, where it is called "Global Call"), you can use the special sign - which means "no destination number available".
This option is optional. If not set, the user won't receive voice calls.
If given, this string indicates email-addresses where the received faxes and voice calls will be sent to. If it is empty, they will be sent to the user account on the system CapiSuite is running on. More addresses are separated by commas. If you don't want emails to be sent at all, use the action option (see voice_action).
This option is optional. If not set, the calls are mailed to the system account.
The answering machine also supports a remote inquiry function. This function is used by entering a PIN (Personal Identification Number) while the announcement is played. This PIN can be setup here. If you don't want to use the remote inquiry function, just use an empty PIN setting. The PIN doesn't have a maximal length - but perhaps you should not use 200 digits or you perhaps won't be able to remember them (I won't at least). ;-)
This option is optional. If not set, remote inquiry is disabled.
Here you can define what action will be taken when a call is received. Currently, three possible actions are supported:
The received call will be mailed to the given address (see voice_email above) and saved to the voice_user_dir (see Section , “The [GLOBAL] section”)
The call will be only saved to the voice_user_dir (see Section , “The [GLOBAL] section”)
Only the announcement will be played - no recording is done.
This option is mandatory.
As written above, all incoming and outgoing calls will be saved on the local file system to assure nothing gets lost. There's no cleaning up done by CapiSuite, so these files will stay forever on your system if you don't clean them up from time to time.
As it's not very convenient to do this manually, I would advise to automate this process. cron is predestinated for such a task. On most modern GNU/Linux distributions, you can simply place scripts in /etc/cron.daily and they will be called automatically once a day.
An example for a bash script you can use is included in the CapiSuite distribution. Just copy capisuite.cron to /etc/cron.daily/capisuite and assure it has correct permissions (owner root, executable bit set).
Now edit the file cronjob.conf and copy it to your CapiSuite configuration directory (usually /etc/capisuite or /usr/local/etc/capisuite). It tells the cron job how long the files should be stored in the different dirs.
The following options are available:
Files stored in the user receive directories which weren't accessed in the last <value> days are deleted. Set to 0 to disable this automatic deletion.
Files stored in the global done directory which weren't accessed in the last <value> days are deleted. Set to 0 to disable this automatic deletion.
Files stored in the global failed directory which weren't accessed in the last <value> days are deleted. Set to 0 to disable this automatic deletion.