Practical Asterisk 1.4 and 1.6

Foreword xxvii

Preface xxix

Acknowledgments xxxi

About the Authors xxxiii



Chapter 1: How to Get the Most Out of This Book 1

1.1 What Is Asterisk? 1

1.2 Who Should Read This Book? 3

1.3 Updates and Versions of the Book 5

1.4 Reader Contributions and Feedback 5

1.5 Additional Resources 6



Chapter 2: Installation and "Hello World" 9

2.1 Installing Asterisk on the Server 9

2.2 Calling "Hello World" from the CLI 10

2.3 Calling "Hello World" with a SIP Phone 13

2.4 Building a Minimal Phone System with Two SIP Phones 16

2.5 Rights Administration with Contexts 18

2.6 Calls to and from the Public Switched Telephone Network 20



Chapter 3: Dialplan Fundamentals 25

3.1 Contexts 25

3.2 Extensions 26

3.3 Pattern Matching 29

3.4 Include Statements 37

3.5 The ${EXTEN} Variable and the ${CALLERID(num)} Function 39



Chapter 4: Case Study: A Typical Business Telephone System 41

4.1 The Numbering Plan 43

4.2 Choosing the Infrastructure 44

4.3 Base Configuration 48

4.4 What Next? 55



Chapter 5: Dialplan Programming 57

5.1 Programming "How-To" 57

5.2 Variables 60

5.3 Special Extensions 67

5.4 Macros 70

5.5 Deprecated Features 71



Chapter 6: Asterisk Extension Language 73

6.1 CLI Commands for AEL 73

6.2 aelparse 74

6.3 Comparing extensions.conf with extensions.ael 74

6.4 Choosing between extensions.ael and extensions.conf 88



Chapter 7: Protocols 89

7.1 Network Protocols 89

7.2 Channels 95

7.3 Peers, Users, and Friends 97

7.4 IAX Versus SIP 97



Chapter 8: Making Connections 101

8.1 Codecs 101

8.2 Integrated Services Digital Network 105

8.3 Analog Telephony 112



Chapter 9: Voicemail 115

9.1 Example Implementations 115

9.3 Dialplan Applications 121

9.4 voicemail.conf 124

9.5 Dial-by-Name 133

9.6 Saving Passwords in voicemail.conf 135



Chapter 10: Interactive Voice Response 137

10.1 A Simple IVR 138

10.2 Multilevel IVR Systems 140

10.3 Text-to-Speech 142



Chapter 11: The Asterisk Database 145

11.1 The Asterisk Database 145

11.2 Database Access from the Command-Line Interface 147

11.3 Database Access from the System Shell 149

11.4 Database Backup 150

11.5 Application Example: Call Forwarding 150

11.6 Application Example: Calling Card 152



Chapter 12: Queues 155

12.1 Extension for Testing Hold Music 156

12.2 musiconhold.conf 157

12.3 queues.conf 160

12.4 agents.conf 166

12.5 Extensions 168

12.6 Log File 170



Chapter 13: Features 175

13.1 Call Transfer 175

13.2 Call Parking 176



Chapter 14: Conferencing 179

14.1 Installation and the Timing Device 179

14.2 Defining Conference Rooms 180

14.3 Access from the Dialplan 180

14.4 Announcing the Number of Conference Participants 181



Chapter 15: External Control of Asterisk 183

15.1 asterisk -rx "command" 183

15.2 Call Files 184

15.3 The Asterisk Manager Interface 186

15.4 The Asynchronous JavaScript Asterisk Manager 195



Chapter 16: Asterisk Gateway Interface 201

16.1 Data Streams 201

16.2 Examples in Various Programming Languages 203



Chapter 17: Fax Server 213

17.1 Installing IAXmodem 213

17.2 Installing Hylafax 217

17.3 Receiving Faxes 222

17.4 Sending Faxes 223

17.5 Sending Received Faxes as E-Mail 224



Chapter 18: Busy Lamp Field, Hints, Pickup 227

18.1 Controlling Indicators 228

18.2 Subscriptions 231

18.3 Configuring Telephones for BLF 231

18.4 Testing the Hints 236

18.5 Configuring Pickup 237

18.6 Advanced BLF Indicators in Asterisk 1.6 242



Appendix A: Installation Instructions for Asterisk 1.4 247

A.1 LibPRI 249

A.2 DAHDI 250

A.3 Asterisk 252



Appendix B: Dialplan Applications 257

B.1 AbsoluteTimeout() 263

B.2 AddQueueMember() 264

B.3 ADSIProg() 266

B.4 AgentCallbackLogin() 267

B.5 AgentLogin() 268

B.6 AgentMonitorOutgoing() 270

B.7 AGI() 272

B.8 AlarmReceiver() 276

