More spelling fixes (issue 7930)
[asterisk/asterisk.git] / doc / queues-with-callback-members.txt
1
2 Setting up Call Queues -- A Tutorial
3
4 Pardon, but the dialplan in this tutorial will be expressed
5 in AEL, the new Asterisk Extension Language. If you are 
6 not used to its syntax, we hope you will find it to some
7 degree intuitive. If not, there are documents explaining
8 its syntax and constructs.
9
10
11 ======  Configuring Call Queues
12
13 First of all, set up call queues in queue.conf
14
15 Here is an example:
16
17    =========== queues.conf ===========
18    | ; Cool Digium Queues            |
19    | [general]                       |
20    | persistentmembers = yes         |
21    |                                 |
22    | ; General sales queue           |
23    | [sales-general]                 |
24    | music=default                   |
25    | context=sales                   |
26    | strategy=ringall                |
27    | joinempty=strict                |
28    | leavewhenempty=strict           |
29    |                                 |
30    | ; Customer service queue        |
31    | [customerservice]               |
32    | music=default                   |
33    | context=customerservice         |
34    | strategy=ringall                |
35    | joinempty=strict                |
36    | leavewhenempty=strict           |
37    |                                 |
38    | ; Support dispatch queue        |
39    | [support-dispatch]              |
40    | music=default                   |
41    | context=dispatch                |
42    | strategy=ringall                |
43    | joinempty=strict                |
44    | leavewhenempty=strict           |
45    ===================================
46
47 In the above, we have defined 3 separate calling queues: 
48 sales-general, customerservice, and support-dispatch.
49
50 Please note that the sales-general queue specifies a
51 context of "sales", and that customerservice specifies the
52 context of "customerservice", and the support-dispatch
53 queue specifies the context "dispatch". These three
54 contexts must be defined somewhere in your dialplan.
55 We will show them after the main menu below.
56
57 <verbage explaining options above>
58 In the [general] section, specifying the persistentmembers=yes,
59 will cause the agent lists to be stored in astdb, and 
60 recalled on startup.
61
62 The strategy=ringall will cause all agents to be dialed
63 together, the first to answer is then assigned the incoming
64 call. 
65
66 "joinempty" set to "strict" will keep incoming callers from
67 being placed in queues where there are no agents to take calls.
68 The Queue() application will return, and the dial plan can 
69 determine what to do next.
70
71 If there are calls queued, and the last agent logs out, the
72 remaining incoming callers will immediately be removed from
73 the queue, and the Queue() call will return, IF the "leavewhenempty" is
74 set to "strict".
75
76
77 =====================================
78 |  Routing incoming Calls to Queues |
79 =====================================
80
81
82 Then in extensions.ael, you can do these things:
83
84 ================ The Main Menu 
85
86 At Digium, incoming callers are sent to the "mainmenu" context, where they
87 are greeted, and directed to the numbers they choose...
88
89 context mainmenu {
90
91         includes {
92                 digium;
93                 queues-loginout;
94         }
95
96         0 => goto dispatch|s|1;
97         2 => goto sales|s|1;
98         3 => goto customerservice|s|1;
99         4 => goto dispatch|s|1;
100
101         s => {
102                 Ringing();
103                 Wait(1);
104                 Set(attempts=0);
105                 Answer();
106                 Wait(1);
107                 Background(digium/ThankYouForCallingDigium);
108                 Background(digium/YourOpenSourceTelecommunicationsSupplier);
109                 WaitExten(0.3);
110         repeat:
111                 Set(attempts=$[${attempts} + 1]);
112                 Background(digium/IfYouKnowYourPartysExtensionYouMayDialItAtAnyTime);
113                 WaitExten(0.1);
114                 Background(digium/Otherwise);
115                 WaitExten(0.1);
116                 Background(digium/ForSalesPleasePress2);
117                 WaitExten(0.2);
118                 Background(digium/ForCustomerServicePleasePress3);
119                 WaitExten(0.2);
120                 Background(digium/ForAllOtherDepartmentsPleasePress4);
121                 WaitExten(0.2);
122                 Background(digium/ToSpeakWithAnOperatorPleasePress0AtAnyTime);
123                 if( ${attempts} < 2 ) {
124                         WaitExten(0.3);
125                         Background(digium/ToHearTheseOptionsRepeatedPleaseHold);
126                 }
127                 WaitExten(5);
128                 if( ${attempts} < 2 ) goto repeat;
129                 Background(digium/YouHaveMadeNoSelection);
130                 Background(digium/ThisCallWillBeEnded);
131                 Background(goodbye);
132                 Hangup();
133         }
134 }
135
136
137 ============= The Contexts referenced from the queues.conf file
138
139
140
141 context sales {
142
143         0 => goto dispatch|s|1;
144         8 => Voicemail(${SALESVM});
145
146         s => {
147                 Ringing();
148                 Wait(2);
149                 Background(digium/ThankYouForContactingTheDigiumSalesDepartment);
150                 WaitExten(0.3);
151                 Background(digium/PleaseHoldAndYourCallWillBeAnsweredByOurNextAvailableSalesRepresentative);
152                 WaitExten(0.3);
153                 Background(digium/AtAnyTimeYouMayPress0ToSpeakWithAnOperatorOr8ToLeaveAMessage);
154                 Set(CALLERID(name)=Sales);
155                 Queue(sales-general|t);
156                 Set(CALLERID(name)=EmptySalQ);
157                 goto dispatch|s|1;
158                 Playback(goodbye);
159                 Hangup();
160         }
161 }
162
163 Please note that there is only one attempt to queue a call in the sales queue. All sales agents that
164 are logged in will be rung.
165
166
167 context customerservice {
168
169         0 => {
170                 SetCIDName(CSVTrans);
171                 goto dispatch|s|1;
172         }
173         8 => Voicemail(${CUSTSERVVM});
174
175         s => {
176                 Ringing();
177                 Wait(2);
178                 Background(digium/ThankYouForCallingDigiumCustomerService);
179                 WaitExten(0.3);
180         notracking:
181                 Background(digium/PleaseWaitForTheNextAvailableCustomerServiceRepresentative);
182                 WaitExten(0.3);
183                 Background(digium/AtAnyTimeYouMayPress0ToSpeakWithAnOperatorOr8ToLeaveAMessage);
184                 Set(CALLERID(name)=Cust Svc);
185                 Set(QUEUE_MAX_PENALTY=10);
186                 Queue(customerservice|t);
187                 Set(QUEUE_MAX_PENALTY=0);
188                 Queue(customerservice|t);
189                 Set(CALLERID(name)=EmptyCSVQ);
190                 goto dispatch|s|1;
191                 Background(digium/NoCustomerServiceRepresentativesAreAvailableAtThisTime);
192                 Background(digium/PleaseLeaveAMessageInTheCustomerServiceVoiceMailBox);
193                 Voicemail(${CUSTSERVVM});
194                 Playback(goodbye);
195                 Hangup();
196         }
197 }
198
199 Note that calls coming into customerservice will first be try to queue
200 calls to those agents with a QUEUE_MAX_PENALTY of 10, and if none are available,
201 then all agents are rung.
202
203
204 context dispatch
205 {
206
207         s => {
208                 Ringing();
209                 Wait(2);
210                 Background(digium/ThankYouForCallingDigium);
211                 WaitExten(0.3);
212                 Background(digium/YourCallWillBeAnsweredByOurNextAvailableOperator);
213                 Background(digium/PleaseHold);
214                 Set(QUEUE_MAX_PENALTY=10);
215                 Queue(dispatch|t);
216                 Set(QUEUE_MAX_PENALTY=20);
217                 Queue(dispatch|t);
218                 Set(QUEUE_MAX_PENALTY=0);
219                 Queue(dispatch|t);
220                 Background(digium/NoOneIsAvailableToTakeYourCall);
221                 Background(digium/PleaseLeaveAMessageInOurGeneralVoiceMailBox);
222                 Voicemail(${DISPATCHVM});
223                 Playback(goodbye);
224                 Hangup();
225         }
226 }
227
228 And in the dispatch context, first agents of priority 10 are tried, then
229 20, and if none are available, all agents are tried. 
230
231 Notice that a common pattern is followed in each of the three queue contexts:
232
233 First, you set QUEUE_MAX_PENALTY to a value, then you call
234 Queue(<queue-name>,option,... (see the documentation for the Queue application));
235
236 In the above, note that the "t" option is specified, and this allows the 
237 agent picking up the incoming call the luxury of transferring the call to 
238 other parties.
239
240 The purpose of specifying the QUEUE_MAX_PENALTY is to develop a set of priorities
241 amongst agents. By the above usage, agents with lower number priorities will 
242 be given the calls first, and then, if no-one picks up the call, the QUEUE_MAX_PENALTY
243 will be incremented, and the queue tried again. Hopefully, along the line, someone
244 will pick up the call, and the Queue application will end with a hangup.
245
246 The final attempt to queue in most of our examples sets the QUEUE_MAX_PENALTY
247 to zero, which means to try all available agents.
248
249
250 =========================================
251 |      Assigning agents to Queues       |
252 =========================================
253
254 In this example dialplan, we want to be able to add and remove agents to 
255 handle incoming calls, as they feel they are available. As they log in,
256 they are added to the queue's agent list, and as they log out, they are
257 removed. If no agents are available, the queue command will terminate, and
258 it is the duty of the dialplan to do something appropriate, be it sending
259 the incoming caller to voicemail, or trying the queue again with a higher 
260 QUEUE_MAX_PENALTY.
261
262 Because a single agent can make themselves available to more than one queue,
263 the process of joining multiple queues can be handled automatically by the
264 dialplan.
265
266
267 ================= Agents Log In and Out 
268
269
270 context queues-loginout
271 {
272         6092 => {
273                         Answer();
274                         Read(AGENT_NUMBER,agent-enternum);
275                         VMAuthenticate(${AGENT_NUMBER}@default,s);
276                         Set(queue-announce-success=1);
277                         goto queues-manip,I${AGENT_NUMBER},1;
278                 }
279
280         6093 => {
281                         Answer();
282                         Read(AGENT_NUMBER,agent-enternum);
283                         Set(queue-announce-success=1);
284                         goto queues-manip,O${AGENT_NUMBER},1;
285                 }
286 }
287
288
289 In the above contexts, the agents dial 6092 to log into their queues,
290 and they dial 6093 to log out of their queues. The agent is prompted
291 for their agent number, and if they are logging in, their passcode, 
292 and then they are transferred to the proper extension in the 
293 queues-manip context.  The queues-manip context does all the 
294 actual work:
295
296
297 context queues-manip {
298
299         // Raquel Squelch
300         _[IO]6121 => {
301                 &queue-addremove(dispatch,10);
302                 &queue-success();
303         }
304
305         // Brittanica Spears
306         _[IO]6165 => {
307                 &queue-addremove(dispatch,20);
308                 &queue-success();
309         }
310
311         // Rock Hudson
312         _[IO]6170 => {
313                 &queue-addremove(sales-general,10);
314                 &queue-addremove(customerservice,20);
315                 &queue-addremove(dispatch,30);
316                 &queue-success();
317         }
318
319         // Saline Dye-on
320         _[IO]6070 => {
321                 &queue-addremove(sales-general,20);
322                 &queue-addremove(customerservice,30);
323                 &queue-addremove(dispatch,30);
324                 &queue-success();
325         }
326 }
327
328 In the above extensions, note that the queue-addremove macro is used
329 to actually add or remove the agent from the applicable queue,
330 with the applicable priority level. Note that agents with a 
331 priority level of 10 will be called before agents with levels
332 of 20 or 30.
333
334 In the above example, Raquel will be dialed first in the dispatch
335 queue, if she has logged in. If she is not, then the second call of
336 Queue() with priority of 20 will dial Brittanica if she is present,
337 otherwise the third call of Queue() with MAX_PENALTY of 0 will 
338 dial Rock and Saline simultaneously.
339
340 Also note that Rock will be among the first to be called in the sales-general 
341 queue, and among the last in the dispatch queue. As you can see in
342 main menu, the callerID is set in the main menu so they can tell 
343 which queue incoming calls are coming from.
344
345 The call to queue-success() gives some feedback to the agent
346 as they log in and out, that the process has completed.
347
348 macro queue-success()
349 {
350         if( ${queue-announce-success} > 0 )
351         {
352                 switch(${MACRO_EXTEN:0:1})
353                 {
354                 case I:
355                         Playback(agent-loginok);
356                         Hangup();
357                 case O:
358                         Playback(agent-loggedoff);
359                         Hangup();
360                 }
361         }
362 }
363
364
365 The queue-addremove macro is defined in this manner:
366
367 macro queue-addremove(queuename,penalty)
368 {
369         switch(${MACRO_EXTEN:0:1})
370         {
371         case I:  // Login
372                 {
373                 AddQueueMember(${queuename},Local/${MACRO_EXTEN:1}@agents,${penalty});
374                 }
375         case O:  // Logout
376                 {
377                 RemoveQueueMember(${queuename},Local/${MACRO_EXTEN:1}@agents);
378                 }
379         case P:  // Pause
380                 {
381                 PauseQueueMember(${queuename},Local/${MACRO_EXTEN:1}@agents);
382                 }
383         case U:  // Unpause
384                 {
385                 UnpauseQueueMember(${queuename},Local/${MACRO_EXTEN:1}@agents);
386                 }
387         default: // Invalid
388                 {
389                 Playback(invalid);
390                 }
391         }
392 }
393
394 Basically, it uses the first character of the MACRO_EXTEN variable, to determine the
395 proper actions to take. In the above dial plan code, only the cases I or O are used,
396 which correspond to the Login and Logout actions.
397
398
399 =======================================================
400 |    Controlling The Way Queues Call the Agents       |
401 =======================================================
402
403 Notice in the above, that the commands to manipulate agents in queues have
404 "@agents" in their arguments. This is a reference to the agents context:
405
406 context agents
407 {
408         // General sales queue
409         8010 =>
410         {
411                 Set(QUEUE_MAX_PENALTY=10);
412                 Queue(sales-general|t);
413                 Set(QUEUE_MAX_PENALTY=0);
414                 Queue(sales-general|t);
415                 Set(CALLERID(name)=EmptySalQ);
416                 goto dispatch|s|1;
417         }
418         // Customer Service queue
419         8011 =>
420         {
421                 Set(QUEUE_MAX_PENALTY=10);
422                 Queue(customerservice|t);
423                 Set(QUEUE_MAX_PENALTY=0);
424                 Queue(customerservice|t);
425                 Set(CALLERID(name)=EMptyCSVQ);
426                 goto dispatch|s|1;
427         }
428         8013 =>
429         {
430                 Dial(iax2/sweatshop/9456@from-ecstacy);
431
432                 Set(CALLERID(name)=EmptySupQ);
433                 Set(QUEUE_MAX_PENALTY=10);
434                 Queue(support-dispatch,t);
435                 Set(QUEUE_MAX_PENALTY=20);
436                 Queue(support-dispatch,t);
437                 Set(QUEUE_MAX_PENALTY=0); // means no max
438                 Queue(support-dispatch,t);
439                 goto dispatch|s|1;
440         }
441         6121 => &callagent(${RAQUEL});
442         6165 => &callagent(${SPEARS});
443         6170 => &callagent(${ROCK});
444         6070 => &callagent(${SALINE});
445 }
446
447 In the above, the variables ${RAQUEL}, etc stand for
448 actual devices to ring that person's
449 phone (like Zap/37).
450
451 The 8010, 8011, and 8013 extensions are purely for transferring
452 incoming callers to queues. For instance, a customer service 
453 agent might want to transfer the caller to talk to sales. The 
454 agent only has to transfer to extension 8010, in this case.
455
456 Here is the callagent macro, note that if a person in the
457 queue is called, but does not answer, then they are automatically
458 removed from the queue.
459
460 macro callagent(device)
461 {
462         if( ${GROUP_COUNT(${MACRO_EXTEN}@agents)}=0 )
463         {
464                 Set(OUTBOUND_GROUP=${MACRO_EXTEN}@agents);
465                 Dial(${device}|300|t);
466                 switch(${DIALSTATUS})
467                 {
468                 case BUSY:
469                         Busy();
470                         break;
471                 case NOANSWER:
472                         Set(queue-announce-success=0);
473                         goto queues-manip|O${MACRO_EXTEN}|1;
474                 default:
475                         Hangup();
476                         break;
477                 }
478         }
479         else
480         {
481                 Busy();
482         }
483 }
484
485 In the callagent macro above, the ${MACRO_EXTEN} will
486 be 6121, or 6165, etc, which is the extension of the agent.
487
488 The use of the GROUP_COUNT, and OUTBOUND_GROUP follow this line
489 of thinking. Incoming calls can be queued to ring all agents in the
490 current priority. If some of those agents are already talking, they
491 would get bothersome call-waiting tones. To avoid this inconvenience,
492 when an agent gets a call, the OUTBOUND_GROUP assigns that 
493 conversation to the group specified, for instance 6171@agents.
494 The ${GROUP_COUNT()} variable on a subsequent call should return
495 "1" for that group. If GROUP_COUNT returns 1, then the busy() 
496 is returned without actually trying to dial the agent.
497
498 ================ Pre Acknowledgement Message
499
500 If you would like to have a pre acknowledge message with option to reject the message
501 you can use the following dialplan Macro as a base with the 'M' dial argument.
502
503 [macro-screen]
504 exten=>s,1,Wait(.25)
505 exten=>s,2,Read(ACCEPT|screen-callee-options|1)
506 exten=>s,3,Gotoif($[${ACCEPT} = 1] ?50)
507 exten=>s,4,Gotoif($[${ACCEPT} = 2] ?30)
508 exten=>s,5,Gotoif($[${ACCEPT} = 3] ?40)
509 exten=>s,6,Gotoif($[${ACCEPT} = 4] ?30:30)
510 exten=>s,30,Set(MACRO_RESULT=CONTINUE)
511 exten=>s,40,Read(TEXTEN|custom/screen-exten|)
512 exten=>s,41,Gotoif($[${LEN(${TEXTEN})} = 3]?42:45)
513 exten=>s,42,Set(MACRO_RESULT=GOTO:from-internal^${TEXTEN}^1)
514 exten=>s,45,Gotoif($[${TEXTEN} = 0] ?46:4)
515 exten=>s,46,Set(MACRO_RESULT=CONTINUE)
516 exten=>s,50,Playback(after-the-tone)
517 exten=>s,51,Playback(connected)
518 exten=>s,52,Playback(beep)
519
520 ================ Caveats 
521
522 In the above examples, some of the possible error checking has been omitted,
523 to reduce clutter and make the examples clearer.
524