Getting Started > Installation

  • Getting Started > Installation

    Install the Adhearsion gem

    First, install the ruby_speech dependencies

    Then, the Adhearsion gem and its dependencies:

    $ gem install adhearsion

    Create an Adhearsion application

    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
           chmod  script/ahn
    $ cd myapp

    Configure your application

    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
    Fetching gem metadata from
    Using rake (
    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
      # 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
      # = "" # Your AMI host
      # Use with FreeSWITCH
      # config.punchblock.platform = :freeswitch # Use FreeSWITCH
      # config.punchblock.password = "" # Your Inbound EventSocket password
      # = "" # Your IES host
    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
    Adhearsion.router do
      # Specify your call routes, directing calls with particular attributes to a controller
      route 'default', SimonGame

    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]
      # 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 [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]               = 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@"

    Connecting to your telephony engine

    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:

    Make a test call

    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.


    Back to Prerequisites Continue to Console
blog comments powered by Disqus