B.9 AMD() 277

B.10 Answer() 281

B.11 AppendCDRUserField() 282

B.12 Authenticate() 283

B.13 Background() 287

B.14 BackgroundDetect() 290

B.15 Bridge() 292

B.16 Busy() 293

B.17 ChangeMonitor() 293

B.18 ChanIsAvail() 295

B.19 ChannelRedirect() 297

B.20 ChanSpy() 299

B.21 CheckGroup() 305

B.22 ClearHash() 306

B.23 Congestion() 307

B.24 ContinueWhile() 308

B.25 ControlPlayback() 309

B.26 Curl() 311

B.27 Cut() 312

B.28 DAHDIBarge() 312

B.29 DAHDIRAS() 314

B.30 DAHDIScan() 315

B.31 DAHDISendKeypadFacility() 316

B.32 DateTime() 317

B.33 DBdel() 318

B.34 DBdeltree() 319

B.35 DBget() 320

B.36 DBput() 321

B.37 DeadAGI() 322

B.38 Dial() 325

B.39 Dictate() 341

B.40 DigitTimeout() 343

B.41 Directory() 344

B.42 DISA() 346

B.43 DumpChan() 351

B.44 DUNDiLookup() 352

B.45 EAGI() 353

B.46 Echo() 356

B.47 EndWhile() 357

B.48 EnumLookup() 358

B.49 Eval() 359

B.50 Exec() 360

B.51 ExecIf() 362

B.52 ExecIfTime() 363

B.53 ExitWhile() 364

B.54 ExtenSpy() 365

B.55 ExternalIVR() 369

B.56 FastAGI() 372

B.57 Festival() 372

B.58 Flash() 374

B.59 FollowMe() 376

B.60 ForkCDR() 377

B.61 GetCPEID() 381

B.62 GetGroupCount() 382

B.63 GetGroupMatchCount() 383

B.64 Gosub() 384

B.65 GosubIf() 385

B.66 Goto() 386

B.67 GotoIf() 388

B.68 GotoIfTime() 390

B.69 Hangup() 392

B.70 HasNewVoicemail() 393

B.71 HasVoicemail() 394

B.72 IAX2Provision() 395

B.73 ICES() 396

B.74 ImportVar() 396

B.75 Incomplete() 398

B.76 JabberSend() 398

B.77 JabberStatus() 399

B.78 KeepAlive() 401

B.79 Log() 401

B.80 LookupBlacklist() 402

B.81 LookupCIDName() 404

B.82 Macro() 405

B.83 MacroExclusive() 408

B.84 MacroExit() 409

B.85 MacroIf() 410

B.86 mailboxExists() 411

B.87 Math() 413

B.88 MD5() 413

B.89 MD5Check() 414

B.90 MeetMe() 415

B.91 MeetMeAdmin() 423

B.92 MeetMeChannelAdmin() 425

B.93 MeetMeCount() 426

B.94 Milliwatt() 428

B.95 MinivmAccMess() 429

B.96 MinivmDelete() 430

B.97 MinivmGreet() 431

B.98 MinivmNotify() 432

B.99 MinivmRecord() 433

B.100 MixMonitor() 434

B.101 Monitor() 436

B.102 Morsecode() 440

B.103 MP3Player() 441

B.104 MSet() 442

B.105 MusicOnHold() 443

B.106 NBScat() 445

B.107 NoCDR() 446

B.108 NoOp() 446

B.109 ODBCFinish() 448

B.110 Page() 448

B.111 Park() 450

B.112 ParkAndAnnounce() 452

B.113 ParkedCall() 454

B.114 PauseMonitor() 456

B.115 PauseQueueMember() 456

B.116 Pickup() 458

B.117 PickupChan() 460

B.118 Playback() 461

B.119 Playtones() 463

B.120 PrivacyManager() 464

B.121 Proceeding() 467

B.122 Progress() 467

B.123 Queue() 468

B.124 QueueLog() 473

B.125 RaiseException() 474

B.126 Random() 475

B.127 Read() 476

B.128 ReadExten() 480

B.129 ReadFile() 481

B.130 RealTime() 482

B.131 RealTimeUpdate() 483

B.132 ReceiveFAX() 484

B.133 Record() 486

B.134 RemoveQueueMember() 489

B.135 ResetCDR() 490

B.136 ResponseTimeout() 491

B.137 RetryDial() 492

B.138 Return() 494

B.139 Ringing() 495

B.140 SayAlpha() 496

B.141 SayDigits() 496

B.142 SayNumber() 497

B.143 SayPhonetic() 499

B.144 SayUnixTime() 500

B.145 SendDTMF() 502

B.146 SendFAX() 503

B.147 SendImage() 504

B.148 SendText() 505

B.149 SendURL() 507

