First, install the Adhearsion gem and its dependencies:
$ gem install adhearsion
Next, create your first Adhearsion application:
$ ahn create myapp create config create config/adhearsion.rb create config/environment.rb create lib create lib/simon_game.rb create script create script/ahn create spec create spec/spec_helper.rb create spec/call_controllers create spec/support create Gemfile create .gitignore create .rspec create Procfile create Rakefile create README.md chmod script/ahn $ cd myapp
Looking at the output from ahn create, you will see several files are generated for you. Here are the most important ones:
Here is the Gemfile that is generated with your new application:
source :rubygems
gem "adhearsion", "~> 2.1.0"
#
# Here are some example plugins you might like to use. Simply
# uncomment them and run `bundle install`.
#
# gem 'adhearsion-asterisk'
# gem 'adhearsion-rails'
# gem 'adhearsion-activerecord'
# gem 'adhearsion-ldap'
# gem 'adhearsion-xmpp'
# gem 'adhearsion-drb'In it you can see the Adhearsion framework itself is required. Also included, but commented out, are several popular or useful plugins. To enable their usage, simply uncomment the line from the Gemfile. When you are done with that, install all the plugins you selected by running bundle install:
$ bundle install
Fetching gem metadata from http://rubygems.org/.........
Fetching gem metadata from http://rubygems.org/..
Using rake (0.9.2.2)
Using i18n (0.6.0)
Using multi_json (1.3.6)
Using activesupport (3.2.8)
Using adhearsion-loquacious (1.9.3)
Using bundler (1.1.4)
Using timers (1.0.1)
Using celluloid (0.11.1)
Using countdownlatch (1.0.0)
Using deep_merge (1.0.0)
Using ffi (1.1.5)
Using future-resource (1.0.0)
Using connection_pool (0.9.2)
Using girl_friday (0.10.0)
Using has-guarded-handlers (1.3.1)
Using little-plugger (1.1.3)
Using logging (1.7.2)
Using coderay (1.0.7)
Using method_source (0.8)
Using slop (3.3.2)
Using pry (0.9.10)
Using eventmachine (0.12.10)
Using nokogiri (1.5.5)
Using niceogiri (1.0.2)
Using blather (0.8.0)
Using nio4r (0.4.0)
Using celluloid-io (0.11.0)
Using ruby_ami (1.2.1)
Using json (1.7.4)
Using ruby_fs (1.0.0)
Using ruby_speech (1.0.0)
Using state_machine (1.1.2)
Using punchblock (1.4.0)
Using thor (0.16.0)
Using adhearsion (2.1.0)
Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.
Next is the main Adhearsion configuration file, config/adhearsion.rb:
# encoding: utf-8
Adhearsion.config do |config|
# Centralized way to specify any Adhearsion platform or plugin configuration
# - Execute rake config:show to view the active configuration values
#
# To update a plugin configuration you can write either:
#
# * Option 1
# Adhearsion.config.<plugin-name> do |config|
# config.<key> = <value>
# end
#
# * Option 2
# Adhearsion.config do |config|
# config.<plugin-name>.<key> = <value>
# end
config.development do |dev|
dev.platform.logging.level = :debug
end
##
# Use with Rayo (eg Voxeo PRISM)
#
# config.punchblock.username = "" # Your XMPP JID for use with Rayo
# config.punchblock.password = "" # Your XMPP password
##
# Use with Asterisk
#
# config.punchblock.platform = :asterisk # Use Asterisk
# config.punchblock.username = "" # Your AMI username
# config.punchblock.password = "" # Your AMI password
# config.punchblock.host = "127.0.0.1" # Your AMI host
##
# Use with FreeSWITCH
#
# config.punchblock.platform = :freeswitch # Use FreeSWITCH
# config.punchblock.password = "" # Your Inbound EventSocket password
# config.punchblock.host = "127.0.0.1" # Your IES host
end
Adhearsion::Events.draw do
# Register global handlers for events
#
# eg. Handling Punchblock events
# punchblock do |event|
# ...
# end
#
# eg Handling PeerStatus AMI events
# ami name: 'PeerStatus' do |event|
# ...
# end
#
end
Adhearsion.router do
#
# Specify your call routes, directing calls with particular attributes to a controller
#
route 'default', SimonGame
endThis is just a skeleton however. To see the full list of available configuration options avaiable, you can always run rake config:show. Note that your output may be different, depending on which plugins you selected above:
$ rake config:show Adhearsion configured environment: development Adhearsion.config do |config| # ******* Configuration for platform ************** # Active environment. Supported values: development, production, staging, test [AHN_PLATFORM_ENVIRONMENT] config.platform.environment = :development # Folder to include the own libraries to be used. Adhearsion loads any ruby file # located into this folder during the bootstrap process. Set to nil if you do not # want these files to be loaded. This folder is relative to the application root folder. [AHN_PLATFORM_LIB] config.platform.lib = "lib" # Log configuration [AHN_PLATFORM_LOGGING] config.platform.logging # A log formatter to apply to all active outputters. If nil, the Adhearsion default formatter will be used. [AHN_PLATFORM_LOGGING_FORMATTER] config.platform.logging.formatter = nil # Supported levels (in increasing severity) -- :trace < :debug < :info < :warn < :error < :fatal [AHN_PLATFORM_LOGGING_LEVEL] config.platform.logging.level = :debug # An array of log outputters to use. The default is to log to stdout and log/adhearsion.log. # Each item must be either a string to use as a filename, or a valid Logging appender (see http://github.com/TwP/logging) [AHN_PLATFORM_LOGGING_OUTPUTTERS] config.platform.logging.outputters = ["log/adhearsion.log"] # Adhearsion process name, useful to make it easier to find in the process list # Pro tip: set this to your application's name and you can do "killall myapp" # Does not work under JRuby. [AHN_PLATFORM_PROCESS_NAME] config.platform.process_name = "ahn" # Adhearsion application root folder [AHN_PLATFORM_ROOT] config.platform.root = "/Users/bklang/src/adhearsion-website/docs/artifacts/80eddf8bb53eddb83f89b24ae751ba75/source/getting-started/myapp" # ******* Configuration for punchblock ************** # The domain at which to address calls [AHN_PUNCHBLOCK_CALLS_DOMAIN] config.punchblock.calls_domain = nil # The amount of time to wait for a connection [AHN_PUNCHBLOCK_CONNECTION_TIMEOUT] config.punchblock.connection_timeout = 60 # The default TTS voice to use. [AHN_PUNCHBLOCK_DEFAULT_VOICE] config.punchblock.default_voice = nil # Host punchblock needs to connect (where rayo/asterisk/freeswitch is located) [AHN_PUNCHBLOCK_HOST] config.punchblock.host = nil # The media engine to use. Defaults to platform default. [AHN_PUNCHBLOCK_MEDIA_ENGINE] config.punchblock.media_engine = nil # The domain at which to address mixers [AHN_PUNCHBLOCK_MIXERS_DOMAIN] config.punchblock.mixers_domain = nil # Authentication credentials [AHN_PUNCHBLOCK_PASSWORD] config.punchblock.password = "1" # Platform punchblock shall use to connect to the Telephony provider. Currently supported values: # - :xmpp # - :asterisk # - :freeswitch [AHN_PUNCHBLOCK_PLATFORM] config.punchblock.platform = :xmpp # Port punchblock needs to connect [AHN_PUNCHBLOCK_PORT] config.punchblock.port = 5222 # The number of times to (re)attempt connection to the server [AHN_PUNCHBLOCK_RECONNECT_ATTEMPTS] config.punchblock.reconnect_attempts = Infinity # Delay between connection attempts [AHN_PUNCHBLOCK_RECONNECT_TIMER] config.punchblock.reconnect_timer = 5 # The root domain at which to address the server [AHN_PUNCHBLOCK_ROOT_DOMAIN] config.punchblock.root_domain = nil # Authentication credentials [AHN_PUNCHBLOCK_USERNAME] config.punchblock.username = "usera@127.0.0.1" end
Adhearsion currently supports three protocols for communication with the telephony engine it is controlling; Rayo, Asterisk AMI with AsyncAGI and FreeSWITCH EventSocket. As such, the configuration for each is slightly different. You will notice that the generated config file contains scaffolding for each, and that the default protocol is Rayo. You are, however, encouraged to store sensitive credentials in the application's environment rather than in the config file.
Please see the documentation for connecting Adhearsion to the telephony engine of your choice:
By default, a generated Adhearsion app includes the SimonGame. You can boot your app by running ahn - and immediately make a call to it. If everything is configured correctly, you should be prompted to play a game. Enjoy your time working with Adhearsion, and feel free to explore the rest of the documentation provided here.