Examples

The examples folder has some examples to get you quickly oriented with ARI4Java, please make sure your read the Understanding ARI on Getting Started page.

Vagrant 🧰

For convenience 🍻 the examples work off an Asterisk Server *️⃣ in a Vagrant Box 🖥️.

You will need to install Vagrant & VirtualBox (or Docker if you're on a Mac with Apple Silicon)

From the examples folder executing vagrant up (or vagrant up --provider docker for M1 Mac) will setup an Ubuntu 20.04 Box, then downloads and installs Asterisk within it. vagrant halt will stop the box (you can start it later using vagrant up) and vagrant destroy will delete it (useful to reclaim the space it used when it's no longer required).

No only is Asterisk included in the vagrant box, but via the Asterisk static-http server a web phone 📞 (using JsSIP) has been created. It can be accessed at https://192.168.56.44:8089/static/ari4java-phone.html. :warning: As we are using self-singed certificates the browser will give an error, you will need to acknowledge that and then allow access to the :microphone: microphone. On Google Chrome Open Advanced and use proceed to website option, if that is missing type thisisunsafe 🥷

At the top of the Web Phone card there is an option to login with either extension 100 or 200.

Once logged in there's a convenient Examples card with buttons to use for the examples below 😎.

🔧 Advanced after the initial setup of the vagrant box you add the NET_BRIDGE env to the up command to add a bridged network interface, this will get an IP from your router so you can connect to Asterisk from other devices on your network, like a physical phone or your mobile phone with the Zoiper app. Extension 300 (with pass abc123) has been setup for this purpose. NET_BRIDGE=on vagrant up you'll be prompted for which network interface to bridge, once the box is started vagrant ssh the ssh banner will show the IP addresses, it usually the last one (eg in my case IPv4 address for enp0s9: 192.168.43.193)

Weasels 🚲

Dialling 901 from a connected phone simply plays the "Weasels have eaten our phone system" 😱 prompt when receiving a StasisStart event then hangs up. The app will stay running for 5 minutes before it exits, so you need to dial 901 from a phone before the example stops. In a real word app you'll not want to exit, it would run indefinitely but as this is an example it waits around for 5 minutes.

The vagrant box has the following in the extensions.conf

; Weasels Example
exten => 901,1,NoOp(Weasels Example)
same => n,Answer()
same => n,Stasis(weasels-app)

This will hand off from the dialplan to the Weasels Java code when 901 is dialed.

Before dialing 901 we need to run the program, it has 4 arguments: url, user pass & ari_ver so to run with Gradle in the example folder

./gradlew runWeaselsExample --args='"http://192.168.56.44:8088/" ari4java yothere 6.0.0'

Once running use the convenient button on the Web phone.

See the source code

Comprehensive 🏎️

The comprehensive example shows the use of the Web/REST API and the Stasis dialplan app. In the example you'll see the use of 2 HashMaps: 1 that contains lookups and the other State objects. In a real world app these should be replaced by a traditional database or no-sql alternative. In order to keep dependencies to a minimum the Web/REST API was created using Netty, but you could use any framework to create a REST API (eg. Spring Boot with spring-boot-starter-web).

Web/REST API:

• /start/{extn1}/{extn2} - starts a call to {extn1} & {extn2}. Returns json with an id
• /end/{id} - ends the call using the {id} returned from /start/...

Dialplan:

• 902 - calls extension 100
• 903 - calls extension 200

The vagrant box has the following in the extensions.conf

; Comprehensive Example
exten => _90[2-3],1,NoOp(Comprehensive Example)
same => n,Answer()
same => n,Stasis(comprehensive-app)

This will hand off from the dialplan to the Comprehensive Java code when 902 or 903 is dialed.

Before dialing we need to run the program, it has 5 arguments: port, url, user, pass & ari_ver so to run with Gradle in the example folder

./gradlew runComprehensiveExample --args='8090 "http://192.168.56.44:8088/" ari4java yothere 6.0.0'

Once running use one the convenient buttons on the Web phone.

For the Rest Call ... or Statis Call ... you'll need a 2 browser windows - 1 logged in to 100 and the other 200.

• The Rest Echo Test calls the logged in extension then a 123 extension in the dailplan that executes the Echo dialplan app.
• The Rest Call ... 1st calls the logged in extension, you'll need to answer that, then the other extension, you'll need to answer in that in the other window.
• The Statis Call ... dials into the dailplan to the other extension, you'll need to answer in that in the other window.

Enjoy talking to yourself 🤣

See the source code