Table of Contents
List of Examples
db_url:mohq_process usage:mohq_send usage:mohq_retrieve usage:mohq_count usage:rpc.debug usage:rpc.drop_call usage:Table of Contents
The mohqueue module diverts INVITE requests into a Music On Hold (MOH) queue where the caller can listen to recorded audio until an operator is available to take the call. When an operator is available, a function can be used to transfer the oldest call in a queue to an operator using an unattended transfer (REFER) to a specified URI. If successful, the call is removed from the queue.
While in queue, recorded audio is streamed to the caller in an endless loop using the rtpproxy module and application. Each queue can be configured to use different audio files.
The queues are defined in the database which allows for dynamic configuration of the queues. Each queue is assigned a specific URI to respond to and a location for the audio files.
As each call arrives the database is updated to show the call status which allows outside processes to inspect the queue. It can also be inspected using a function to see how many calls are currently in queue.
While in queue, all SIP messages for a call must pass through the mohqueue module so that it can accurately detect the call status.
The following modules must be loaded before this module:
The rtpproxy applications supported by the rtpproxy module (e.g. http://www.b2bua.org/wiki/RTPproxy).
The URL to connect to the database for the mohqueue tables.
Default is the same value used by Kamailio.
Example 1.1. Set db_url:
...
modparam ("mohqueue", "db_url", "mysql://kamailio:kamailiorw@localhost/kamailio")
...
db_qtable is the name of the table that defines
the queues and db_ctable is the table that
maintains the call status.
Default is "MOHQUEUES" for db_qtable and
"MOHQCALLS" for db_ctable.
Example 1.2. Set table names:
...
modparam ("mohqueue", "db_qtable", "mqueues")
modparam ("mohqueue", "db_ctable", "mcalls")
...
Path to the directory where the audio files are stored. Audio files are usually relative to this directory although the value can be overridden by a directory specified in the queues table.
Default is None. If not set by the module it must be defined in the queues table.
Example 1.3. Set default directory for audio files:
...
modparam ("mohqueue", "mohdir", "/var/kamailio/MOH")
...
Defines the maximum number of calls that can be placed in queue. It is the sum of all calls in all queues. It must be in the range of 1 to 5000. NOTE: it may be limited by the processing power of the server or the number of available rtpproxy ports.
Default value is 50.
Checks to see if the current SIP message involves a queue. If it does it will process the message and return a TRUE value.
In order for mohqueue to detect changes in the call it is necessary that all messages involving the call be processed through this function. The easiest way is to accomplish this is to place it at the beginning of the main route of the script.
mohqueue calls are identified by an RURI that matches a queue URI.
Once a call is placed in queue it checks the To
header field along with the RURI to find a match, except in the case
of a CANCEL which matches only on the RURI.
This function has no parameters and must be called from a request route.
Return code:
Example 1.5. mohq_process usage:
...
request_route {
# main route with limited processing
...
# MOH queue?
if (mohq_process ()) {
xlog ("L_DBG", "Handled by mohqueue");
exit;
}
# An error or not a MOH queue message; continue processing
...
}
...
Normally calls enter the queue with an initial INVITE message that
1) has a RURI that matches a queue URI and 2) is passed through
mohq_process (), which is the preferred method.
This function is used when you wish to send a call into a queue that does not match the queue URI.
It has only one parameter, the name of the queue, and must be called from the request route with an initial INVITE message. The queue name can be passed as a literal or pseudo-variable.
Return code:
Example 1.6. mohq_send usage:
...
# call is initial INVITE and ready for queue?
if (some test) {
if (mohq_send ("main")) {
xlog ("L_DBG", "Sent call to main mohqueue");
exit;
}
# failed to enter queue!
...
}
...
Retrieves the oldest call in a queue and redirects it to a URI. Although the function returns, the transfer of the call may not have completed since the new URI (operator) must answer the call.
It has two parameters, the queue name and the URI to REFER the call to, both which can be passed as literals or pseudo-variables. It can be called from any route.
Return code:
Example 1.7. mohq_retrieve usage:
...
#!define MOHQNAME "operators"
#!define CGROUP "sip:operators@10.211.64.5"
...
# redirect oldest call to operator call group
if (mohq_retrieve (MOHQNAME, CGROUP)) {
xlog ("L_DBG", "Retrieved call from mohqueue");
exit;
}
# queue is empty or something went wrong
...
Finds the number of calls that are in a queue. It will not count calls that are in the process of entering or exiting the queue.
The function has two parameters, the name of the queue and the pseudo-variable which receives the count. The queue name can be passed as a literal or a pseudo-variable. It can be called from any route.
Return code:
Example 1.8. mohq_count usage:
...
$var(mohq) = "operators";
...
# more than 10 calls?
mohq_count ("$var(mohq)", "$var(mohqcnt)");
if ($var(mohqcnt) > 10) {
xlog ("L_WARN", "$var(mohq) queue has $var(mohqcnt) calls!");
}
...
mohqueue uses two external database tables to manage the queues and provide status information to outside processes. Internally, it keeps a volatile database in memory of call status. If the module is restarted it loses the internal database and clears the external one.
On a regular basis it checks the external table that defines the queues to see if the definition has changed. It makes this check under the following conditions: the queue has not been checked in the last 60 seconds AND no call is currently in queue or transitioning in or out. The last condition prevents existing calls from being adversely affected by queue redefinitions.
This table controls the definition of the queue. The name is set by the db_qtable parameter. There is no internal function to modify the table so it must be configured externally. It contains the following fields:
This table contains the status of calls that are in queue, or transitioning in or out of a queue. The name is set by the db_ctable parameter. This table is read-only for external processes and its contents should not be modified. It contains the following fields:
From header field.
Call-ID header field.
Contact header field, if it
exists.
When rtpproxy negotiates to determine which media to use in the audio
stream it uses the files in the MOH directory as defined by the
MOHQUEUES table. The table
defines the location of the files and the base name used to identify
each. The actual stream type depends on the RTP payload number that
is part of the name. The complete file name for each stream is
composed of mohdir/mohfile.type. For example,
/var/kamailio/MOH/HeWillCall.8 would be the file
for payload type 8 (PCMA/8000).
The supported types and their order of preference are:
See RTP Audio Video Profile for more information about RTP payload types.
Turns debugging on or off for a queue. The first parameter is the queue name and the second is a number indicating whether debugging should be turned off or on (0=off, <>0=on).
Example 1.9. rpc.debug usage:
... # enable debugging on the test queue rpc.debug test 1 # disable debugging on the main queue rpc.debug main 0 ...
Drops a call from a queue. The first parameter is the queue name and the second is the call ID. Using a call ID of "*" (asterisk) drops all calls from the queue.
Example 1.10. rpc.drop_call usage:
... # drop all calls from the test queue rpc.drop_call test * # drop a call from the main queue rpc.drop_call main 3807f84e-f1a860fd-db1d09d4@192.168.137.82 ...