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.
