TelAPI Blog

At TelAPI, we're working around the clock to become the best telephony API available. As part of that effort, we are pleased to say we now offer faxing capability on all of our phone numbers! Since it's a brand new feature, it'll be considered as an open beta test for a now, so we look forward to hearing any feedback from you.

To accept an incoming fax, just go to the phone number management page of your TelAPI dashboard, pick the number you want to receive faxes on and set the Fax URL to the web page you want to be requested when the fax comes in. We'll POST two params called OriginalURL and ProcessedURL which will be URLs to a TIFF file and a PDF of the fax that was received.

Instead of dedicating your numbers to just faxing, we've added automatic fax detection. This means you can continue using the same number for voice calls. The way this works is TelAPI will fetch the voice URL set on your number just like it would for a normal voice call, but if fax tones are detected, it will stop executing your InboundXML and begin receiving the facsimile.

Sending a fax is dead simple. Just POST an HTTP request with the parameters From, To and Url to https://api.telapi.com/v1/Accounts/{AccountSid}/Faxes and we'll take care of the rest. As with the rest of our REST calls, just use BASIC authentication where your username is your account SID and the password is your API token. Set the "From" parameter to the TelAPI number you want the fax to come from. "To" is obviously the destination number. "Url" is the web address of the image you want to send. We support many formats, including PDF. See the details at http://www.telapi.com/docs/api/rest/faxes/send/.

A curl request to send a fax might look like this:

Stick around, our next blog post will show how to make your own faxing iOS app!

In Part 1 of this two part blog post, we walked through how to lay the foundation for an SMS subscription service. With just a few lines of code using TelAPI's Ruby helper library, users can now 'subscribe' or 'unsubscribe' in order to be added to or removed from our database.

The next question we have to ask ourselves is, what kind of content would we like to share with our subscribers and how often would we like to send it to them? First, we'll create a Messages class that can be used to instantiate messages which can be sent to our users. Then we'll use a Heroku scheduled task to send out daily messages to our subscribers regarding upcoming deals our company is offering.

As we did for our User's class in Part 1, we'll once again use scaffolding to generate a Messages model, Messages controller and a Messages view. Messages will have names (string), dates (string) and content (text). The 'name' attribute will be used to uniquely distinguish each message. The 'date' attribute will be used to determine when a particular message should be sent to subscribers. Lastly, the 'content' attribute will be what is sent in the body of our text messages. Let's go ahead and generate our Messages class:

$ rails generate scaffold Message name:string date:string content:text

As we did before upon creating our User class, this will also require a database migration.

$ heroku rake db:migrate

Let's then open our application and create a few samples messages (like the one below) associated with deals our business is offering on certain days.

Take note of the date in our Messages class. Ultimately the date attribute will be used to determine if our SMS messages should be sent. I'll elaborate more on this shortly. Also, you'll notice that the date attribute is in UTC format. This is the date/time format Heroku uses. For the sake of this walkthrough, we'll use UTC date/time in an effort to keep things consistent.

Now that we have our sample messages created, we can then configure a scheduled task to run everyday. The scheduled task will be used to check and see if there are any messages with today's date regarding a deal we're offering that should be sent to our subscribers. Since we are already using Heroku, let's go ahead and use their Heroku Scheduler add-on (though a traditional cron job would work just fine).

To use the Heroku Scheduler add-on, it can be installed like so:

$ heroku addons:add scheduler:standard

Once installed, open your application in the Heroku dashboard. You'll notice that your application has a new "Heroku Scheduler Standard" add-on. Click on that to open the scheduled job configuration page. Upon opening it for the first time, you'll notice that currently "You have no scheduled jobs".

Go ahead and click the 'Add Job' link. Then, let's name the job 'send_sms' and execute it as a rake task. We'll run that rake task everyday at 15:00 UTC (10am EST). Hence, your Heroku Scheduler dashboard should look like this:

Now that we have done that, it's time to write the code the rake task will execute everyday at 15:00 UTC. First, we need to create a scheduler.rake file where we can add our 'send_sms' method. The 'send_sms' method will be used to make an HTTP GET request to a new action called 'send_sms_to_subscribers' in our TextsController. To perform the GET request we'll use HTTParty (i.e. a gem we installed during Part 1). Here's what the code looks like:

We will then save scheduler.rake in our "lib/tasks" directory. Also, we have to remember to add a route to "config/routes.rb" to account for our new 'texts/send_sms_to_subscribers' action.

Now it's time to create our new 'send_sms_to_subscribers' action. When our scheduler.rake task makes an HTTP GET request to 'send_sms_to_subscribers', it must check to see if there is a message in our database with today's date. If there is, then it will send an SMS to all of our users with the message's content as the body of the SMS. The following is what the 'send_sms_to_subscribers' action will look like:

Because this action is using TelAPI's REST API to send SMS messages, we must be sure to authenticate with TelAPI using our Account SID and Authentication Token. To do this, let's create an initializer named 'authenticate.rb' and store our TelAPI credentials there. This way, we'll be able to use our credentials throughout the entire application.

