TelAPI Blog

Data Mining your Recordings with Keyword Transcriptions

Posted on by devpatel


With our newly announced "keyword" setting in our Transcriptions API, you can get a pulse of what topics and keywords are being mentioned in an Audio URL.

This setting is meant to be used with large duration files and works perfectly for customer service related data mining.

Here is an example CURL request, give it try with your account and start transcribing and get a feel for the keywords are trending on your application!

Simply send the audio URL, a URL where we can post the response to and set the quality to keywords:

curl -X POST 'https://api.telapi.com/v2/Accounts/{AccountSid}/Transcriptions' -u {AccountSid}:{AuthToken}' -d 'AudioUrl={AudioFileUrl}&TranscribeCallback={CallbackUrl}&Quality=keywords'

We return back with the transcribed text, and the respective topics, keywords, and the timestamps in which they appear throughout the audio file.

...
"Keywords": "[\"Pedagogy:Learning:5.84\", \"Pedagogy:Interactivity:3.44:9.29\", \"Pedagogy:Multimedia:4.05\"]",
...

Tell us how you plan on using this feature, @telapi or drop us a line at support@telapi.com with your thoughts!

Posted on by devpatel | Posted in API, transcriptions | Tagged , ,


How TelAPI manages SMS Opt-Outs

Posted on by TelAPI


TelAPI provides a robust SMS API, that allows you to send and/or receive messages to operators around the world.

We allow developers an easy way to launch interactive messaging with their customers by following these two simple steps:

  1. Adding an SMS enabled number to their account
  2. Initiating an API request to TelAPI to trigger a message to be sent to the customer FROM the SMS enabled number.
  3. Managing the inbound message; with InboundXML

Naturally, we want developers to be aware of the value this brings to their applications and spamming them with messages is a sure way to upset them among other things.

TelAPI manages the SMS opt-out on behalf of the developer, subsequently protecting the end recipient customers and the respective developers from erroneous application behavior.

Lets say one of your customers switched their number, and you sent the number a message thinking it belongs to your customer. The new user of the message can reply with either one of these messages: STOP, QUIT or UNSUBSCRIBE to opt-out of future messages that you may initiate from your TelAPI account.

TelAPI will reply back to the customer, with this message: You will no longer receive SMS messages from this number. Reply with SUBSCRIBE, YES or START to undo this request.

When the developer account re-attempts delivery of this message to the opted-out customer, our system will send you an API error:
TelAPI Error: You don't have permission to send SMS to requested destination ( 'TO' ) number. The recipient has requested not to receive messages from your account. - Code 400

The above is captured/gathered under error notifications and are also accessible via the REST so developers can be aware of numbers that have opted out in the past.

All of this allows TelAPI and the developer using us in staying complaint of the guidelines established for messaging by operators, eliminates customer dissatisfaction for developer applications, and allows developers to use SMS as a reliable communication and notification channel with their customers.

Have a specific question about SMS and how it works?

Feel free to get in touch with us at support@telapi.com or sign up for a free trial account and test drive it for yourself.

Posted on by TelAPI | Posted in API, General, SMS | Tagged ,


Changes to Carrier Lookup API

Posted on by TelAPI


Please note that these changes have been made live as of October 1, 2014 3:20 EST

As a result of customer feedback, we are making a few changes to improve our Carrier Lookup API end-point which allows customers to look-up the Carrier/Network of a supplied phone number in the next few weeks.

The pricing for carrier look-ups will not change.

We are making these changes in an effort to improve the look-up detail in returning more refined data across operators for the global phone numbers.

We are updating our international data to be more descriptive: with additional flags for SMS enabled networks and Networks that support actual devices vs. being phone numbers that belong to an OTT provider (over the top/app supported) or MVNO (Mobile Virtual Network Operator).

As a result of this update, you will now be able to identify the MVNO/OTT provider and their supporting network. This will allow you to differentiate which phone numbers belong to services such as Google Voice, Skype, etc., and will provide you with the underlying operator/network, rather than only the underlying operator/network as we have provide you today.

An important change is being made to our existing Carrier IDs, which reflects an internal reference to the network operator. If you have been using the Carrier ID rather than the name of the network to identify the carrier/operator, this change will impact you going forward. You will want to make the change to consume the newly updated list. It is highly recommended that you review your current process and ensure that the updated Carrier ID list is being used going forward. You should download the new list at your earliest for review and implementation.

