Application Design Best Practices

Ben Langfeld edited this page Apr 11, 2012 · 4 revisions

DEPRECATION NOTICE: This is old documentation relevant to Adhearsion 1.x and will soon be removed. See the main documentation for up-to-date info.

Application Design Best Practices

This page is a repository of lessons-learned: what works well, and what does not. This comes from real-world experience building and running Adhearsion applications.

Rails Integration

The default Adhearsion application layout, as generated by the ahn command line, is ideal for a standalone Adhearsion application. But many Adhearsion applications need to integrate with Rails. How best, then, to keep the two application files in sync?

  • Store your Adhearsion application in the same repository as your Rails application. In this way they are versioned and tested as one, minimizing the chance of error. You also avoid having do duplicate any models this way.

  • Use Ahn-Rails generators to install an Adhearsion application scaffold inside an existing Rails application. These generators have several optimizations that will help integrate Adhearsion and Rails.

Audio Prompts

Most telephony applications will eventually need more prompts than come with Asterisk. Managing these is like managing images in a web application -- consideration needs to be made to keep things organized.

  • Keep your audio prompts in an "assets" or "prompts" directory inside the application repository. In this way your prompts will be versioned with your application. Avoid the "public" directory so prompts are not accidentally served via Rails (unless, of course, you want this for some reason, eg. with Tropo).

  • Where possible, tell Asterisk to play the audio prompts directly from your application. This can be done by passing a full path to the audio prompt with methods like #play and #input. Use your application root so this can be done programmatically: play "#{AHN_ROOT}/prompts/my_menu"

  • Always store the highest quality audio format you can. Someday, down the road, you will need to edit the prompt and in this way you can avoid generational loss. If you need to generate a different format for use with Asterisk, do it as a Rake task and run it each time you deploy the code. Sox will help with this task. See this page on VoIP Info Wiki for more details.


Text-to-speech is a great way to prototype voice applications. It allows you to get moving quickly writing code and testing without waiting for recordings to be available, or having to take the time to make recordings yourself.

  • If Text-to-Speech is going to be a requirement for production, identify this as early in the development process as possible. You will need to consider licensing for most TTS engines, the cost for which is in part driven by the number of concurrent channels you need.

  • TTS engine quality also varies significantly from vendor to vendor. Set aside time to experiment with different engines and voices, especially if you want advanced features like SSML integration.