Lastly, let's test our 'send_sms' task to make sure everything in 'send_sms_to_subscribers' is working properly. To do this, we will use rake to trigger the task:

$ rake send_sms

In our server logs we should see the successful GET request to 'texts/send_sms_to_subscribers'. As mentioned before, this action uses TelAPI to send out the texts with today's content to all of our subscribers.

And there you have it! We've successfully implemented a fully functioning SMS subscription service with just a few lines of code. Now your business is well-positioned to take advantage of a rich new medium to engage your customers.

If you have an questions regarding this blog post, please reach out to TelAPI's developer evangelist, Doug Crescenzi. He'll be sure to help you with them!

Looking for a new way to engage your customers? Why not give an SMS subscription service a try? In recent months, more and more businesses have begun using SMS subscription services than ever before. Why you ask? Well, there's a few reasons.

First, SMS subscription services facilitate a direct line of communication to your customers. Instead of having them seek information out, your company can use SMS subscriptions to deliver information straight to them. Second, SMS subscription services establish a frictionless user experience. That is to say, they require little to no effort on the user's end to effectively utilize the service. Third, SMS subscription services work as informative reminders. In other words, customers can use them to receive the information they need, when they need it.

As a result of their effectiveness, members of our developer community have inquired about how to build these SMS subscription services. Fortunately, they're incredibly easy to build with TelAPI!

The following two-part blog post demonstrates how a simple SMS subscription service can be built with Ruby on Rails and TelAPI's Ruby helper library. Part 1 walks through the process of building an application with TelAPI that can be used to process incoming SMS messages and create/delete subscribers. Part 2 will explain how scheduled tasks can be used to generate requests to TelAPI's REST API in order to send SMS messages to all of your service's subscribers.

OK, so first things first. Go ahead and create a new Ruby on Rails application.

$ rails new sms-subscription

Upon doing so, open up your Gemfile and add the following gems to it:

Then go ahead and perform a 'bundle install' to ensure all dependencies from the Gemfile will be available in the application.

$ bundle install

Next, let's go ahead and create a 'Texts' controller with a 'subscribe' method that will be used to process incoming SMS subscriptions.

$ rails generate controller Texts subscribe

After our controller has been generated, let's go ahead and assign our TelAPI number to a variable in the 'subscribe' method. Also, while we are at it, let's assign numbers from incoming SMS messages to the 'from_number' variable. That way, when our TelAPI number receives an inbound SMS message, the phone number the message came from will be assigned to a variable. In addition, we'll assign the body of the incoming SMS message to a variable as well.

Next,  create an if statement to handle incoming user subscriptions. In the case that a user texts "Subscribe" (or "Unsubscribe") in the body of a text message, we want to be sure our service recognizes the request and handles it appropriately. We also want to account for incoming messages in which the text's body is neither "Subscribe" or "Unsubscribe". The following if/else statement addresses this:

Once we have ported our code over to our hosting solution of choice (in this example, Heroku), we must then configure our TelAPI SMS Request URL to retrieve and execute our code above. This can be done through the TelAPI 'Manage Numbers' dashboard.

Now that we have our SMS Request URL configured properly, it's time to address how to store users in our database. First, we'll use scaffolding to generate a User model, User controller and all corresponding User views. Our User class will have only one attribute: number (i.e. the phone number a User subscribes from).

$ rails generate scaffold User number:string

Don't forget, we need to perform a database migration to alter our existing database and add the new User table to it.

$ heroku rake db:migrate

Now that we have a User class and a Users table in our database, we can then create instances of User when our service receives text messages with "Subscribe" in the body. To do this, we must include the following code after our initial if statement:

Next, we must account for individuals that would like to unsubscribe from our service. To do this, we must add the following line of code after our elsif statement:

Therefore, the code from the entire TextsController looks a little something like this:

Now, we have a working SMS subscription service in which users can 'subscribe' and 'unsubscribe' in order to be added to or removed from our database.

As you can see, creating the initial subscription component of this service was done very easily with TelAPI. In part 2 of this blog post, we will learn how to use a scheduled process to make requests to TelAPI's REST API and send outbound SMS messages to all of our subscribers.

If you have an questions regarding this blog post, please reach out to TelAPI's developer evangelist, Doug Crescenzi. He'll be sure to help you with them!

Using TelAPI to create applications that interact with the telephone network is simple. Dead simple. Despite its simplicity, TelAPI is a powerful tool with a range of practical uses for startups. The best way for us to prove this, is by giving you sample code and example apps to backup our claim and get you on your way to setting up your first TelAPI application.

We've tried to make this post as simple as possible, by doing a few examples just in XML, but we've also taken the time to create other examples in PHP, Python, and Ruby. (Note: The PHP, Python, and Ruby examples utilize our TelAPI helper libraries for that language)

When you sign up for TelAPI, you'll also receive $25 in free credit to test these uses — enough to get you 2500 SMS, 2500 voice minutes, or a US phone number for 25 months!

