First, install the ruby_speech dependencies
Then, 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, along with other gems that Adhearsion depends on (such as
rspec). Also included, but commented out, are several popular or useful plugins. To enable their usage, simply uncomment the appropriate line from the Gemfile.
When you are done with that, exit your editor and run
bundle install. This will ensure that all gems referenced in the Gemfile are installed and version-locked. It's important to do this now whether or not you've modified the Gemfile in order to ensure that all dependencies are met; otherwise you might experience errors.
$ 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,
# 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 end
This 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 = "email@example.com" 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:
You will need a softphone or physical IP phone to make a test call and ensure everything is working correctly. Installation/configuration will vary by the phone you use and the telephony engine you intend to connect to. Check the docs for your telephony engine of choice for guidance on making an initial test call, and be sure to test call the standalone engine first before attempting to integrate with Adhearsion in order to simplify troubleshooting.
Start your Adhearsion app by running
ahn -, then try to make a call to it by calling your telephony engine. If you've configuring intregation with Adhearsion correctly, all calls made to the engine should be immediately forwarded to Adhearsion. By default, a generated Adhearsion app responds to all incoming calls with the SimonGame. If everything is configured correctly, the SimonGame will begin reading numbers to you and respond with 'good' or 'try again' when you enter the numbers via the dialpad.
Enjoy your time working with Adhearsion, and feel free to explore the rest of the documentation provided here.