b5a70317dd81cf6d0007b1c0f857ef1aebe1ac72
[sip-router] / src / modules / mohqueue / README
1 mohqueue Module
2
3 Robert Boisvert
4
5    Copyright © 2013 Robert Boisvert, rdbprog@gmail.com
6      __________________________________________________________________
7
8    Table of Contents
9
10    1. Admin Guide
11
12         1. Overview
13         2. Dependencies
14
15               2.1. Kamailio Modules
16               2.2. External Libraries or Applications
17
18         3. Parameters
19
20               3.1. db_url (str)
21               3.2. db_qtable and db_ctable (str)
22               3.3. mohdir (str)
23               3.4. moh_maxcalls (integer)
24
25         4. Functions
26
27               4.1. mohq_process ()
28               4.2. mohq_send (queue_name)
29               4.3. mohq_retrieve (queue_name, URI)
30               4.4. mohq_count (queue_name, pvar)
31
32         5. Database Schema
33
34               5.1. MOHQUEUES Table
35               5.2. MOHQCALLS Table
36
37         6. Audio Files
38         7. RPC Commands
39
40               7.1. mohqueue.debug
41               7.2. mohqueue.drop_call
42
43    List of Examples
44
45    1.1. Set db_url:
46    1.2. Set table names:
47    1.3. Set default directory for audio files:
48    1.4. Set maximum calls to 200.
49    1.5. mohq_process usage:
50    1.6. mohq_send usage:
51    1.7. mohq_retrieve usage:
52    1.8. mohq_count usage:
53    1.9. rpc.debug usage:
54    1.10. rpc.drop_call usage:
55
56 Chapter 1. Admin Guide
57
58    Table of Contents
59
60    1. Overview
61    2. Dependencies
62
63         2.1. Kamailio Modules
64         2.2. External Libraries or Applications
65
66    3. Parameters
67
68         3.1. db_url (str)
69         3.2. db_qtable and db_ctable (str)
70         3.3. mohdir (str)
71         3.4. moh_maxcalls (integer)
72
73    4. Functions
74
75         4.1. mohq_process ()
76         4.2. mohq_send (queue_name)
77         4.3. mohq_retrieve (queue_name, URI)
78         4.4. mohq_count (queue_name, pvar)
79
80    5. Database Schema
81
82         5.1. MOHQUEUES Table
83         5.2. MOHQCALLS Table
84
85    6. Audio Files
86    7. RPC Commands
87
88         7.1. mohqueue.debug
89         7.2. mohqueue.drop_call
90
91 1. Overview
92
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.
99
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.
103
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.
107
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
111    queue.
112
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.
115
116 2. Dependencies
117
118    2.1. Kamailio Modules
119    2.2. External Libraries or Applications
120
121 2.1. Kamailio Modules
122
123    The following modules must be loaded before this module:
124      * a database module
125      * sl module
126      * tm module
127      * rtpproxy module
128
129 2.2. External Libraries or Applications
130
131    The rtpproxy applications supported by the rtpproxy module (e.g.
132    http://www.b2bua.org/wiki/RTPproxy).
133
134 3. Parameters
135
136    3.1. db_url (str)
137    3.2. db_qtable and db_ctable (str)
138    3.3. mohdir (str)
139    3.4. moh_maxcalls (integer)
140
141 3.1. db_url (str)
142
143    The URL to connect to the database for the mohqueue tables.
144
145    Default is the same value used by Kamailio.
146
147    Example 1.1. Set db_url:
148 ...
149 modparam ("mohqueue", "db_url", "mysql://kamailio:kamailiorw@localhost/kamailio"
150 )
151 ...
152
153 3.2. db_qtable and db_ctable (str)
154
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.
157
158    Default is "MOHQUEUES" for db_qtable and "MOHQCALLS" for db_ctable.
159
160    Example 1.2. Set table names:
161 ...
162 modparam ("mohqueue", "db_qtable", "mqueues")
163 modparam ("mohqueue", "db_ctable", "mcalls")
164 ...
165
166 3.3. mohdir (str)
167
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.
171
172    Default is None. If not set by the module it must be defined in the
173    queues table.
174
175    Example 1.3. Set default directory for audio files:
176 ...
177 modparam ("mohqueue", "mohdir", "/var/kamailio/MOH")
178 ...
179
180 3.4. moh_maxcalls (integer)
181
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.
186
187    Default value is 50.
188
189    Example 1.4. Set maximum calls to 200.
190 ...
191 modparam ("mohqueue", "moh_maxcalls", 200)
192 ...
193
194 4. Functions
195
196    4.1. mohq_process ()
197    4.2. mohq_send (queue_name)
198    4.3. mohq_retrieve (queue_name, URI)
199    4.4. mohq_count (queue_name, pvar)
200
201 4.1.  mohq_process ()
202
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.
205
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.
210
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
214    on the RURI.
215
216    This function has no parameters and must be called from a request
217    route.
218
219    Return code:
220      * TRUE=successful and call in queue
221      * FALSE=failed, unrecognized URI or unable to place in queue
222
223    Example 1.5. mohq_process usage:
224 ...
225 request_route {
226   # main route with limited processing
227 ...
228   # MOH queue?
229   if (mohq_process ()) {
230     xlog ("L_DBG", "Handled by mohqueue");
231     exit;
232   }
233   # An error or not a MOH queue message; continue processing
234 ...
235 }
236 ...
237
238 4.2.  mohq_send (queue_name)
239
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.
243
244    This function is used when you wish to send a call into a queue that
245    does not match the queue URI.
246
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.
250
251    Return code:
252      * TRUE=successful and call in queue
253      * FALSE=failed, unable to place in queue
254
255    Example 1.6. mohq_send usage:
256 ...
257   # call is initial INVITE and ready for queue?
258   if (some test) {
259     if (mohq_send ("main")) {
260       xlog ("L_DBG", "Sent call to main mohqueue");
261       exit;
262     }
263     # failed to enter queue!
264     ...
265   }
266 ...
267
268 4.3.  mohq_retrieve (queue_name, URI)
269
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.
273
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.
277
278    Return code:
279      * TRUE=successful, transfer started
280      * FALSE=failed, parameters are incorrect or there are no calls in
281        queue
282
283    Example 1.7. mohq_retrieve usage:
284 ...
285 #!define MOHQNAME "operators"
286 #!define CGROUP   "sip:operators@10.211.64.5"
287 ...
288   # redirect oldest call to operator call group
289   if (mohq_retrieve (MOHQNAME, CGROUP)) {
290       xlog ("L_DBG", "Retrieved call from mohqueue");
291       exit;
292   }
293   # queue is empty or something went wrong
294 ...
295
296 4.4.  mohq_count (queue_name, pvar)
297
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.
300
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.
304
305    Return code:
306      * TRUE=successful, pseudo-variable contains count
307      * FALSE=failed, parameters are incorrect
308
309    Example 1.8. mohq_count usage:
310 ...
311 $var(mohq) = "operators";
312 ...
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!");
317   }
318 ...
319
320 5. Database Schema
321
322    5.1. MOHQUEUES Table
323    5.2. MOHQCALLS Table
324
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.
329
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.
336
337 5.1. MOHQUEUES Table
338
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
364        log level.
365
366 5.2. MOHQCALLS Table
367
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
377        From header field.
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.
384
385 6. Audio Files
386
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
394    (PCMA/8000).
395
396    The supported types and their order of preference are:
397      * 9: G722/8000
398      * 0: PCMU/8000
399      * 8: PCMA/8000
400      * 18: G729/8000
401      * 3: GSM/8000
402      * 4: G723/8000
403      * 15: G728/8000
404      * 5: DVI4/8000
405      * 7: LPC/8000
406      * 12: QCELP/8000
407      * 13: CN/8000
408      * 16: DVI4/11025
409      * 6: DVI4/16000
410      * 17: DVI4/22050
411      * 10: L16/44100
412      * 11: L16/44100
413      * 14: MPA/90000
414
415    See RTP Audio Video Profile for more information about RTP payload
416    types.
417
418 7. RPC Commands
419
420    7.1. mohqueue.debug
421    7.2. mohqueue.drop_call
422
423 7.1.  mohqueue.debug
424
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).
428
429    Example 1.9. rpc.debug usage:
430 ...
431 # enable debugging on the test queue
432 rpc.debug test 1
433 # disable debugging on the main queue
434 rpc.debug main 0
435 ...
436
437 7.2.  mohqueue.drop_call
438
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.
442
443    Example 1.10. rpc.drop_call usage:
444 ...
445 # drop all calls from the test queue
446 rpc.drop_call test *
447 # drop a call from the main queue
448 rpc.drop_call main 3807f84e-f1a860fd-db1d09d4@192.168.137.82
449 ...