Entrepreneurs and small business owners want their customers and clients to have access to them at all times, but they don't always want to give out or publicize their direct personal phone numbers. To solve this problem, TelAPI phone numbers can be used to receive calls and forward those calls to another number — anywhere in the world. The best part is, this can be done very easily, with just a few lines of XML.

It gets even easier though! If you use TelAPI's InboundXML Editor, we'll host the XML code for you, so you don't even need a web server or your own hosting to get this up and running. 

<!-- Ensure the "Voice Request URL" for your TelAPI number points to wherever this XML document is hosted -->

<!-- An InboundXML document is made up of various XML elements nested in the response element -->
<Response>
<!-- The <Dial> element starts an outgoing call. Replace this number with the number of the phone you would like to receive the call -->
    <Dial>15555555555</Dial>
</Response>

There are countless cases where businesses may need to quickly setup conference calls for impromptu meetings. This is typically costly and/or burdensome, and in many cases inconveniences employees. No one actually likes conferencing services that give out a dial-in number plus another 10 digit room number to dial. It's almost impossible to use a conference room setup like this if the dial-in number is in an email on your smartphone and you don't have a pen handy! With TelAPI, businesses can easily instantiate one, consistent conference call number to share with participants.

<Response>
    <Dial>
        <Conference startConferenceOnEnter="true" maxParticipants="10">
            Conference Call Example Room
        </Conference>
    </Dial>
</Response>

Recording incoming calls and having those conversations transcribed to easily readable and searchable text is extremely valuable. Many businesses and individuals are doing this these days, as a means to capture important information and reference it at a later date. Accomplishing this with TelAPI can be done very easily in just 2 steps. The first step simply involves crafting an inbound XML document that receives the incoming phone call on a TelAPI number and records the conversation. The second step is receiving the resulting transcription in a callback script.

To show you an example of this, we've broken the code down into the two necessary files. You'll notice that part 2, which is the callback script, simply receives the transcription and echos it. However, you could easily expand upon this example. For instance, the transcription could be emailed to participants on the call, stored in a searchable database or even shaved via SMS. The possibilites are endless.

<?php
// Save the following file as start_recording.php

require_once('library/TelApi/InboundXML.php');

$inbound_xml = new TelApi_InboundXML();

// Use 'Say' element to acknowledge that the call is being recorded

$inbound_xml->say('The following call is being recorded.');

// Use 'Record' element to record the call

$inbound_xml->record(array(
    'action' => 'http://yourdomain.com/record-my-call-action-example',
    'method' => 'POST',
    'playBeep' => 'true',
    'timeout' => '30',
    'transcribe' => 'true',
    // URL where the transcription text is sent for further processing
   'transcribeCallback' => 'http://yourdomain.com/transcribe_call.php'
));

echo $inbound_xml;

# Save the following as start_recording.py

from flask import Flask
from telapi import inboundxml

app = Flask(__name__)

@app.route("/start_recording")
def start_recording():
    print "RECORDING STARTED"

    return "%s" % inboundxml.Response(
        inboundxml.Say(
            # Let user know that the following call is being recorded
            'The following call is being recroded' % (caller_name)
        ),
        inboundxml.Record(
            action = 'http://yourdomain.com/record-my-call-action-example',
            method      = 'POST',
            finishOnKey = '#',
            transribe = 'true',
            transcribeCallback = 'http://yourdomain.com/records/transcribe_call'
        )
    )

if __name__ == "__main__":
    app.run()

class RecordsController < ApplicationController   def record_incoming_calls     xml = Telapi::InboundXml.new do       # Let user know that the following call is being recorded       Say('The following call is being recorded.', :voice => 'man')
      Record(
        # In this example, this channel is being used for debugging HTTP requests
           :action => 'http://yourdomain.com/record-my-call-action-example',
           :method => 'POST',
           :playBeep => 'true',
           :timeout => '30',
           :transcribe => 'true',
           # This is the URL where the transcription is sent for further processing
           :transcribeCallback => 'http://blog-post.herokuapp.com/records/transcribe_call',
           :finishOnKey => '#')
    end

    respond_to do |format|
      format.xml { render :xml => xml.response }
    end

  end

<?php
// Save the following file as transcribe_call.php

// Assign the transcription text to a variable
$transcription = $_GET['TranscriptionText'];

// Output the the transcription text
echo "This is the transcription text: {$transcription}";

# Save the following file as transcribe_call.py

from flask import Flask, flask
from telapi import inboundxml

app = Flask(__name__)

@app.route("/transcribe_call", methods=['GET', 'POST'])
def transcribe_call():
    # Assign the transcription text to a variable
    if request.method == 'POST':
        transcription = request.form.get("TranscriptionText")
    else:
        transcription = request.args.get("TranscriptionText")

    return 'This is the transcription text: %s' % (transcription)

if __name__ == "__main__":
    app.run()

  # Action URL where the transcription is sent
  def transcribe_call

    render :nothing => true

    # Assigning the transcription text to a parameter
    transcription = params["TranscriptionText"]

    # Outputting the transcription text
    puts = "The following is the text from the transcription."
    puts transcription

  end
