- Removing the "README." from the name of the README files.
[asterisk/asterisk.git] / doc / privacy.txt
1 Title: Everything About The Privacy Options In The Dial Command That
2 You Never Wanted To Know, And Even A Little More On Zapateller and
3 PrivacyManager:
4
5 by Steve Murphy
6
7
8 So, you want to avoid talking to pesky telemarketers/charity
9 seekers/poll takers/magazine renewers/etc?
10
11 =============
12 First of all:
13 =============
14
15 Try the FTC "Don't call" database, this alone will reduce your
16 telemarketing call volume considerably.  (see:
17 https://www.donotcall.gov/default.aspx ) But, this list won't protect
18 from the Charities, previous business relationships, etc.
19
20
21 =================================
22 Next, Fight against autodialers!!
23 =================================
24
25 Zapateller detects if callerid is present, and if not, plays the
26 da-da-da tones that immediately precede messages like, "I'm sorry,
27 the number you have called is no longer in service."
28
29 Most humans, even those with unlisted/callerid-blocked numbers, will
30 not immediately slam the handset down on the hook the moment they hear
31 the three tones. But autodialers seem pretty quick to do this.
32
33 I just counted 40 hangups in Zapateller over the last year in my
34 CDR's.  So, that is possibly 40 different telemarketers/charities that have
35 hopefully slashed my back-waters, out-of-the-way, humble home phone
36 number from their lists.
37
38 I highly advise Zapateller for those seeking the nirvana of "privacy".
39
40
41 =======================================
42 Next, Fight against the empty CALLERID!
43 =======================================
44
45 A considerable percentage of the calls you don't want, come from
46 sites that do not provide CallerID. 
47
48 Null callerid's are a fact of life, and could be a friend with an
49 unlisted number, or some charity looking for a handout. The
50 PrivacyManager application can help here. It will ask the caller to
51 enter a 10-digit phone number. They get 3 tries(configurable), and this is
52 configurable, with control being passed to priority+101 if they won't
53 supply one.
54
55 PrivacyManager can't guarantee that the number they supply is any
56 good, tho, as there is no way to find out, short of hanging up and
57 calling them back. But some answers are obviously wrong. For instance,
58 it seems a common practice for telemarketers to use your own number
59 instead of giving you theirs. A simple test can detect this. More
60 advanced tests would be to look for -555- numbers, numbers that count
61 up or down, numbers of all the same digit, etc.
62
63 My logs show that 39 have hung up in the PrivacyManager script over
64 the last year.
65
66 (Note: Demanding all unlisted incoming callers to enter their CID may
67 not always be appropriate for all users. Another option might be to
68 use call screening. See below.)
69
70 ==========================
71 Next, use a WELCOME MENU !
72 ==========================
73
74 Experience has shown that simply presenting incoming callers with
75 a set of options, no matter how simple, will deter them from calling
76 you. In the vast majority of situations, a telemarketer will simply
77 hang up rather than make a choice and press a key.
78
79 This will also immediately foil all autodialers that simply belch a
80 message in your ear and hang up.
81
82
83 ----------------------------------------------
84 Example usage of Zapateller and PrivacyManager:
85 ----------------------------------------------
86
87 [homeline]
88 exten => s,1,Answer
89 exten => s,2,SetVar,repeatcount=0
90 exten => s,3,Zapateller,nocallerid
91 exten => s,4,PrivacyManager
92 exten => s,105,Background(tt-allbusy)       ;; do this if they don't enter a number to Privacy Manager
93 exten => s,106,Background(tt-somethingwrong)
94 exten => s,107,Background(tt-monkeysintro)
95 exten => s,108,Background(tt-monkeys)
96 exten => s,109,Background(tt-weasels)
97 exten => s,110,Hangup
98 exten => s,5,GotoIf($[ "${CALLERIDNUM}"  = "7773334444" &  "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
99
100 I suggest using Zapateller at the beginning of the context, before
101 anything else, on incoming calls.This can be followed by the
102 PrivacyManager App.
103
104 Make sure, if you do the PrivacyManager app, that you take care of the
105 error condition! or their non-compliance will be rewarded with access
106 to the system. In the above, if they can't enter a 10-digit number in
107 3 tries, they get the humorous "I'm sorry, but all household members
108 are currently helping other telemarketers...", "something is terribly
109 wrong", "monkeys have carried them away...", various loud monkey
110 screechings, "weasels have...", and a hangup. There are plenty of
111 other paths to my torture scripts, I wanted to have some fun.
112
113 In nearly all cases now, the telemarketers/charity-seekers that
114 usually get thru to my main intro, hang up. I guess they can see it's
115 pointless, or the average telemarketer/charity-seeker is instructed
116 not to enter options when encountering such systems. Don't know. 
117
118 ===================
119 Next: Torture Them!
120 ===================
121
122 I have developed an elaborate script to torture Telemarketers, and
123 entertain friends. (See
124 http://www.voip-info.org/wiki-Asterisk+Telemarketer+Torture )
125
126 While mostly those that call in and traverse my teletorture scripts
127 are those we know, and are doing so out of curiosity, there have been
128 these others from Jan 1st,2004 thru June 1st, 2004:
129 (the numbers may or may not be correct.)
130
131 603890zzzz     hung up telemarket options.
132 "Integrated Sale"  called a couple times. hung up in telemarket options
133 "UNITED STATES GOV"  (-- maybe a military recruiter, trying to lure one of my sons).
134 800349zzzz -- hung up in charity intro
135 800349zzzz -- hung up in charity choices, intro, about the only one who actually travelled to the bitter bottom of the scripts!
136 216377zzzz -- hung up the magazine section
137 626757zzzz = "LIR    " (pronounced "Liar"?) hung up in telemarket intro, then choices
138 757821zzzz -- hung up in new magazine subscription options.
139
140 That averages out to maybe 1 a month. That puts into question whether
141 the ratio of the amount of labor it took to make the scripts versus
142 the benefits of lower call volumes was worth it, but, well, I had fun,
143 so what the heck.
144
145 but, that's about it. Not a whole lot. But I haven't had to say "NO"
146 or "GO AWAY" to any of these folks for about a year now ...!
147
148 ========================================
149       Using Call Screening
150 =======================================
151
152 Another option is to use call screening in the Dial command. It has
153 two main privacy modes, one that remembers the CID of the caller, and
154 how the callee wants the call handled, and the other, which does not
155 have a "memory".
156
157 Turning on these modes in the dial command results in this sequence of
158 events, when someone calls you at an extension:
159
160 1. The caller calls the Asterisk system, and at some point, selects an
161 option or enters an extension number that would dial your extension.
162
163 2. Before ringing your extension, the caller is asked to supply an
164 introduction. The application asks them: "After the tone, say your
165 name". They are allowed 4 seconds of introduction.
166
167 3. After that, they are told "Hang on, we will attempt to connect you
168 to your party. Depending on your dial options, they will hear ringing
169 indications, or get music on hold. I suggest music on hold.
170
171 4. Your extension is then dialed. When (and if) you pick up, you are
172 told that a caller presenting themselves as <their recorded intro is
173 played> is calling, and you have options, like being connected,
174 sending them to voicemail, torture, etc.
175
176 5. You make your selection, and the call is handled as you chose.
177
178
179 There are some variations, and these will be explained in due course.
180
181
182 To use these options, set your Dial to something like:
183
184 exten => 3,3,Dial(Zap/5r3&Zap/6r3|35|tmPA(beep))
185
186 or 
187
188 exten => 3,3,Dial(Zap/5r3&Zap/6r3|35|tmP(something)A(beep))
189
190 or 
191
192 exten => 3,3,Dial(Zap/5r3&Zap/6r3|35|tmpA(beep))
193
194
195 The 't' allows the dialed party to transfer the call using '#'. It's
196 optional.
197
198 The 'm' is for music on hold. I suggest it. Otherwise, the calling
199 party gets to hear all the ringing, and lack thereof. It is generally
200 better to use Music On Hold. Lots of folks hang up after the 3rd or
201 4th ring, and you might lose the call before you can enter an option!
202
203 The 'P' option alone will database everything using the extension as a
204 default 'tree'. To get multiple extensions sharing the same database, use
205 P(some-shared-key). Also, if the same person has multiple extensions,
206 use P(unique-id) on all their dial commands.
207
208 Use little 'p' for screening. Every incoming call will include a
209 prompt for the callee's choice. 
210
211 the A(beep), will generate a 'beep' that the callee will hear if they
212 choose to talk to the caller. It's kind of a prompt to let the callee
213 know that he has to say 'hi'. It's not required, but I find it
214 helpful.
215
216 When there is no CallerID, P and p options will always record an intro
217 for the incoming caller. This intro will be stored temporarily in the
218 /var/lib/asterisk/sounds/priv-callerintros dir, under the name
219 NOCALLERID_<extension><channelname> and will be erased after the
220 callee decides what to do with the call.
221
222 Of course, NOCALLERID is not stored in the database. All those with no
223 CALLERID will be considered "Unknown".
224
225 ========================
226  The 'N' and 'n' options
227 ========================
228
229 Two other options exist, that act as modifiers to the privacy options
230 'P' and 'p'. They are 'N' and 'n'. You can enter them as dialing
231 options, but they only affect things if P or p are also in the
232 options.
233
234 'N' says, "Only screen the call if no CallerID is present". So, if a
235 callerID were supplied, it will come straight thru to your extension.
236
237 'n' says, "Don't save any introductions". Folks will be asked to
238 supply an introduction ("At the tone, say your name") every time they
239 call. Their introductions will be removed after the callee makes a
240 choice on how to handle the call. Whether the P option or the p option
241 is used, the incoming caller will have to supply their intro every
242 time they call.
243
244 =======================
245 Recorded Introductions
246 =======================
247
248 [Philosophical Side Note:
249 The 'P' option stores the CALLERID in the database, along with the
250 callee's choice of actions, as a convenience to the CALLEE, whereas
251 introductions are stored and re-used for the convenience of the CALLER.]
252
253 Unless instructed to not save introductions (see the 'n' option above),
254 the screening modes will save the recordings of the caller's names in
255 the directory /var/lib/asterisk/sounds/priv-callerintros, if they have
256 a CallerID.  Just the 10-digit callerid numbers are used as filenames,
257 with a ".gsm" at the end.
258
259 Having these recordings around can be very useful, however...
260
261 First of all, if a callerid is supplied, and a recorded intro for that
262 number is already present, the caller is spared the inconvenience of
263 having to supply their name, which shortens their call a bit.
264
265 Next of all, these intros can be used in voicemail, played over
266 loudspeakers, and perhaps other nifty things. For instance:
267
268 exten => s,7,System(/usr/bin/play /var/lib/asterisk/sounds/priv-callerintros/${CALLERIDNUM}.gsm&|0) 
269
270 When a call comes in at the house, the above priority gets executed,
271 and the callers intro is played over the phone systems speakers. This
272 gives us a hint who is calling.
273
274 (Note: the |0 option at the end of the System command above, is a
275 local mod I made to the System command. It forces a 0 result code to
276 be returned, whether the play command successfully completed or
277 not. Therefore, I don't have to ensure that the file exists or
278 not. While I've turned this mod into the developers, it hasn't been
279 incorporated yet. You might want to write an AGI or shell script to
280 handle it a little more intelligently)
281
282 And one other thing. You can easily supply your callers with an option
283 to listen to, and re-record their introductions. Here's what I did in
284 the home system's extensions.conf. (assume that a
285 Goto(home-introduction|s|1) exists somewhere in your main menu as an
286 option):
287
288 [home-introduction]
289 exten => s,1,Background,intro-options   ;; Script: To hear your Introduction, dial 1.
290                                         ;;         to record a new introduction, dial 2.
291                                         ;;         to return to the main menu, dial 3.
292                                         ;;         to hear what this is all about, dial 4.
293 exten => 1,1,Playback,priv-callerintros/${CALLERIDNUM}
294 exten => 1,2,Goto(s,1)
295 exten => 2,1,Goto(home-introduction-record,s,1)
296 exten => 3,1,Goto(homeline,s,7)
297 exten => 4,1,Playback,intro-intro     ;; Script:
298                                 ;; This may seem a little strange, but it really is a neat
299                                 ;; thing, both for you and for us. I've taped a short introduction
300                                 ;; for many of the folks who normally call us. Using the Caller ID
301                                 ;; from each incoming call, the system plays the introduction
302                                 ;; for that phone number over a speaker, just as the call comes in.
303                                 ;; This helps the folks
304                                 ;; here in the house more quickly determine who is calling.
305                                 ;; and gets the right ones to gravitate to the phone.
306                                 ;; You can listen to, and record a new intro for your phone number
307                                 ;; using this menu.
308 exten => 4,2,Goto(s,1)
309 exten => t,1,Goto(s,1)
310 exten => i,1,Background,invalid
311 exten => i,2,Goto(s,1)
312 exten => o,1,Goto(s,1)
313
314 [home-introduction-record]
315 exten => s,1,Background,intro-record-choices    ;; Script:
316                                 ;;      If you want some advice about recording your
317                                 ;;      introduction, dial 1. 
318                                 ;;      otherwise, dial 2, and introduce yourself after
319                                 ;;      the beep.
320 exten => 1,1,Playback,intro-record
321                                 ;;      Your introduction should be short and sweet and crisp.
322                                 ;;      Your introduction will be limited to 4 seconds.
323                                 ;;      This is NOT meant to be a voice mail message, so
324                                 ;;      please, don't say anything about why you are calling.
325                                 ;;      After we are done making the recording, your introduction
326                                 ;;      will be saved for playback. 
327                                 ;;      If you are the only person that would call from this number, 
328                                 ;;      please state your name.  Otherwise, state your business
329                                 ;;      or residence name instead. For instance, if you are 
330                                 ;;      friend of the family, say, Olie McPherson, and both
331                                 ;;      you and your kids might call here a lot, you might
332                                 ;;      say: "This is the distinguished Olie McPherson Residence!"
333                                 ;;      If you are the only person calling, you might say this:
334                                 ;;      "This is the illustrious Kermit McFrog! Pick up the Phone, someone!!"
335                                 ;;      If you are calling from a business, you might pronounce a more sedate introduction,like,
336                                 ;;      "Fritz from McDonalds calling.", or perhaps the more original introduction:
337                                 ;;      "John, from the Park County Morgue. You stab 'em, we slab 'em!".
338                                 ;;      Just one caution: the kids will hear what you record every time
339                                 ;;      you call. So watch your language!
340                                 ;;      I will begin recording after the tone. 
341                                 ;;      When you are done, hit the # key. Gather your thoughts and get 
342                                 ;;      ready. Remember, the # key will end the recording, and play back
343                                 ;;      your intro. Good Luck, and Thank you!"
344 exten => 1,2,Goto(2,1)
345 exten => 2,1,Background,intro-start
346                                 ;;  OK, here we go! After the beep, please give your introduction.
347 exten => 2,2,Background,beep
348 exten => 2,3,Record,priv-callerintros/${CALLERIDNUM}:gsm|4
349 exten => 2,4,Background,priv-callerintros/${CALLERIDNUM}
350 exten => 2,5,Goto(home-introduction,s,1)
351 exten => t,1,Goto(s,1)
352 exten => i,1,Background,invalid
353 exten => i,2,Goto(s,1)
354 exten => o,1,Goto(s,1)
355
356
357 In the above, you'd most likely reword the messages to your liking,
358 and maybe do more advanced things with the 'error' conditions (i,o,t priorities),
359 but I hope it conveys the idea...
360
361