This add-on is operated by TelAPI Inc.
Effortless Cloud Telephony
TelAPI
Last updated January 30, 2017
This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.
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 the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env
file. To view all of your app’s config vars, type heroku config
. Use the following command to add the ADDON-CONFIG-NAME values retrieved from heroku config to your .env
file.
$ 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
.
For more information, see the Heroku Local article.
Usage
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:
POST heroku.telapi.com/send_sms
The URL for placing a call:
POST heroku.telapi.com/make_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 = HTTParty.post("https://heroku.telapi.com/send_sms", :body => request_data)
puts r
# Make a call
request_data = { :To => "[TO_NUMBER]", :Url => "https://heroku.telapi.com/inbound_call", :Token => ENV['TELAPI_TOKEN'] }
r = HTTParty.post("https://heroku.telapi.com/make_call", :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 => "https://heroku.telapi.com/inbound_call", :Token => ENV[[TELAPI_TOKEN" }
r = HTTParty.post("https://heroku.telapi.com/make_call", :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 = requests.post('https://heroku.telapi.com/send_sms', 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');
Dashboard
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 Dashboard 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)
Support
All TelAPI addon issues should be directed to support@telapi.com.