end

IVRs are ubiquitous in today's enterprise business environment. Many small and medium sized businesses would undoubtedly find value in having such a system in place, but they may lack the resources or funds necessary to build one. TelAPI changes that. Now any developer can buy a toll free number and build a high quality IVR in minutes.

Below is a sample IVR that offers your callers the option to be transfered to three different departments. From here, you could setup an "ivr-user-response" script on your server to do whatever you'd like for each extension, such as routing the calls to a voicemail box or to another individual's phone.

require_once('library/TelApi/InboundXML.php');

// TelAPI inbound XML document
$inbound_xml = new TelApi_InboundXML();

$gather = $inbound_xml->gather(array(
    // URL where the gathered digits will be sent
    'action' => 'http://yourdomain.com/ivr-user-response.php',
    // HTTP method used to request the action URL
    'method' => 'GET',
    // The maximum number of digits that will be gathered
    'numDigits' => 1,
    // The key a caller can press to finish the gather
    'finishOnKey' => '#',
    // The number of seconds Gather will wait for user input
    'timeout' => '10'
));

// Gather is used to obtain the digits callers submit
$gather -> say('If you would like to reach sales, press 1')
           say('If you would like to reach accounting, press 2.')
           say('If you would like to reach legal, press 3.');

echo $inbound_xml;

from flask import Flask
from somewhere import ivr

app = Flask(__name__)

@app.route('/ivr/intro')
def ivr_intro():
    response = ivr.Gather(
        Say('If you would like to reach sales, press 1.'),
        Say('If you would like to reach accounting, press 2.'),
        Say('If you would like to reach legal, press 3.'),

        action = 'http://yourdomain.com/ivr-user-response.py',
        method = 'GET',
        numDigits = 1,
        finishOnKey = '#',
        timeout = '10'
    )

    return "%s" % response

if __name__ == '__main__':
    app.run(debug=True)

def ivr
xml = Telapi::InboundXml.new do
  # Gather is used to obtain the digits callers submit
  Gather(
  # URL where the gathered digits will be sent
  :action => "http://yourdomain.com/ivr-user-response.rb",
  # HTTP method used to request the action URL
  :method => "GET",
  # The maximum number of digits that will be gathered
  :numDigits => "1",
  # The key a caller can press to finish the gather
  :finishOnKey => "#",
  # The number of seconds Gather should wait for the user input
  :timeout => "10")
  {
    Say("If you would like to reach sales, press 1.")
    Say("If you would like to reach accounting, press 2.")
    Say("If you would like to reach legal, press 3.")
  }
end

# Ruby code used to generate an XML response
  respond_to do |format|
    format.xml { render :xml => xml.response }
  end
end

There are many instances in which businesses could benefit from providing an SMS reminder service to their customers or clients. For instance, if a doctor has a client with an appointment scheduled for tomorrow afternoon, his office could send that client an SMS reminder so they won't forget about their appointment. Practical and useful!

require_once 'library/TelApi.php';

// Always use singleton design pattern
$telapi = TelApi::getInstance();

// Set TelAPI credentials
$telapi -> setOptions(array(
    'account_sid' => 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'auth_token'  => 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
));

$dateToRemind = 'DESIRED DATE HERE';

if ($dateToRemind == date('Y-m-d'))
  {
    $sms_message = $telapi->create('sms_messages', array(
    // Make sure the 'From" number is one of your TelAPI DIDs
    'From' => '5555555555',
    'To' => '5555555555',
    'Body' => 'This is a reminder of your upcoming appointment.'
    ));
  }
else
  {
  echo "It's not time to remind them yet.";
  }

from telapi import rest
from datetime import datetime

account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
auth_token  = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
client      = rest.Client(account_sid, auth_token)
account     = client.accounts[client.account_sid]

if dateToRemind == datetime.now():
    sms_message = account.sms_messages.create(
        # Make sure the 'From" number is one of your TelAPI DIDs
        from_number='5555555555'
        to_number='5555555555'
        body='This is a reminder of your upcoming appointment.'
    )
else:
    print "It's not time to remind them yet."

def reminder  

    require 'telapi'

    Telapi.config do |config|
        config.account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
        config.auth_token  = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
    end

    if dateToRemind == Time.now
    # Send SMS via TelAPI's REST API
    # Make sure the 'From" number is one of your TelAPI DIDs
        Telapi::Message.create(number_to_send_to,
                               number_to_send_from,
        'This is a reminder of your upcoming appointment.' )
    else
        puts "It's not time to remind them yet."
    end
end

Many companies these days prefer using SMS over email to send out personalized offers or information to their customers. But are you sure the numbers in your list are valid mobile numbers? Have you thought about checking the numbers before they get added to your lists? For these types of campaigns, it's important for a company to verify their lists only contain mobile numbers capable of receiving SMS. TelAPI's Carrier Lookup endpoint and its 'IsMobile' property can do just that.

require_once 'library/TelApi.php';

// Always use singleton design pattern
$telapi = TelApi::getInstance();

