# Admin Guide

## Overview

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.

## Dependencies

### Kamailio Modules

The following modules must be loaded before this module:

- a database module
- sl module
- tm module
- rtpproxy module

### External Libraries or Applications

The rtpproxy applications supported by the rtpproxy module (e.g. http://www.b2bua.org/wiki/RTPproxy).

## Parameters

### `db_url` (str)

The URL to connect to the database for the mohqueue tables.

Default is the same value used by Kamailio.

#### Set `db_url`:

    ...
    modparam ("mohqueue", "db_url", "&defaultdb;")
    ...

### `db_qtable` and `db_ctable` (str)

`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`.

#### Set table names:

    ...
    modparam ("mohqueue", "db_qtable", "mqueues")
    modparam ("mohqueue", "db_ctable", "mcalls")
    ...

### `mohdir` (str)

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.

#### Set default directory for audio files:

    ...
    modparam ("mohqueue", "mohdir", "/var/kamailio/MOH")
    ...

### `moh_maxcalls` (integer)

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.

#### Set maximum calls to 200.

    ...
    modparam ("mohqueue", "moh_maxcalls", 200)
    ...

## Functions

### `mohq_process ()`

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:

- TRUE=successful and call in queue
- FALSE=failed, unrecognized URI or unable to place in queue

#### `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
    ...
    }
    ...

### `mohq_send (queue_name)`

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:

- TRUE=successful and call in queue
- FALSE=failed, unable to place in queue

#### `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!
        ...
      }
    ...

### `mohq_retrieve (queue_name, URI)`

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:

- TRUE=successful, transfer started
- FALSE=failed, parameters are incorrect or there are no calls in queue

#### `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
    ...

### `mohq_count (queue_name, pvar)`

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:

- TRUE=successful, pseudo-variable contains count
- FALSE=failed, parameters are incorrect

#### `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!");
      }
    ...

## Database Schema

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.

### MOHQUEUES Table

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:

- id (integer): unique identifier that is created automatically. Do not attempt to change this value.
- name (25-character string, required): the queue name. Duplicate names are not allowed.
- uri (100-character string, required): the URI of the queue. Duplicates are not allowed. It should not include any parameters or headers (e.g. "sip:user@host;maddr=239.255.255.1" or "sip:user@host?subject=project") although it will match any RURI that contains this URI even if the RURI has parameters or headers. The server name of the URI must uniquely identify the server. If the RURI server name does not uniquely identify the server then it should be rewritten to one the does before calling mohq_send ().
- mohdir (100-character string, optional): path to the directory where the audio files for the queue are stored. This path overrides the one provided by the mohdir parameter. If the directory is not accessible by the module the queue is not activated.
- mohfile (100-character string, required): the base name of the audio file. See the section about audio files for more information about file names. If no files matching this name are found in the directory the queue is not activated.
- debug (integer, required): enables debugging messages for the queue. If non-zero, it will send debugging messages to the log for conditions that involve the queue, whether or not Kamailio has logging enabled for debugging. If zero, it depends on Kamailio's log level.

### MOHQCALLS Table

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:

- id (integer): unique identifier that is created automatically.
- mohq_id (integer, required): the id value of the queue.
- call_status (integer, required): the status of the call. 1=entering; 2=in queue (listening to MOH); 3=leaving
- call_from (100-character string, required): the contents of the `From` header field.
- call_id (100-character string, required): the contents of the `Call-ID` header field.
- call_contact (100-character string, optional): the contents of the `Contact` header field, if it exists.
- call_time (datetime, required): time the call entered the queue. If a retrieve fails this time is not changed.

## Audio Files

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:

- 9: G722/8000
- 0: PCMU/8000
- 8: PCMA/8000
- 18: G729/8000
- 3: GSM/8000
- 4: G723/8000
- 15: G728/8000
- 5: DVI4/8000
- 7: LPC/8000
- 12: QCELP/8000
- 13: CN/8000
- 16: DVI4/11025
- 6: DVI4/16000
- 17: DVI4/22050
- 10: L16/44100
- 11: L16/44100
- 14: MPA/90000

See RTP Audio Video Profile for more information about RTP payload types.

## RPC Commands

### `mohqueue.debug`

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).

#### `rpc.debug` usage:

    ...
    # enable debugging on the test queue
    rpc.debug test 1
    # disable debugging on the main queue
    rpc.debug main 0
    ...

### `mohqueue.drop_call`

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.

#### `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
    ...