This add-on is operated by TelAPI Inc.

Effortless Cloud Telephony


Last Updated: 07 May 2015

The TelAPI add-on is currently in beta.

Table of Contents

This add-on is for quickly and conveniently adding TelAPI powered telephony functionality into your Heroku app. Adding the ability to send SMS or place calls from your application enables seamless communication directly with your customers. Mobile communication is one of the most relevant ways to get in touch with your customers, considering we live in an always-on society with our phones no less than 2 inches from our bodies. Take advantage of this epidemic to ensure that your application is always keeping its users up to date!

Provisioning the add-on

Telapi can be attached to a Heroku application via the CLI:

$ heroku addons:create telapi
-----> Adding telapi to sharp-mountain-4005... done, v18 (free)

Once the addon has been added you can access its management interface where a unique request token can be found. This token is all thats used to authorize HTTP requests to send SMS messages or place calls.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the TELAPI_TOKEN config var so your development environment can make authenticated requests to TelAPI.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the ADDON-CONFIG-NAME values retrieved from heroku config to .env.

$ heroku config -s | grep TELAPI_TOKEN >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.


The initiation of outbound SMS messages or calls with the add-on is achieved by performing an HTTP post request to one of the add-on urls.

The URL for sending an SMS is:


The URL for placing a call:


Using with Ruby

Though the example below implements the httparty library, any ReST client library may be used to interact with the addon.

require 'httparty'

# Send an SMS
request_data = { :To => "[TO_NUMBER]", :Body => "Hello, from TelAPI Heroku addon!", :Token => ENV['TELAPI_TOKEN'] }
r ="", :body => request_data)
puts r

# Make a call
request_data = { :To => "[TO_NUMBER]", :Url => "", :Token => ENV['TELAPI_TOKEN'] }
r ="", :body => request_data)
puts r

# Premium plan users can send messages / place calls via a custom from number they've purchased from the addon management page
request_data = { :To => "[TO_NUMBER]", :From => "[FROM_NUMBER]", :Url => "", :Token =>  ENV[[TELAPI_TOKEN" }
r ="", :body => request_data)
puts r

Using with Python

Though the example below implements the requests library, any ReST client library may be used to interact with the addon.

import os
import requests

def send_sms(to, body, _from = None):
    data = {
        'token'     : os.environ['TELAPI_TOKEN'],
        'to'        : to,                           # The recipient of the SMS message,
        'body'      : body                          # Limited to 160 characters, message splicing must be performed in your logic

    if _from is not None:
        data['from'] = _from

    r ='', data=data)

    return r.json()

// Send via the default DID
print send_sms('+15557771234', 'Hello there, how are you doing today?');

// Send via a custom DID, optional for Premium Accounts
print send_sms('+15557771234', 'Hello there, how are you doing today?', _from='+15558675309');


The TelAPI add-on dashboard allows you to view your usage, add and configure inbound phone numbers, and see a list of all SMS messages / calls occurring through your account.

The dashboard can be accessed via the CLI:

$ heroku addons:open telapi
Opening telapi for sharp-mountain-4005…

or by visiting the Heroku apps web interface and selecting the application in question. Select TelAPI from the Add-ons menu.

Migrating between plans

A variety of plans with varying usage tiers and functionality are available.

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade telapi:newplan
-----> Upgrading telapi:newplan to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: telapi:newplan

Removing the add-on

TelAPI can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:destroy telapi
-----> Removing telapi from sharp-mountain-4005... done, v20 (free)


All TelAPI addon issues should be directed to