= Larynx A framework to develop IVR applications in Ruby for the FreeSWITCH (FS) telephony platform. It is used with the FS event socket module to easily develop IVR applications in an asynchronous fashion. It offer some useful functions and classes on top the default FreeSWITCH dialplan commands to make application development easier. Larynx currently implements an 'outbound' socket listener for incoming calls to be handled. An 'inbound' module will probably follow soon enough. == Install On Rubygems.org: sudo gem install larynx You will need to have the FreeSWITCH server installed somewhere you can control. == Example Simplest possible Larynx.answer {|call| call.speak 'Hello world! Or whoever you are.' } Using the bare Application class, below is a guessing game. class Guess < Larynx::Application def run @number = rand(9) + 1 @guess = '' @guesses = 0 get_guess end def get_guess if @guesses < 3 speak(guess_prompt) { @guesses += 1 } else speak "Sorry you didn't guess it. It was #{@number}. Try again soon.", :bargein => false hangup end end def guess_prompt @guesses == 0 ? 'Guess a number between 1 and 9.' : 'Have another guess.' end def check_guess if @guess.to_i == @number speak "You got it! It was #{@guess}. It took you #{@guesses} guesses.", :bargein => false speak "Thanks for playing." hangup else speak "No it's not #{@guess}." get_guess end end def dtmf_received(input) @guess = input check_guess end end Larynx.answer {|call| Guess.run(call) } A more sophisticated example using the Form class class Guess < Larynx::Form field(:guess, :attempts => 3, :length => 1) do prompt :speak => 'Guess a number between 1 and 9.', :interdigit_timeout => 6 reprompt :speak => 'Have another guess.', :interdigit_timeout => 6 setup do @number = rand(9) + 1 @guesses = 0 end validate do @guesses += 1 if guess.size > 0 @number == guess.to_i end invalid do if guess.size > 0 speak "No, it's not #{guess}.", :bargein => false end end success do speak "You got it! It was #{guess}. It took you #{@guesses} guesses.", :bargein => false hangup end failure do speak "Sorry you didn't guess it. It was #{@number}. Try again soon.", :bargein => false hangup end end end Larynx.answer {|call| Guess.run(call) } The Form class wraps up many handy conventions into a pleasant DSL in which allows you to control the caller interaction more easily. Save your app into file and run larynx comand to start the app server ready to receive calls. $ larynx app.rb Now make a call to extension 2000 with a SIP phone. Your app should start. == Configure FreeSWTICH To set up a dialplan which connects to your app read http://wiki.freeswitch.org/wiki/Event_Socket Also take a look at the http://wiki.freeswitch.org/wiki/Event_socket_outbound for background. Example socket diaplan: Which connects calls to destination number 2000 to your event socket app. == Global Hooks Larynx provides three globals hooks you can use to perform some action at each point. The are: Larynx.connect {|call| # you can choose to hangup the call here if you wish } Larynx.answer {|call| # call is answered and ready to interact with the caller } Larynx.hungup {|call| # finish off any logging or some such } Mainly you just use the answer hook. From the examples you can see can start sending commands or start an application class running. You write an app just in this block but you don't want to. == Application Class The application adds a sprinkling of convenience for handling a call, plus you can store instance variables and create methods for structuring you app better. The application should define a run instance method which is used to kick it off when you call MyApp.run(call) The class method initialises some things for you and then calls run on the instance. From there its up to you. You can use all the commands directly rather than call them on the call instance. == Event Hooks The Application and Form classes have a couple of useful event hook methods available which are class MyApp < Larynx::Application def run end def dtmf_received(input) # input is the button the caller just pushed end def hungup # application specific handling of a hangup end end == Form Class The Form class is a sublcass of the Application class with some added goodness. You can use the field DSL to abstract away a lot of the reptitive work and more difficult asynchronous stuff you would have to handle yourself. When collection input from the caller you are usually needing to do one or more of a few things. These are: 1. Set-up something before the caller is prompted for the information. 2. Repeat the prompt for input if the caller doesn't enter anything or does not enter enough digits. 3. Validate the input for constraints beyond length such as a range or finding a matching database record. 4. Perform some task, perhaps say something, if the input is invalid but before the prompt is repeated. 5. Handle the next action if the input is valid 6. Handle the next action if the caller fails enter valid input after a number of attempts. You define these tasks as callbacks for each type of action, be it setup, validate, invalid, success or failure. These callbacks are run in the scope of the form class instance each time so that they can access user defined methods or instance variables you need. Each field defined becomes an attribute on the form class instance which you can use at any time. The value is set to the caller input after each prompt, just use the field attribute method to retrieve it. A form may have as many fields defined you as need. Though the idea would be to group fields with a particular purpose together and define another form for unrelated fields. Lets look at a simple Form class with empty callbacks in place. class MyApp < Larynx::Form field(:my_field, :attempts => 3, :length => 1) do prompt :speak => 'Please enter a value.' setup do # Run once when the field is starts. end validate do # Run when the input is of a valid length. Return true if valid. end invalid do # Run when the input is not a valid length or the validate block returns false. end success do # Run when the input is a valid length and the validate block, if defined, returns true. end failure do # Run when the maximum attempts has been reached and valid input has not been entered. end end end This form will do the following when run: * Define a field attribute method called my_field * Atempt to obtain the field value up to 3 times if the caller fails to successfully enter it * Accept a single digit value as complete and valid intput