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