// Set TelAPI credentials
$telapi -> setOptions(array(
    'account_sid' => 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'auth_token'  => 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
));

// Make a request to TelAPI's Carrier Lookup
$carrier_resource = $telapi->get('carrier', array(
 'PhoneNumber' => '15555555555'
));

// Assign the IsMobile boolean value to the is_mobile variable
$is_mobile = $_GET['IsMobile'];

if($is_mobile == "True")
{
   echo "This number is a mobile number. SMS enabled.";
}
else
{
   echo "This number is not a mobile number. Not SMS enabled.";
}

from flask import Flask, request
from telapi import rest

account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
auth_token  = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
client      = rest.Client(account_sid, auth_token)
account     = client.accounts[client.account_sid]

@app.route('/call/check-mobile')
def check_mobile():
    # Make a call to TelAPI's REST endpoint for Carrier Lookups
    carrier_details  = account.carrier.create(
        'phone_number' = '5555555555'
    ) 

    # Assign the IsMobile request param to the is_mobile variable
    is_mobile = request.args.get("IsMobile")

    if is_mobile == "True":
        print "This number is a mobile number. SMS enabled."
    else:
        print "This number is not a mobile number. Not SMS enabled."

require 'telapi'

  Telapi.config do |config|
    config.account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
    config.auth_token  = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
  end

  # Make a request to TelAPI's Carrier Lookup
  Telapi::Carrier.lookup(phone_number)

  # Assign the IsMobile boolean value to the is_mobile variable
  is_mobile = params["IsMobile"]

  if is_mobile == "True"
    puts "This number is a mobile number. SMS enabled."
  else
    puts "This number is not a mobile number. Not SMS enabled."
  end
end

To offer the best service possible, many businesses find it advantageous to offer personal greetings to incoming callers. This can easily be implemented by obtaining the 'CallerName' attribute in the request parameters.

require_once('library/TelApi/InboundXML.php');

// TelAPI inbound XML document
$inbound_xml = new TelApi_InboundXML();

// Assign the CallerName request param to the caller_name variable
$caller_name = $_GET['CallerName'];

$inbound_xml->say(
    // Greet the incoming caller with their name
    "Hello {$caller_name}! Thanks for calling in!", array('voice' => 'man')
);

echo $inbound_xml;

from flask import Flask
from telapi import inboundxml

app = Flask(__name__)

@app.route('/caller/intro')
def ivr_intro():
    # Assign the CallerName request param to the caller_name variable
    caller_name = request.args.get("CallerName")

    return '%s' % inboundxml.Response(
        inboundxml.Say(
            # Greet the incoming caller with their name
            'Hello %s! Thanks for calling in!' % (caller_name)
        ))

if __name__ == '__main__':
    app.run(debug=True)

def greeting

    # Assign the CallerName request param to the caller_name
    caller_name = params["CallerName"]

    # Generate XML response
    xml = Telapi::InboundXml.new do
      # Greet the incoming caller with their name
      Say("Hello #{caller_name}!", :voice => "man")
      Say("Thanks for calling in!", :voice => "man")
    end

    respond_to do |format|
      format.xml { render :xml => xml.response }
    end

end

Businesses can find added value in using call screening software to determine who incoming calls are coming from. For instance, if an important client is trying to get through, they likely don't want to miss that call. However, if it is a telemarketer or something else that is inconsequential, a business's employees would likely prefer to ignore those callers. With TelAPI, building call screening software can be done very easily. This, of course, is just one simple example, but could be expanded upon to create a more comprehensive system.

require_once('library/TelApi/InboundXML.php');

$inbound_xml = new TelApi_InboundXML();

// A banned number assigned to a variable
$banned_number = "+18005551234";

// Assign the CallerName request param to the caller_name
$call_from = $_GET['From'];

//Assign the CallerName request variable to caller_name
$caller_name = $_GET['CallerName'];