B.150 Set() 509

B.151 SetAccount() 512

B.152 SetAMAFlags() 513

B.153 SetCallerID() 514

B.154 SetCallerPres() 515

B.155 SetCDRUserField() 516

B.156 SetCIDName() 517

B.157 SetCIDNum() 518

B.158 SetGlobalVar() 519

B.159 SetGroup() 521

B.160 SetLanguage() 521

B.161 SetMusicOnHold() 522

B.162 SetRDNIS() 523

B.163 SetTransferCapability() 524

B.164 SetVar() 526

B.165 SIPAddHeader() 526

B.166 SIPdtmfMode() 527

B.167 SIPGetHeader() 528

B.168 SMS() 529

B.169 SoftHangup() 532

B.170 Sort() 534

B.171 StackPop() 534

B.172 StartMusicOnHold() 535

B.173 StopMixMonitor() 536

B.174 StopMonitor() 537

B.175 StopMusicOnHold() 538

B.176 StopPlaytones() 539

B.177 System() 540

B.178 Transfer() 541

B.179 TryExec() 543

B.180 TrySystem() 544

B.181 TXTCIDName() 545

B.182 UnpauseMonitor() 546

B.183 UnpauseQueueMember() 547

B.184 UserEvent() 548

B.185 Verbose() 550

B.186 VMAuthenticate() 551

B.187 VoiceMail() 553

B.188 VoiceMailMain() 555

B.189 Wait() 557

B.190 WaitExten() 558

B.191 WaitForNoise() 559

B.192 WaitForRing() 560

B.193 WaitForSilence() 561

B.194 WaitMusicOnHold() 563

B.195 WaitUntil() 564

B.196 While() 566

B.197 Zapateller() 567

B.198 ZapBarge() 568

B.199 ZapRAS() 570

B.200 ZapScan() 571

B.201 ZapSendKeypadFacility() 572



Appendix C: Dialplan Functions 575

C.1 AGENT() 576

C.2 ARRAY() 578

C.3 BASE64_DECODE() 579

C.4 BASE64_ENCODE() 580

C.5 BLACKLIST 580

C.6 CALLERID() 581

C.7 CDR() 584

C.8 CHANNEL() 588

C.9 CHECKSIPDOMAIN() 591

C.10 CURL() 592

C.11 CUT() 593

C.12 DB() 594

C.13 DB_DELETE() 595

C.14 DB_EXISTS() 596

C.15 DUNDILOOKUP() 597

C.16 ENUMLOOKUP() 598

C.17 ENV() 600

C.18 EVAL() 601

C.19 EXISTS() 602

C.20 FIELDQTY() 603

C.21 FILTER() 604

C.22 GLOBAL() 605

C.23 GROUP() 606

C.24 GROUP_COUNT() 607

C.25 GROUP_LIST() 608

C.26 GROUP_MATCH_COUNT() 608

C.27 IAXPEER() 609

C.28 IF() 611

C.29 IFTIME() 612

C.30 ISNULL() 613

C.31 KEYPADHASH() 614

C.32 LANGUAGE() 615

C.33 LEN() 616

C.34 MATH() 617

C.35 MD5() 618

C.36 MUSICCLASS() 619

C.37 ODBC_SQL() 620

C.38 ODBC_USER_DATABASE() 620

C.39 QUEUEAGENTCOUNT() 621

C.40 QUEUE_MEMBER_COUNT() 622

C.41 QUEUE_MEMBER_LIST() 623

C.42 QUOTE() 624

C.43 RAND() 624

C.44 REGEX() 626

C.45 SET() 627

C.46 SHA1() 628

C.47 SIPCHANINFO() 629

C.48 SIPPEER() 630

C.49 SIP_HEADER() 633

C.50 SORT() 634

C.51 STAT() 635

C.52 STRFTIME() 637

C.53 STRPTIME() 638

C.54 TIMEOUT() 640

C.55 TXTCIDNAME() 642

C.56 URIDECODE() 643

C.57 URIENCODE() 644

C.58 VMCOUNT() 645



Appendix D: AGI Command Summary 647

D.1 ANSWER 647

D.2 ASYNCAGI BREAK 648

D.3 CHANNEL STATUS 648

D.4 CONTROL STREAM FILE 649

D.5 DATABASE DEL 650

D.6 DATABASE DELTREE 650

D.7 DATABASE GET 651

D.8 DATABASE PUT 651

D.9 EXEC 652

D.10 GET DATA 653

D.11 GET FULL VARIABLE 653

D.12 GET OPTION 654

D.13 GET VARIABLE 654

D.14 GOSUB 655

D.15 HANGUP 656

D.16 NOOP 656

D.17 RECEIVE CHAR 657

D.18 RECEIVE TEXT 657

