Tropo just recently partnered with PamFax to deliver faxing capabilities via an API.  Jason Goecke wrapped their API with a very simple Ruby gem called pamfaxr available at GitHub and installable using a “gem install pamfaxr” from your command line.  Using the PamFaxr Ruby gem, I will demonstrate how to send a simple fax as well as how to build a Tropo Voice to Fax transcription application using our Scripting API!

Getting Started

Before you can start sending faxes, you need to head over to the PamFax site and sign up for a PamFax account. After you fill out and submit the form, you’ll get an email with your login credentials and how to get started.

You also need to install the Ruby gem called pamfaxr on to the system where you are going to run the application that will send the fax. The Ruby gem is available at GitHub and should install simply by typing “gem install pamfaxr” from your command line. You will need to edit the code to have your PamFax username and password.

Sending A Fax From The Command Line

Before we involve Tropo, here is the Ruby/Sinatra code for simply sending a fax from the command line using the PamFaxr gem:

require 'rubygems'
require 'pamfaxr'

# Pass user name and password
pamfaxr = PamFaxr.new :username => 'your_username',
                      :password => 'secret'

# Create a new FaxJob
faxjob = pamfaxr.create_fax_job

# Add the cover sheet
covers = pamfaxr.list_available_covers
pamfaxr.set_cover(covers['Covers']['content'][1]['id'], 'Chris was here 2!')

# Add files
# pamfaxr.add_remote_file('https://s3.amazonaws.com/pamfax-test/R-intro.pdf')
# pamfaxr.add_file('examples/R-intro.pdf')

# Add a recipient
pamfaxr.add_recipient('+14802191300')

# Loop until the fax is ready to send
loop do
  fax_state = pamfaxr.get_state
  break if fax_state['FaxContainer']['state'] == 'ready_to_send'
  sleep 5
end

# Send the fax
pamfaxr.send_fax

Just copy that code into a text file, edit it to have your information in it and then run it with ruby from your command line. In a short bit you should have a fax waiting for you.

Sending Faxes From Tropo

Now for the fun Tropo Voice to Fax application code! The first code snippet is written in Ruby runs on the Tropo cloud. It greets the caller, asks for your fax number, records your voice/fax message and sends the transcription via a callback to the Ruby/Sinatra application that sends the actual fax.  Here’s the Tropo code:

say "Welcome to the Tropo fax demo.", :voice => 'dave'

result = ask "What's your fax number? Please include your country code.", {
   :choices => "[11 DIGITS]", :voice => 'dave'}

record "Please say what you would like for me to fax.", {
    :beep => false,
    :voice => 'dave',
    :maxTIme => 60,
    :silenceTimeout  => 2,
    :transcriptionOutURI => "http://web1.tunnlr.com:11053/transcribe?fax=" + result.value
    }

say "Your voice is being converted to a facsimily!  Go check your fax machine!  Goodbye.", :voice => 'dave'

hangup

Here is the complimentary Ruby/Sinatra code that catches the Tropo transcription callback and sends the fax of the transcription to the number specified in the Tropo script using the PamFaxr gem as demonstrated above. This code needs to be run on a publicly-accessible web server to which Tropo can connect and send the data. You have several options including:

• Running the code on your own publicly-available webserver
• Running the code on a hosting service like Heroku
• Running the code on your local machine and use a service like Tunnlr to make the service available

Once you have the Ruby/Sinatra code below running in one of those locations, you’ll just update the Tropo code above with the correct URL (on line 11).

The code is here:

require "rubygems"
require "sinatra"
require 'json'
require 'pamfaxr'

pamfaxr = PamFaxr.new :username => 'your_username',
                      :password => 'secret'

post "/transcribe" do

  transcript_json = JSON.parse(request.body.read)
  identifier = transcript_json['result']['identifier']
  transcript = transcript_json['result']['transcription']

  # Create a new FaxJob
  faxjob = pamfaxr.create_fax_job

  # Add the cover sheet
  covers = pamfaxr.list_available_covers
  pamfaxr.set_cover(covers['Covers']['content'][1]['id'], transcript)

  # Add a recipient
  pamfaxr.add_recipient('+' + params[:fax])

  # Loop until the fax is ready to send
  loop do
    fax_state = pamfaxr.get_state
    break if fax_state['FaxContainer']['state'] == 'ready_to_send'
    sleep 5
  end

  # Send the fax
  pamfaxr.send_fax

end

Wow, that was fun!  I hope that you enjoyed this demonstration and I hope that you find both our PamFaxr gem and our Tropo Scripting API useful and powerful.