We made a change of requiring the request to be sent via POST instead of GET, in the past.

Carrier lookup is achieved using the HTTP POST method. The format of the URI used to
make the POST request is below.
POST https://api.telapi.com/v2/Accounts/{AccountSid}/Lookups/Carrier
Kindly make sure this is being used going forward, as this remains the same.

We are hoping to push these changes in the next 1-2 weeks and we know these changes will affect how your application will interpret carrier look-ups so want to make sure you are prepared.

We are here to help you transition to the new update, please let us know if we can help you do so in any manner.

Please note that these changes have been made live as of October 1, 2014 3:20 EST

Posted on by TelAPI | Posted in API | Tagged ,


Transcription Slicing

Posted on by TelAPI


With our newly released feature of transcription slicing, you can request your submitted audio URL to be transcribed to a certain duration.

This new feature allows companies and developers to transcribe a snippet of the submitted audio instead of the entire file.

SliceStart and SliceDuration allow you to pass the requested duration measured in seconds.

This option is available when transcribing an Audio URL: http://www.telapi.com/docs/api/rest/transcriptions/transcribe-audio-url/#SliceStart or any recording: http://www.telapi.com/docs/api/rest/transcriptions/transcribe-recording/#SliceStart

We'd love to hear how you are using our services. It is our goal to help you take advantage of our powerful APIs to build your next VOIP application.

If you have any questions about our transcription service, please don't hesitate to get in touch with us at support@telapi.com

Note: The SliceStart and SliceDuration are only available within the RestFul API, support for these parameters within InboundXML is coming soon!

Posted on by TelAPI | Posted in General


Things to know for Messaging (SMS) with TelAPI

Posted on by TelAPI


TelAPI allows you to send messages around the globe.

We offer interactive messaging with virtual numbers and allow one-way or two-way messaging via in-country short-codes/bulk SMS routes.

Our focus is on deliverability; so we either connect directly with one of the in country operators or a central aggregators that is no more than 1 connection away from the destination operator.

For notifications and time-sensitive messages, it is best to deliver messages via ShortCodes or Bulk 1-Way routes; As these routes provide you with delivery status notifications and update as the message gets delivered, which sometimes can mean: handset delivery confirmation.

Since each country varies on what type of messaging is allowed, it is highly recommend you check our SMS features document, which will provide you insight on what Sender ID (within TelAPI, we call this the FROM address) requirements based on the country you are sending messages to.

Short-Codes and 1-Way International routes provide you with delivery reports; allowing your application to know when your message was delivered to the end-user.

Below are details of the various SMS routes available through TelAPI. Keep these in mind when using our SMS gateway and you will be able to launch your application without any issues.

US-messaging via Virtual Numbers
This is meant to be used for interactive messaging. The virtual numbers are voice-enabled and can also send/receive messaging from other US based operators. This makes these numbers perfect for interactive messaging. You will be able to send messages by setting the FROM to your purchased virtual number (from the TelAPI dashboard) to a destination number. You can also have an auto-response message incase anyone sends a message to your number; by simply editing the InboundXML document and assigning it to the number.. The limit of delivering messages on these numbers is 3 messages per minute; and are not meant to be used for high-throughput marketing campaigns. Messaging via Virtual Numbers does not support delivery confirmations, we simply show you successful hand-off to the destination operator.

If you are creating a two-way messaging service and want to ensure that the end-user get their messages from the same number, be sure to correspond the origination and destination numbers accordingly. We supply each unique message to/from respective networks with a SID (a unique record), which will allow your application to keep track of these messages.

US-messaging via Short Codes
Short-Codes messages can be scaled to meet higher through-put messaging (than with virtual numbers) along with delivery notifications. TelAPI offers shared short-codes and dedicated short-codes to accommodate for short term campaigns.