D.19 RECORD FILE 658

D.20 SAY ALPHA 659

D.21 SAY DATE 659

D.22 SAY DATETIME 660

D.23 SAY DIGITS 661

D.24 SAY NUMBER 662

D.25 SAY PHONETIC 662

D.26 SAY TIME 663

D.27 SEND IMAGE 664

D.28 SEND TEXT 664

D.29 SET AUTOHANGUP 665

D.30 SET CALLERID 665

D.31 SET CONTEXT 666

D.32 SET EXTENSION 667

D.33 SET MUSIC 667

D.34 SET PRIORITY 668

D.35 SET VARIABLE 669

D.36 STREAM FILE 669

D.37 TDD MODE 670

D.38 VERBOSE 670

D.39 WAIT FOR DIGIT 671



Appendix E: AMI Command Summary 673

E.1 AbsoluteTimeout 673

E.2 AgentCallbackLogin 674

E.3 AgentLogoff 674

E.4 Agents 675

E.5 AGI 675

E.6 Atxfer 676

E.7 Bridge 676

E.8 Challenge 677

E.9 ChangeMonitor 677

E.10 Command 678

E.11 CoreSettings 678

E.12 CoreShowChannels 679

E.13 CoreStatus 679

E.14 CreateConfig 680

E.15 DAHDIDialOffhook 680

E.16 DAHDIDNDoff 681

E.17 DAHDIDNDon 681

E.18 DAHDIHangup 682

E.19 DAHDIRestart 682

E.20 DAHDIShowChannels 683

E.21 DAHDITransfer 684

E.22 DBDel 684

E.23 DBDelTree 685

E.24 DBGet 685

E.25 DBPut 686

E.26 Events 686

E.27 ExtensionState 687

E.28 GetConfig 687

E.29 GetConfigJSON 688

E.30 Getvar 689

E.31 Hangup 689

E.32 IAXnetstats 690

E.33 IAXpeerlist 690

E.34 IAXpeers 691

E.35 JabberSend 691

E.36 ListCategories 692

E.37 ListCommands 692

E.38 Login 693

E.39 Logoff 693

E.40 MailboxCount 694

E.41 MailboxStatus 695

E.42 MeetmeList 695

E.43 MeetmeMute 696

E.44 MeetmeUnmute 696

E.45 ModuleCheck 697

E.46 ModuleLoad 697

E.47 Monitor 698

E.48 Originate 698

E.49 Park 699

E.50 ParkedCalls 700

E.51 PauseMonitor 700

E.52 Ping 701

E.53 PlayDTMF 702

E.54 QueueAdd 702

E.55 QueueLog 703

E.56 QueuePause 703

E.57 QueuePenalty 703

E.58 QueueRemove 704

E.59 QueueRule 704

E.60 Queues 704

E.61 QueueStatus 705

E.62 QueueSummary 705

E.63 Redirect 706

E.64 Reload 706

E.65 SendText 707

E.66 SetCDRUserField 707

E.67 Setvar 708

E.68 ShowDialPlan 708

E.69 SIPnotify 709

E.70 SIPpeers 709

E.71 SIPqualifypeer 710

E.72 SIPshowpeer 710

E.73 SIPshowregistry 711

E.74 Status 712

E.75 StopMonitor 712

E.76 UnpauseMonitor 713

E.77 UpdateConfig 713

E.78 UserEvent 714

E.79 VoicemailUsersList 715

E.80 WaitEvent 715

E.81 ZapDialOffhook 716

E.82 ZapDNDoff 717

E.83 ZapDNDon 717

E.84 ZapHangup 718

E.85 ZapRestart 718

E.86 ZapShowChannels 719

E.87 ZapTransfer 720



Appendix F: Configuration Templates 721

F.1 Creating Templates 722

F.2 Using Templates 722



Appendix G: Upgrading from 1.4 to 1.6 725

G.1 AEL 725

G.2 Core 726

G.3 Voicemail 727

G.4 Dialplan Applications and Functions 727

G.5 CDR 729

G.6 Audio Formats 729

G.7 Channel Drivers 730

G.8 Configuration 731

G.9 Asterisk Manager Interface 731



Appendix H: From Zaptel to DAHDI 733

H.1 DAHDI 734

H.2 Interview with Kevin P. Fleming 737



Appendix I: IAX vs. SIP 741



Appendix J: GNU Free Documentation License 745

0 Preamble 745

1 Applicability and Definitions 746

2 Verbatim Copying 748

3 Copying in Quantity 748

4 Modifications 749

5 Combining Documents 751

6 Collections of Documents 752

7 Aggregation with Independent Works 752

8 Translation 752

9 Termination 753

10 Future Revisions of This License 754

11 Relicensing 754



Index 757