// If the number comes from a banned number, then reject it
if($call_from == $banned_number)
{
    $inbound_xml->reject(array( 'reason' => 'rejected' ));
}
// If number is not banned, answer call and greet caller
else
{
    $inbound_xml->say(
    'Hello $caller_name!
    Thanks for calling in!', array('voice' => 'man'));
}

echo $inbound_xml;

from flask import Flask, request
from telapi import inboundxml

@app.route('/call/intro')
def call_intro():
    # A banned number assigned to a variable
    banned_number = "+18005551234"

    # Assign the number of the incoming call to a variable
    call_from = request.args.get("From")

    # Assign the name registered to the incoming caller to a variable
    caller_name = request.args.get("CallerName")

    # If the number comes from a banned number, then reject it
    if call_from = banned_number:
        return '%s' % inboundxml.Response(
              inboundxml.Reject(reason = 'rejected')
        )
    else:
    # If the number is not banned, answer the call and greet the caller
        return '%s' % inboundxml.Response(
            inboundxml.Say(
            # Greet the incoming caller with their name
            'Hello %s, Thanks for calling in!' % (caller_name)
        ))

def screening

# A banned number assigned to a variable
    banned_number = "+18005551234"
# Assign the number of the incoming call to a variable
    call_from = params["From"]
# Assign the name registered to the incoming caller to a variable
    caller_name = params["CallerName"]

# If the number comes from a banned number, then reject it
    if call_from == banned_number
      xml = Telapi::InboundXml.new do
        Reject(:reason => "rejected")
      end
    else
# If the number is not banned, answer and greet the caller
      xml = Telapi::InboundXml.new do
        Say("Hello #{caller_name}. Thanks for calling in.")
      end
    end
# Ruby used to generate an XML response
    respond_to do |format|
      format.xml { render :xml => xml.response }
    end
  end

Take away: These are just a few of many potential business uses that can be implemented with TelAPI using very little code. Ultimately, TelAPI enables developers of all skill levels to seamlessly build a wide-range of powerful telephony applications.

If you have any follow-up questions concerning the examples above, please reach out to Doug Crescenzi, TelAPI's developer evangelist.

Do you sometimes find yourself looking to escape from awkward conversations? What about times when you're out and about, and you want to show your friends and family how popular you are? If these types of questions resonate with you, then you should definitely check out Blow Up My Phone.

Jonas Meyer's Blow Up My Phone allows users to schedule incoming calls and text messages to their phones as a way to escape from those awkward moments we all know too well. For incoming calls, Jonas is using custom caller IDs which allow his users to make incoming calls come from any number they'd like. "Oh look, my mother's calling. I gotta run!" As Jonas puts it, "It allows a simple phone call or text message to be used as a social tool providing the user credible ‘social currency’ in real time."

Jonas was inspired to build the application after a friend had asked him to call him while he was out on a date. His friend told him that it was a precautionary measure in case the date was going poorly. Not only that, if his date were to see that his phone was blowing up she would "assume that he was popular or important". As far as Jonas's friend was concerned, the fake incoming call was a win/win on both fronts in the context of a potentially awkward date.

Blow Up My Phone was built in PHP via the WordPress CMS. Jonas used scripted shortcodes in order to interface with TelAPI and make phone calls, send text messages and use custom caller IDs. Jonas noted that without the freedom to use unrestricted custom caller IDs, he wouldn't have been able to build such an innovative telephony application.

Next, Jonas intends to create call recordings in other languages and make Blow Up My Phone an international application. He also plans to leverage TelAPI's InboundXML editor as a more convenient way to host and modify his TelAPI XML documents on the fly.

Blow Up My Phone is fresh out of beta and its subscriber-base is growing at a rapid pace. Jonas is super excited about it and we are too. You should definitely check it out!

Learn More About Jonas Meyer

Jonas is a Sarasota, FL based developer/hacker and creator of Blow Up My Phone.  At the moment computers are only a hobby as he’s currently pursuing a BS in Finance. While not in school, Jonas enjoys spending time with his son, building fun telephony web applications and entertaining world changing ideas.  You can contact Jonas on twitter @blowupmyphone or via email at jonas@blowupmyphone.com.

If you're a developer that has built an innovative application using TelAPI, we would love to hear from you! Please reach out to TelAPI's Developer Evangelist Doug Crescenzi to see how we might be able to help you promote your application.

This past Saturday, TelAPI hosted our very first hackathon, held in New York City, with our good friends at Rain. The hackathon's focus centered on using telephony to create tools for emergency preparedness and response, something which was still fresh on everyone's mind after the recent Hurricane Sandy tragedy. Twenty-five developers came together, and over the span of a 12 hour period, built some incredible applications with immense utility. Here's a brief overview on some of the tools built at the hackathon:

• POD (winner) - POD (i.e. Power Outage Detector) is a hardware component anyone can plug into their power outlet (and keep plugged in) to determine when the power goes out. When POD detects a power outage, it uses TelAPI to send a text messages to the owner and also calls their utility company to automatically report a power outage (it even uses the owners own phone number as the Caller ID). In addition, POD records every time your power goes out and for how long, which you can see via the web.

• HomeBase (2nd place) - HomeBase offers hyper-local messaging services to apartments and office buildings. First, it enables any user to create a profile for their apartment or office building through SMS. Once a building's profile is setup, residents or employees can easily join and use HomeBase to send messages to other individuals associated with the profile or broadcast messages to all members using SMS. HomeBase is a great tool for sharing resources and perfect for disseminating information when individuals are away from their residence or offices.

• Hugo Helps - Hugo Helps is a service allowing users to simply text an address to a TelAPI number and determine if power is available. In the case that power is not available, Hugo responds with the addresses of nearby hotels that have power.

• Sprout Help - Sprout Help is an application with SMS, web and Twitter interfaces that uses geolocation to match people in need with people ready to help. Sprout Help creates direct relationships to expedite various aid offerings. Instead of proxying resources through intermediaries, Sprout Help aims to ensure resources are allocated effectively and with agility.

• SafetyNet - SafetyNet is a tool that enables users to quickly broadcast information to emergency contacts using SMS when it matters most. SafetyNet offers three different emergency levels to ensure individuals are able to share critical status information with close friends and family, as well as being able to connect with emergency services in a time of need.

If you would like to learn more about these projects and upcoming TelAPI hackathons, please reach out to Doug Crescenzi, TelAPI's developer evangelist. 

Today, we are really excited to announce our first ever TelAPI hackathon! This will be an awesome opportunity to bring together NYC's finest, sling some code and build a bunch of really cool telephony applications.

The hackathon is right around the corner (November 10th). Our good friends at Rain are co-sponsoring the event with us, and have been kind enough to offer up their office space and host. It's going to be a lot of fun! Here's the rest of the details:

Who: TelAPI, Rain Agency and the greater NYC developer community

Cost: FREE!

What: Telephony API Hackathon in conjunction with the Node.js Knockout. TelAPI and the Rain Agency are co-sponsoring this event as an opportunity to bring together the NYC developer community and write some serious code. Developers of all kinds are welcome, though unfortunately we are limited to 30 available spots. For you developers that would like to attend, you must RSVP via the Hacker League page.

Where:
Rain Agency
207 West 25th Street, Suite 507
New York, NY 10001

Why: We love to build cool telephony applications that leverage voice and SMS!

When: Saturday November 10th, 2012

First Place Prizes: 
Two iPad Minis - 16GB Wi-Fi models
$250 free TelAPI credits for each team member
TelAPI hoodie for each member of the winning team

Second Place Prizes:
$100 free TelAPI credits for each member of the winning team

Free Swag:
TelAPI T-Shirts and TelAPI Stickers

Schedule:
10:30am - Meet and Greet
11:00am - Idea pitching and team formation
11:30am - Hacking begins
10:30pm - Hacking ends, pitches and demos begin
11:15pm - Award the winners
11:30pm - Grab celebratory beers at a bar around the corner

Other Details:
Red Bull, Beer, Water, Soda will be provided
Snacks will be provided
Lunch will be provided
Dinner will be provided

If you have any questions please reach out to Doug Crescenzi, TelAPI's Developer Evangelist.

So you’re a current Twilio developer, but you’re considering transitioning to TelAPI and taking advantage of some of the added functionality TelAPI has to offer. Awesome! Fortunately, it is easy to seamlessly transition from Twilio to TelAPI. That's because leveraging TelAPI's InboundXML elements is no different than Twilio's TwiML attributes, and as you'll see from the example below, our REST calls are nearly identical as well:

Twilio REST API: Making calls:

https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls

TelAPI REST API: Making calls:

https://api.telapi.com/v1/Accounts/{AccountSid}/Calls

Let's walk through the scenario below to demonstrate how easy it is to transition from Twilio to TelAPI, and leverage the customizable caller ID feature. Unlike Twilio, TelAPI allows developers to use the custom caller ID feature without inconveniently requiring developers to verify a particular number.

Problem: Let's say your business uses an existing Twilio application built with Ruby on Rails. The intent of the application is to call your clients and remind them of an upcoming appointment. Unfortunately, there are many instances in which your clients do not answer their phones. This is because they do not recognize the Twilio number from which they are receiving the calls. Additionally, your developers want the autonomy to customize caller ID features at their own discretion, not Twilio's.

Solution: TelAPI can solve this problem. TelAPI allows developers to customize outbound Caller IDs without requiring verification. In the case of your client reminder application, using TelAPI, you can customize the outbound Caller ID to be that of your office's phone number. That way your clients will recognize the number from which the calls appear to be coming from. This should ultimately increase the likelihood that they will answer their phones.

Here's what our existing code looks like using Twilio:

Here's the XML that resides at the URL that's requested when the call connects:

Alright, so first things first. You can go to the TelAPI Sign Up page and create an account. This involves providing your first name, last name, email address and creating an account password. Unlike Twilio, during the account creation process, TelAPI does not require your phone number for verification. This is done out of respect for customer privacy. Once you have your TelAPI account set up, you need to install the TelAPI Ruby gem. The TelAPI Ruby gem functions nearly identically to the way Twilio's Ruby gem does. To install our Ruby gem, you simply open your Rails Gemfile and add:

Then you can execute:

$ bundle install

Upon installing the TelAPI Ruby gem, you can replace your Twilio 'account_sid' and 'auth_token' with your TelAPI 'account_sid' and 'auth_token'. To do this, you'll need to use a Rails initializer. Let's create an initializer named 'authenticate.rb' and store your TelAPI credentials there. That way you can use your credentials throughout the entire application:

After you have configured your initializer, you can then replace the code in your calls_controller like so:

As you can see, we have replaced the Twilio number with your office's number. That way your clients will recognize the number that displays on their Caller ID when your application initiates a call to them.

That's all it takes! You've now successfully transitioned to TelAPI from Twilio and leveraged a practical telecommunications feature that Twilio inconveniently limits.

Take away: Transitioning from Twilio to TelAPI can be done seamlessly. Upon transitioning, developers have the autonomy to leverage common telephony features without having to deal with a burdensome intermediary. In doing so, we hope to promote developer autonomy and dramatically enhance your existing telephony applications or services.

If you would like to learn more about other features unique to TelAPI, please reach out to our developer evangelist, Doug Crescenzi. He'd love to chat with you!

Today we are extremely excited to bring TelAPI out of private beta and finally offer it to the world. TelAPI began 16 months ago as an effort to build a next-generation cloud-based telephony API to power our own unique business needs. However, upon showing immense potential, we decided to spin TelAPI off into its own product with the intent of offering it as the most fully featured telephony API on the market. To do so, the team has worked exceedingly hard these past few months. We have poured our hearts and souls into this effort, and today we are thrilled to share TelAPI with you.

No longer must developers and entrepreneurs have a deep understanding of telecommunications systems to build applications that leverage voice and SMS. TelAPI’s cloud-based communications platform requires no hardware, no setup and no network administration. That means developers can focus on features, functionality and creating innovative telephony applications. Telephony is complicated, so TelAPI helps make it simple.

So, why did we build TelAPI? We know there are similar products in this space that nobly ”dumb down” telecom and solve 80% of the problem. But what about the remaining 20%? That is to say, the developers who need additional features and functionality and are unable to satisfy the unique requirements they have with existing telephony APIs. That’s who TelAPI caters to — businesses and developers with highly custom voice and SMS requirements.

TelAPI stands apart from other APIs by offering:

• The ability to set your outbound Caller ID to any number
• Reverse carrier lookups on phone numbers
• Flat-rate unlimited inbound calling to your TelAPI phone numbers
• Voice and audio effects on your phone calls
• Private number Caller ID unblocking
• Premium transcriptions with human processed dictation
• Speech recognition
• Account fraud prevention controls to help combat abuse of your applications

We have incorporated all of these features into TelAPI without compromising ease-of-use. Consequently, developers transitioning from Twilio’s platform to TelAPI can do so seamlessly as our REST calls are consistent with theirs.

Ultimately, we’re passionate about helping developers solve problems. To do so, it is our intent to offer TelAPI’s extensive toolkit to developers of all skill-levels using nearly any programming languages they’d like. We've been in the telecommunications space for the better part of a decade now and we get "it". We understand the challenges developers in this domain face and we seek to address them.

We are really proud of what we have accomplished so far in private beta, and look forward to taking the next step with all of you!

About TelAPI

TelAPI is a self-funded startup with 7 employees in NYC, NJ and Miami. Our mission is to bring something new to the cloud communications space by creating compelling features and functionality you won’t find elsewhere. As we transition today from private beta to version 1.0, TelAPI is already processing 1.9 million voice minutes and 875,000 text messages per month, with international support for 16 countries.

Unlike others in this space, we have not raised money from investors. That is a decision we have made because we are proud of our history of successfully bootstrapping our companies and we are primarily concerned with building a superior product while establishing a sustainable business. Our decision making processes center around the best interests of our users and our product, not tripling investment from VCs in three to five years.

For additional information please email us at press@telapi.com and follow @TelAPI on Twitter.

Hi everyone!

I'm the newest member of the TelAPI team, and the first of a soon to be burgeoning TelAPI Developer Evangelist community. Brooklyn is my homebase (as my wife and I have an affinity for hipster culture and good beer) and soon I'll be traveling the country to meet you all. Be warned, we're going to build some seriously kick ass apps together!

You may already know that TelAPI is a platform for developers to build and create awesome voice and SMS applications. Perhaps what's less apparent is the overwhelming passion the team has for providing easy-to-use, affordable, pay-as-you-go telephony services for *all* developers, novices and superstars alike. The TelAPI team has been grinding away, hustling like maniacs and building a stellar product that we're super pumped to finally release to the world!

Building telephony services

I've been playing around with telephony APIs for a few months now, and absolutely love how simple they are. At a hackathon a couple of months ago, my friends and I built a service for beer lovers, called BeerText.Us, that allows beer aficionados to learn about the beers they drink via SMS. Then a couple of weeks later, I built an app with TelAPI to prank my friend (don't worry, he deserved it).

The reality is, I don't know all that much about the underlying/esoteric details of complex telecommunication systems (aside from how messy and convoluted they are). But that doesn't matter anymore! With TelAPI, it's incredibly easy for folks to build nearly any telecommunications app they could ever want.

Excited to hit the ground running

With the release of TelAPI upon us, I can't wait to get out there, meet you all and show you how awesome this service is. TelAPI introduces an opportunity for developers of all skill levels to transcend previous technological boundaries, and coalesce the two most powerful communication mediums humankind has seen in our history — the Internet and telecom.

I couldn't be more excited about joining a super talented team, and working with a passionate developer community that fuels innovation, disrupts contemporary norms and solves complex problems.

Most importantly, I want to ensure your development needs are met with the highest degree of satisfaction. That's why I'm here, to give you a voice and to ensure that it's heard. We want to help you, the innovators and the problems solvers, revolutionize modern day communications.

So, don't hesitate to email me at doug@telapi.com or @dougiebuckets if you have any questions or thoughts you'd like to share!

I look forward to building awesome stuff with you!