Within the US, Short-Codes can be leased from the CSCA (http://usshortcodes.com) and provisioned via TelAPI. Although each provider is different, each application will require that you adhere to MMA (Mobile Marketing Association) guidelines and require approval from each operator that the Short-Code will be made available on.

TelAPI can guide you through the provisioning process and manage communications to all operators regarding your use-case and campaign.
International Short Codes are available within TelAPI in the following countries.

  • Brazil
  • New Zealand
  • United Kingdom
    Contact support (at) telapi.com in order to get more details for Short-Codes outside of the US.

2 way messaging with In-Country Local SMS Numbers (Other countries)
TelAPI offers two-way messaging in the following countries, by request. These numbers are not readily available on our dashboard until we have ensured the use-case is approved by the in-country operators. These numbers are only enabled for SMS inbound messaging. Our users utilize 1-way messaging (mentioned below) and numeric sender IDs, to create a two-way messaging experience for the end-user.

  • Austria
  • Australia
  • Canada
  • Czech Republic
  • Finland
  • Hong Kong
  • Hungary
  • India
  • Ireland
  • Lithuania
  • Netherlands
  • Norway
  • Poland
  • Spain
  • Sweden
  • Switzerland
  • United Kingdom

Upcoming Countries for SMS only number:

  • Belgium
  • China
  • Denmark
  • France
  • Germany
  • Portugal
  • Russia
  • Singapore
  • South Africa
Also, please note: International Short Codes are available in:
  • Brazil
  • New Zealand
  • United Kingdom

1 way messaging, Other countries
One-way messaging is available in 180 countries. TelAPI offers delivery confirmation that are posted on your SMS callback URL; allowing you to measure the time the message was delivered. For this method of submitting messages you have the flexibility to set your FROM address to an alpha/numeric character for upto 15 characters. Again, this depends on the country you are sending the message to; but a quick review of this list of SMS features will help you get a better insight on the sender ID options and allowing you to send SMS messages through TelAPI.

Documentation for our API can be found here.

If you have any questions regarding SMS, feel free to reach dev (at) telapi.com, anytime!

Posted on by TelAPI | Posted in General | Tagged , , , , , ,


Carrier Lookups API

Posted on by TelAPI


At TelAPI, we strive to deliver the most robust telephony platform on the market, allowing developers to mix-and-match our API to deliver complete enterprise solutions.

Our new Carrier Lookup API allows you to perform a real-time carrier/provider lookup on any phone number (mobile/landline). We aggregate this data from in-country local number portability as well as line-range databases maintained by country specific number registry providers. The carrier lookup API provides accurate and real-time information so you can act on it by delivering targeted services and marketing to your end-users.

Below is an example of the data you can expect when sending a carrier lookup request to TelAPI.

The response.

A complete list of covered operators and their respective Carrier IDs can be found on an excel sheet Here.

You can read the full the API docs at http://www.telapi.com/docs/api/rest/carrier-services/carrier-lookup/.

If you have any questions regarding our Carrier Lookup API, please email us at support@telapi.com

Posted on by TelAPI | Posted in API | Tagged , ,


Introducing TelAPI Heroku Addon

Posted on by TelAPI


One of TelAPI’s foremost goals is making the lives of developers easier when building Telephony applications. Heroku is a platform developers can use to make their lives easier when building ANY type of application. Thats why we’re super excited to announce the public beta of our Heroku Addon.

Starting today, developers on the Heroku platform can integrate with TelAPI in minutes. With the the TelAPI Heroku Addon, your app can now send outbound SMS messages, place outbound calls, and even purchase dedicated phone numbers for receiving inbound SMS and calls. All this telephony functionality and no new sign ups -- everything is seamlessly integrated within your existing Heroku account.

To get started, simply provision the addon to your Heroku application via the Heroku CLI Tool:

Or just grab it from the addon marketplace: https://addons.heroku.com/telapi

Once provisioned, you can make HTTP requests to the heroku.telapi.com domain with your authorization token to initaite calls or messages. Any built in HTTP methods or REST helper libraries will work to facilitate these requests so the addon can be used with the programming language of your choice!

We hope this addon helps developers get their telephony applications off the ground faster and can’t wait to see how its used.

Feel free to get in touch with us at support@telapi.com for more information on getting started using the TelAPI Heroku Addon or view the addon documentation available in the Heroku Dev Center: https://devcenter.heroku.com/articles/telapi

Posted on by TelAPI | Posted in General


Part 2: How To Build An SMS Subscription Service With TelAPI

Posted on by TelAPI


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!

Posted on by TelAPI | Posted in General | Tagged , , , , ,


Part 1: How To Build An SMS Subscription Service With TelAPI

Posted on by TelAPI


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!

Posted on by TelAPI | Posted in General | Tagged , , , , , ,