5 Copyright © 2013-2017 Robert Boisvert, rdbprog@gmail.com
6 __________________________________________________________________
16 2.2. External Libraries or Applications
21 3.2. db_qtable and db_ctable (str)
23 3.4. moh_maxcalls (integer)
28 4.2. mohq_send (queue_name)
29 4.3. mohq_retrieve (queue_name, URI)
30 4.4. mohq_count (queue_name, pvar)
41 7.2. mohqueue.drop_call
47 1.3. Set default directory for audio files:
48 1.4. Set maximum calls to 200.
49 1.5. mohq_process usage:
51 1.7. mohq_retrieve usage:
52 1.8. mohq_count usage:
54 1.10. rpc.drop_call usage:
56 Chapter 1. Admin Guide
64 2.2. External Libraries or Applications
69 3.2. db_qtable and db_ctable (str)
71 3.4. moh_maxcalls (integer)
76 4.2. mohq_send (queue_name)
77 4.3. mohq_retrieve (queue_name, URI)
78 4.4. mohq_count (queue_name, pvar)
89 7.2. mohqueue.drop_call
93 The mohqueue module diverts INVITE requests into a Music On Hold (MOH)
94 queue where the caller can listen to recorded audio until an operator
95 is available to take the call. When an operator is available, a
96 function can be used to transfer the oldest call in a queue to an
97 operator using an unattended transfer (REFER) to a specified URI. If
98 successful, the call is removed from the queue.
100 While in queue, recorded audio is streamed to the caller in an endless
101 loop using the rtpproxy module and application. Each queue can be
102 configured to use different audio files.
104 The queues are defined in the database which allows for dynamic
105 configuration of the queues. Each queue is assigned a specific URI to
106 respond to and a location for the audio files.
108 As each call arrives the database is updated to show the call status
109 which allows outside processes to inspect the queue. It can also be
110 inspected using a function to see how many calls are currently in
113 While in queue, all SIP messages for a call must pass through the
114 mohqueue module so that it can accurately detect the call status.
118 2.1. Kamailio Modules
119 2.2. External Libraries or Applications
121 2.1. Kamailio Modules
123 The following modules must be loaded before this module:
129 2.2. External Libraries or Applications
131 The rtpproxy applications supported by the rtpproxy module (e.g.
132 http://www.b2bua.org/wiki/RTPproxy).
137 3.2. db_qtable and db_ctable (str)
139 3.4. moh_maxcalls (integer)
143 The URL to connect to the database for the mohqueue tables.
145 Default is the same value used by Kamailio.
147 Example 1.1. Set db_url:
149 modparam ("mohqueue", "db_url", "mysql://kamailio:kamailiorw@localhost/kamailio"
153 3.2. db_qtable and db_ctable (str)
155 db_qtable is the name of the table that defines the queues and
156 db_ctable is the table that maintains the call status.
158 Default is "MOHQUEUES" for db_qtable and "MOHQCALLS" for db_ctable.
160 Example 1.2. Set table names:
162 modparam ("mohqueue", "db_qtable", "mqueues")
163 modparam ("mohqueue", "db_ctable", "mcalls")
168 Path to the directory where the audio files are stored. Audio files are
169 usually relative to this directory although the value can be overridden
170 by a directory specified in the queues table.
172 Default is None. If not set by the module it must be defined in the
175 Example 1.3. Set default directory for audio files:
177 modparam ("mohqueue", "mohdir", "/var/kamailio/MOH")
180 3.4. moh_maxcalls (integer)
182 Defines the maximum number of calls that can be placed in queue. It is
183 the sum of all calls in all queues. It must be in the range of 1 to
184 5000. NOTE: it may be limited by the processing power of the server or
185 the number of available rtpproxy ports.
189 Example 1.4. Set maximum calls to 200.
191 modparam ("mohqueue", "moh_maxcalls", 200)
197 4.2. mohq_send (queue_name)
198 4.3. mohq_retrieve (queue_name, URI)
199 4.4. mohq_count (queue_name, pvar)
203 Checks to see if the current SIP message involves a queue. If it does
204 it will process the message and return a TRUE value.
206 In order for mohqueue to detect changes in the call it is necessary
207 that all messages involving the call be processed through this
208 function. The easiest way is to accomplish this is to place it at the
209 beginning of the main route of the script.
211 mohqueue calls are identified by an RURI that matches a queue URI. Once
212 a call is placed in queue it checks the To header field along with the
213 RURI to find a match, except in the case of a CANCEL which matches only
216 This function has no parameters and must be called from a request
220 * TRUE=successful and call in queue
221 * FALSE=failed, unrecognized URI or unable to place in queue
223 Example 1.5. mohq_process usage:
226 # main route with limited processing
229 if (mohq_process ()) {
230 xlog ("L_DBG", "Handled by mohqueue");
233 # An error or not a MOH queue message; continue processing
238 4.2. mohq_send (queue_name)
240 Normally calls enter the queue with an initial INVITE message that 1)
241 has a RURI that matches a queue URI and 2) is passed through
242 mohq_process (), which is the preferred method.
244 This function is used when you wish to send a call into a queue that
245 does not match the queue URI.
247 It has only one parameter, the name of the queue, and must be called
248 from the request route with an initial INVITE message. The queue name
249 can be passed as a literal or pseudo-variable.
252 * TRUE=successful and call in queue
253 * FALSE=failed, unable to place in queue
255 Example 1.6. mohq_send usage:
257 # call is initial INVITE and ready for queue?
259 if (mohq_send ("main")) {
260 xlog ("L_DBG", "Sent call to main mohqueue");
263 # failed to enter queue!
268 4.3. mohq_retrieve (queue_name, URI)
270 Retrieves the oldest call in a queue and redirects it to a URI.
271 Although the function returns, the transfer of the call may not have
272 completed since the new URI (operator) must answer the call.
274 It has two parameters, the queue name and the URI to REFER the call to,
275 both which can be passed as literals or pseudo-variables. It can be
276 called from any route.
279 * TRUE=successful, transfer started
280 * FALSE=failed, parameters are incorrect or there are no calls in
283 Example 1.7. mohq_retrieve usage:
285 #!define MOHQNAME "operators"
286 #!define CGROUP "sip:operators@10.211.64.5"
288 # redirect oldest call to operator call group
289 if (mohq_retrieve (MOHQNAME, CGROUP)) {
290 xlog ("L_DBG", "Retrieved call from mohqueue");
293 # queue is empty or something went wrong
296 4.4. mohq_count (queue_name, pvar)
298 Finds the number of calls that are in a queue. It will not count calls
299 that are in the process of entering or exiting the queue.
301 The function has two parameters, the name of the queue and the
302 pseudo-variable which receives the count. The queue name can be passed
303 as a literal or a pseudo-variable. It can be called from any route.
306 * TRUE=successful, pseudo-variable contains count
307 * FALSE=failed, parameters are incorrect
309 Example 1.8. mohq_count usage:
311 $var(mohq) = "operators";
313 # more than 10 calls?
314 mohq_count ("$var(mohq)", "$var(mohqcnt)");
315 if ($var(mohqcnt) > 10) {
316 xlog ("L_WARN", "$var(mohq) queue has $var(mohqcnt) calls!");
325 mohqueue uses two external database tables to manage the queues and
326 provide status information to outside processes. Internally, it keeps a
327 volatile database in memory of call status. If the module is restarted
328 it loses the internal database and clears the external one.
330 On a reqular basis it checks the external table that defines the queues
331 to see if the definition has changed. It makes this check under the
332 following conditions: the queue has not been checked in the last 60
333 seconds AND no call is currently in queue or transitioning in or out.
334 The last condition prevents existing calls from being adversely
335 affected by queue redefinitions.
339 This table controls the definition of the queue. The name is set by the
340 db_qtable parameter. There is no internal function to modify the table
341 so it must be configured externally. It contains the following fields:
342 * id (integer): unique identifier that is created automatically. Do
343 not attempt to change this value.
344 * name (25-character string, required): the queue name. Duplicate
345 names are not allowed.
346 * uri (100-character string, required): the URI of the queue. It
347 should not include any parameters or headers (e.g.
348 "sip:user@host;maddr=239.255.255.1" or
349 "sip:user@host?subject=project") although it will match any RURI
350 that contains this URI even if the RURI has parameters or headers.
351 Duplicates are not allowed.
352 * mohdir (100-character string, optional): path to the directory
353 where the audio files for the queue are stored. This path overrides
354 the one provided by the mohdir parameter. If the directory is not
355 accessible by the module the queue is not activated.
356 * mohfile (100-character string, required): the base name of the
357 audio file. See the section about audio files for more information
358 about file names. If no files matching this name are found in the
359 directory the queue is not activated.
360 * debug (integer, required): enables debugging messages for the
361 queue. If non-zero, it will send debugging messages to the log for
362 conditions that involve the queue, whether or not Kamailio has
363 logging enabled for debugging. If zero, it depends on Kamailio's
368 This table contains the status of calls that are in queue, or
369 transitioning in or out of a queue. The name is set by the db_ctable
370 parameter. This table is read-only for external processes and its
371 contents should not be modified. It contains the following fields:
372 * id (integer): unique identifier that is created automatically.
373 * mohq_id (integer, required): the id value of the queue.
374 * call_status (integer, required): the status of the call.
375 1=entering; 2=in queue (listening to MOH); 3=leaving
376 * call_from (100-character string, required): the contents of the
378 * call_id (100-character string, required): the contents of the
379 Call-ID header field.
380 * call_contact (100-character string, optional): the contents of the
381 Contact header field, if it exists.
382 * call_time (datetime, required): time the call entered the queue. If
383 a retrieve fails this time is not changed.
387 When rtpproxy negotiates to determine which media to use in the audio
388 stream it uses the files in the MOH directory as defined by the
389 MOHQUEUES table. The table defines the location of the files and the
390 base name used to identify each. The actual stream type depends on the
391 RTP payload number that is part of the name. The complete file name for
392 each stream is composed of mohdir/mohfile.type. For example,
393 /var/kamailio/MOH/HeWillCall.8 would be the file for payload type 8
396 The supported types and their order of preference are:
415 See RTP Audio Video Profile for more information about RTP payload
421 7.2. mohqueue.drop_call
425 Turns debugging on or off for a queue. The first paramater is the queue
426 name and the second is a number indicating whether debugging should be
427 turned off or on (0=off, <>0=on).
429 Example 1.9. rpc.debug usage:
431 # enable debugging on the test queue
433 # disable debugging on the main queue
437 7.2. mohqueue.drop_call
439 Drops a call from a queue. The first paramater is the queue name and
440 the second is the call ID. Using a call ID of "*" (asterisk) drops all
441 calls from the queue.
443 Example 1.10. rpc.drop_call usage:
445 # drop all calls from the test queue
447 # drop a call from the main queue
448 rpc.drop_call main 3807f84e-f1a860fd-db1d09d4@192.168.137.82