Hoiio SDK¶

Setting Up¶

Before you begin, make sure you have already installed the SDK. Refer to Quick Start if you have not. Basically you do a pip install hoiio.

To use the package, you import Hoiio from hoiio.

Then initialize the service with your Hoiio credentials (a pair of App ID and Access Token). You can create an app and get the Hoiio credentials by logging in at http://developer.hoiio.com.

from hoiio import Hoiio

Hoiio.init('MY_APP_ID', 'MY_ACCESS_TOKEN')

We use a singleton pattern [1] to init the credentials, so you only need to call init(...) once.

Requests¶

Hoiio SDK is designed to let you write less code.

It is designed to be as simple as possible, but no simpler [2].

Hence, it has minimal number of classes which you need to know. The most important is Hoiio, which you can use to make various API requests, such as:

• Hoiio.voice.call(...)
• Hoiio.sms.send(...)
• Hoiio.fax.send(...)
• Hoiio.ivr.dial(...)
• Hoiio.ivr.gather(...)

As you can see, the services are categorized as voice, sms, fax, ivr, number and account. This correspond to what Hoiio API provides.

The required parameters are passed in as positional arguments to the methods.

The optional parameters are passed in as keyword arguments after the positional arguments.

Example of a mix of required and optional parameters:

res = Hoiio.CATEGORY.REQUEST(REQUIRED_1, REQUIRED_2, key1=OPTIONAL_1)

You will see many of the APIs are in the same pattern.

Response¶

After you make a service request, a Response object will be returned.

You can access the fields of the response object. It corresponds to the response parameters in Hoiio API.

print res.txn_ref
# 'TX-1234'

You can also access additional fields.

# The exact http response body
print res.text
# '{"txn_ref": "AA-C-3070102","status": "success_ok"}'

# The http response body in JSON
print res.json
# {'txn_ref': 'AA-C-3070102', 'status': 'success_ok'}

Lastly, the SDK uses Requests, a HTTP python package for Humans.

You can access the Response object, which gives you access to fields like the HTTP headers and status code.

print res.response.headers
# {'content-length': '56170', 'x-content-type-options': 'nosniff', 'x-cache':
'HIT from cp1006.eqiad.wmnet, MISS from cp1010.eqiad.wmnet', 'content-encoding':
'gzip', 'age': '3080', 'content-language': 'en', 'vary': 'Accept-Encoding,Cookie',
'server': 'Apache', 'last-modified': 'Wed, 13 Jun 2012 01:33:50 GMT',
'connection': 'close', 'cache-control': 'private, s-maxage=0, max-age=0,
must-revalidate', 'date': 'Thu, 14 Jun 2012 12:59:39 GMT', 'content-type':
'text/html; charset=UTF-8', 'x-cache-lookup': 'HIT from cp1006.eqiad.wmnet:3128,
MISS from cp1010.eqiad.wmnet:80'}

You can even access the request headers, if you need it.

print res.response.request.headers
# {'Accept-Encoding': 'identity, deflate, compress, gzip',
'Accept': '*/*', 'User-Agent': 'python-requests/0.13.1'}

Make call back¶

Makes a voice call back between 2 phone numbers.

res = Hoiio.voice.call('+6511111111', '+6522222222')

There are some optional parameters that you can use as documented in Hoiio Voice API. These optional parameters can be passed in as keyword arguments.

res = Hoiio.voice.call('+6511111111', '+6522222222',
    caller_id = 'private',
    max_duration = 600,
    tag = 'myapp',
    notify_url = 'http://my.server.com/myscript'
)

The example above will call with a private caller ID (shown only to dest2), the call will be cut off in 10 minutes (600 sec), tagged with ‘myapp’ for the application reference, and the server’s script will be notified on the call status.

We have shown how you can make an API request. But what about handling the response?

Hoiio API response can be accessed as fields of a Response object.

res = Hoiio.voice.call('+6511111111', '+6522222222')

print res.txn_ref
# 'AA-S-141147'

print res.is_success()
# True

One of the most important field is txn_ref - a transaction for the API. All chargeable API (eg. making a call back, sending an SMS) will return 1 or more txn_ref.

It is also possible for the API to return unsuccessful. The response status will then return the error code eg. error_invalid_http_method, error_insufficient_credit, error_rate_limit_exceeded, etc. If is_success() returns False, then there is an error, and you might want to log the error.

res = Hoiio.voice.call('+6511111111', '+6522222222')

if res.is_success():
    print 'The txn ref:', res.txn_ref
else:
    # The API failed. Print the error code.
    print 'Error:', res.status

Make conference call¶

Voice call back connects only 2 phone numbers. As an extension, voice conference can connect multiple phone numbers (currently limited to 8 per room).

# Call 3 phones and put them in a conference
res = Hoiio.voice.conference('+6511111111', '+6522222222', '+6533333333')

# Find out the room id
print res.room
# 'MY-ROOM'

# The transaction reference ID correspond to each of the phone number
print res.txn_refs
# ['TX-1', 'TX-2', 'TX-3']

It is not neccessary that you supply all the phone numbers in 1 API request. You could at some point in time add another participant into an existing conference room.

# Add another participant into the conference room
res = Hoiio.voice.conference('+6544444444', room='MY-ROOM')

print res.txn_refs
# ['TX-4']

Hangup call¶

You may also at any point in time hangup any of the participant eg. kick him out of the conference room. In the example below, ‘TX-4’ refers to the txn_ref of +6544444444.

# Hangup one of the phone.
res = Hoiio.voice.hangup('TX-4')

Hangup is applicable to both conference call and call back. The difference is that a call back is considered 1 transaction, so hangup will disconnect both the phones, whereas a conference call is made up of multiple participants (each with their own transaction), so hangup will disconnect the participants individually.

Retrieve call status¶

You can find out the call status of a particular transaction.

res = Hoiio.voice.status('TX-1234')

print res.txn_ref
# 'TX-1234'

print res.tag
# 'my-tag'

print res.date
# datetime.datetime(2012, 1, 31, 12, 6, 15)

print res.dest1
# '+6511111111'

print res.dest2
# '+6522222222'

print res.call_status_dest1
# 'answered'

print res.call_status_dest2
# 'answered'

print res.duration
# 2

print res.currency
# 'SGD'

print res.rate
# 0.018

print res.debit
# 0.036

There are many information you can get from a call status. Most of the fields are returned as string or int or float. For ‘date’, a python datetime is returned.

The Call Status can also be used to query for the live status of a call eg. is it still ongoing?

res = Hoiio.voice.status('TX-1234')

print res.call_status_dest1
# 'ongoing'

Retrieve call history¶

Query for all the transactions.

res = Hoiio.voice.history()

print res.total_entries_count
# 234

print res.entries_count
# 100

for entry in res.entries:
    print entry.txn_ref
    print entry.date
    # etc ..

Each entry has similar fields to that of Call Status.

The query history API will fetch the transationcs in batches of 100. To go to the next page:

res = Hoiio.voice.history(page=2)

Retrieve call rate¶

You could find out how much the call back will cost before you actually make the call.

res = Hoiio.voice.rate('+6511111111', '+6522222222')

print res.currency
# 'SGD'

print  res.rate
# 0.036

print res.talktime
# 2352

The about call will cost $0.036 (Singapore Dollars), and with the account credit balance, the call can last 2352 minutes.

If you don’t want to use API to find out the cost, you could refer to the Pricing Page.

Send an SMS¶

Send a single SMS to a phone. What’s better than a Hoiio World message.

res = Hoiio.sms.send('Hoiio World', '+6511111111')

There are some optional parameters that you can use as documented in Hoiio SMS API. These parameters can be passed in as keyword arguments in all of the methods.

res = Hoiio.sms.send('Hoiio World', '+6511111111',
    sender_name = 'Citibank',
    tag = 'myapp',
    notify_url = 'http://my.server.com/myscript'
)

One of the very useful feature is sender_name. It should only be used if you have activated the SMS Rebranding feature. You can change to any alphanumeric eg. a company name or other phone numbers.

The notify_url should be your web server. Hoiio will post notification to this URL on the SMS delivery status. You need this to know if the SMS is “queued” of “delivered”.

Hoiio API response can be accessed as fields of a Response object.

res = Hoiio.sms.send('Hoiio World', '+6511111111')

print res.txn_ref
# 'AA-S-1234'

print res.is_success()
# True

The txn_ref is a very important field - a transaction for the API. All chargeable API (eg. making a call back, sending an SMS) will return 1 or more txn_ref.

Send bulk SMS¶

Bulk SMS API is a convenient extension to Send an SMS. It sends up to 1,000 SMS in a single request. This is useful if you want to send the same message to multiple phone numbers.

The phone numbers are passed in as variable arguments to the method.

# SMS to 2 numbers (up to 1000 numbers)
res = Hoiio.sms.bulk_send('Hoiio World', '+6511111111', '+652222222',
    notify_url = 'http://my.server.com/myscript'
)

# The bulk_txn_ref that encapsulate individual txn_ref
print res.bulk_txn_ref
# 'AA-B-1234'

It is recommended that you make use of notify_url to track the status of the individual SMS. The txn_ref of the individual SMS will be provided during the notification phase.

Receive SMS¶

Hoiio supports receiving SMS. Developers need to purchase an SMS enabled number from Hoiio. At the point of writing (Sep 2012), the only country that has SMS enabled number is the US.

To get a notification from Hoiio whenever you receive an SMS at the number, you will need to go to Hoiio’s developer portal and configure the Notify URL, or use the Number API to configure.

Retrieve SMS status¶

You can find out the SMS status of a particular transaction.

There are many information you can get from a SMS status. Most of the fields are returned as string, int or float. For ‘date’, a python datetime is returned. Note the datetime is in GMT+8.

res = Hoiio.sms.status('TX-1234')

print res.txn_ref
# 'TX-1234'

print res.sms_status
# 'delivered'

print res.dest
# '+6511111111'

print res.date
# datetime.datetime(2012, 1, 31, 12, 6, 15)

print res.tag
# 'my-tag'

print res.split_count
# 2

print res.currency
# 'SGD'

print res.rate
# 0.032

print res.debit
# 0.064

Retrieve SMS history¶

Query for all the transactions.

res = Hoiio.sms.history()

print res.total_entries_count
# 234

print res.entries_count
# 100

for entry in res.entries:
    print entry.txn_ref
    print entry.date
    # etc ..

Each entry has similar fields to that of SMS Status (see Retrieve SMS status).

The query history API will fetch the transationcs in batches of 100. To go to the next page:

res = Hoiio.voice.history(page=2)

You can also filter by dates. The date format is ‘YYYY-MM-DD HH:MM:SS’ (GMT+8).

res = Hoiio.voice.history(from='2012-01-01 08:00:00', to='2012-12-31 08:00:00')

Retrieve SMS rate¶

Find out how much an SMS will cost before you actually send it.

res = Hoiio.sms.rate('Hoiio World', '+6511111111')

print res.currency
# 'SGD'

print res.rate
# 0.032

res.split_count
# 2

res.total_cost
# 0.064

res.is_unicode
# False

You can also find out how much it cost to receive an SMS on your Hoiio number. Hoiio supports receiving SMS for only a few countries. In the example below, you own the Hoiio number +6599999999.

res = Hoiio.sms.rate_in('+6599999999')

print res.currency
# 'SGD'

print res.rate
# 0.01

Note that Hoiio charges per incoming SMS, regardless of the message size or unicode.

If you don’t need to use API to find out the cost (it seldom change anyway), you could refer to Hoiio Pricing Page.

Answer¶

When a call is received on your Hoiio number, your server will receive a notification from Hoiio, and Hoiio expect your action - to answer the call, or ignore.

Answer is a pseudo API. You don’t need to explicitly call it. To answer the call, just use a Middle or End block eg. Play a message or Transfer to another number.

The notification from Hoiio includes a session, which is an important data needed for you to make subsequent requests to affect that call session.

Dial¶

Make an outgoing to a number.

res = Hoiio.ivr.dial('+6511111111')

print res.txn_ref
# 'TX-1234'

print res.session
# 'S4643'

An advanced use which call a number with a caller ID, plays a message, and set the max duration for the call.

res = Hoiio.ivr.dial('+6511111111',
    msg = 'Hello. This is an automated message from Hoiio.',
    caller_id = '+6500000000',
    max_duration = '60',
    tag = 'myapp',
    notify_url = 'http://my.server.com/myscript'
)

Play¶

Play a message over the phone

res = Hoiio.ivr.play(session, 'Hello. This is an automated message from Hoiio.',
    tag = 'myapp',
    notify_url = 'http://my.server.com/myscript'
)

print res.is_success()
# True

Gather¶

Gather a keypad response over the phone. The following code will ask the user to press 1 for yes or press 2 for no. The system will expect only 1 digit, and it will attempt (and repeats) 3 times if the user does not respond. It will also timeout (hangup) if there is no response in 60 seconds.

res = Hoiio.ivr.gather(session,
    msg = 'Hello. Press 1 for yes, press 2 for no.',
    max_digits = 1,
    timeout = 60,
    attempts = 3,
    tag = 'myapp',
    notify_url = 'http://my.server.com/myscript'
)

print res.is_success()
# True

Record¶

Record a voice message.

res = Hoiio.ivr.record(session,
    msg = 'Hello. We are recording your voice message now.',
    max_duration = 60,
    tag = 'myapp',
    notify_url = 'http://my.server.com/myscript'
)

print res.is_success()
# True

Monitor¶

Monitor a phone conversation, that is record the whole phone conversation from the point that Monitor API is called.

res = Hoiio.ivr.monitor(session,
    msg = 'Hello. Note that this phone conversation is recorded.',
    tag = 'myapp',
    notify_url = 'http://my.server.com/myscript'
)

print res.is_success()
# True

Transfer¶

Transfer to a phone number or a conference room.

res = Hoiio.ivr.transfer(session, '+6522222222'
    msg = 'Hello. We will be transferring this call.',
    caller_id = '+6500000000',
    tag = 'myapp',
    notify_url = 'http://my.server.com/myscript'
)

print res.is_success()
# True

In the example code above, the call will end no matter if the transfer is successful or not. There are cases where you would want to handle the call if the transfer did not go through eg. dest is busy.

You could revert the Transfer operation by setting on_failure to ‘continue’. This way, you will receive a notification when the transfer did not go through, and you can call subsequent Middle or End blocks. eg. Gather or even another Transfer.

res = Hoiio.ivr.transfer(session, '+6522222222'
    msg = 'Hello. We will be transferring this call.',
    caller_id = '+6500000000',
    on_failure = 'continue'
    tag = 'myapp',
    notify_url = 'http://my.server.com/myscript'
)

Hangup¶

Hangup a call.

res = Hoiio.ivr.monitor(session,
    msg = 'Hello. We will be hanging up now. Bye!',
    tag = 'myapp',
    notify_url = 'http://my.server.com/myscript'
)

print res.is_success()
# True

You can call this API at any point of time when a call is in progress. You do not need to wait for a notification before calling this API. However, if hangup is used in this way, the msg parameter will not be played to the user and the call will hangup immediately.

Send Fax¶

Send a PDF file to a fax number

res = Hoiio.fax.send('+6511111111', '/path/to/file.pdf')

print res.txn_ref
# 'TX-1234'

A more advanced use. The filename parameter is used to change the filename that resides at Hoiio.

res = Hoiio.fax.send('+6511111111', '/path/to/file.pdf',
    filename = 'awesome-file.pdf',
    caller_id = '+6500000000',
    tag = 'myapp',
    notify_url = 'http://my.server.com/myscript'
)

Receive Fax¶

To receive fax, you need to purchase a Hoiio number that supports receiving fax. Currently (as of Sep 2012), only Singapore numbers are capable of receiving fax.

To get a notification from Hoiio whenever you receive a fax at the number, you will need to go to Hoiio’s developer portal and configure the Notify URL, or use Number to configure.

Retrieve Fax status¶

Find out the status of a Fax (supports both sent or received) with its txn_ref.

res = Hoiio.fax.status('TX-1234')

print res.txn_ref
# 'TX-1234'

print res.fax_status
# 'answered'

print res.src
# '+6500000000'

print res.dest
# '+6511111111'

print res.date
# datetime.datetime(2012, 1, 31, 12, 6, 15)

print res.fax_pages
# 3

print res.fax_url
# 'http://some.server.com/file.pdf'

print res.tag
# 'my-tag'

print res.currency
# 'SGD'

print res.rate
# 0.032

print res.debit
# 0.064

Retrieve Fax history¶

Query for all fax transactions. Each of entry has similar fields as the response in Retrieve Fax status.

res = Hoiio.fax.history()

print res.total_entries_count
# 234

print res.entries_count
# 100

for entry in res.entries:
    print entry.txn_ref
    print entry.fax_status
    # etc ..

You can also filter the fax history by date and type (incoming, outgoing or all).

res = Hoiio.fax.history(
    from = '2010-01-01 00:00:00',
    to = '2012-01-01 00:00:00',
    page = 3,
    type = 'incoming'
)

Retrieve Fax rate¶

Find out how much a fax will cost before you actually send it.

res = Hoiio.fax.rate('+6511111111')

print res.currency
# 'SGD'

print res.rate
# 0.032

You also check how much it cost to receive a fax.

res = Hoiio.fax.rate_in('+6500000000')

print res.currency
# 'SGD'

print res.rate
# 0.01

Retrieve available countries¶

Retrieve the countries and states that have available Hoiio numbers. The country code and state code are needed later for Retrieve available numbers.

res = Hoiio.number.available_countries()

for country in res.entries:
    print '%s [%s] with number prefix %s' % (country.name, country.code, country.prefix)
    # 'USA [US] with number prefix 1'

    # For countries with states
    for state in country.states:
        print '  %s [%s]' % (state.name, state.code)
        # '  Alabama [AL]'

It is not necessary to use this method if the countries you support is pre-determined. You can simply use the country code in ISO 3166-1 alpha-2 format, and state code in ISO 3166-2 format.

This method is more useful if you want to support new countries dynamically as Hoiio supports them.

Retrieve available numbers¶

Retrieve the numbers availabe for purchasing.

res = Hoiio.number.available_numbers('US', 'AL')

for entry in res.entries:
    print entry.number
    # '+16001234567'

# Print the total available
print res.total_entries_count

# Print the total in this page
print len(res.entries)

For countries without states, the state argument can be omitted.

res = Hoiio.number.available_numbers('SG')

To access a different page,

res = Hoiio.number.available_numbers('SG', page=2)

Retrieve number cost¶

Retrieve how much a number subscription will cost for a country. eg. $4 per month

res = Hoiio.number.rate('US')

print res.currency
# 'USD'

for entry in res.entries:
    print '%d month: %f %s' % (entry.duration, entry.rate, res.currency)
    # '1 month: 4 USD'

Subscribe a number¶

Subscribe a number for x months.

# To subscribe for 1 month
res = Hoiio.number.subscribe('+16001234567', 1)

print 'Subscribed for %f %s' % (res.debit, res.currency)
print 'Expires on %s' % res.expiry

You can also subscribe with auto extension. That way, the number will automatically renew every month.

res = Hoiio.number.subscribe('+16001234567', 'auto_extend')

Configure a number¶

After subscribing to a number, you can configure the number to notify your server when a call/fax/sms is received on the number.

Number capabilities varies across country; they support a mix of voice, fax and SMS, or none. Voice and fax are mutually exlusive, it’s either one or the other.

As of Sept 2012:

• US numbers supports voice + SMS
• Singapore numbers supports voice/fax
• Hong Kong numbers supports voice
• Vietnam numbers supports voice
• Australia numbers supports voice
• New Zealand numbers supports voice

# Configure for voice only
res = Hoiio.number.configure('+16001234567',
    foward_to = 'http://my.server.com/myscript'
)

# Configure for SMS only
res = Hoiio.number.configure('+16001234567',
    foward_sms_to = 'http://my.server.com/myscript'
)

# Configure for voice + SMS
res = Hoiio.number.configure('+16001234567',
    foward_to = 'http://my.server.com/myscript',
    foward_sms_to = 'http://my.server.com/myscript',
)

# Configure for fax + SMS
res = Hoiio.number.configure('+16001234567',
    foward_to = 'http://my.server.com/myscript',
    foward_sms_to = 'http://my.server.com/myscript',
    mode = 'fax'
)

Retrieve subscribed numbers¶

Retrieve details of all your subscribed numbers.

res = Hoiio.number.subscribed_numbers()

for number in res.entries:
    print number.number
    # '+16001234567'

    print number.forward_to
    # 'http://my.server.com/myscript'

    print number.forward_sms_to
    # 'http://my.server.com/myscript'

    print number.expiry
    # 2012-12-31

    print number.auto_extend_status
    # 'enabled'

    print number.country
    # 'US'

    print number.state
    # 'AL'

Retrieve credit balance¶

Hoiio credit balance is made up of:

1. Main Points (aka points)
2. Bonus Points (aka bonus)

The only difference is that bonus cannot be transferred to another account. When Hoiio debits, it will take from bonus first.

res = Hoiio.account.balance()

print 'Balance [%s]: %f (%f + %f)' % (res.currency, res.balance, res.points, res.bonus)
# 'Balance [USD]: 12.40 (10 + 2.40)'

Retrieve account info¶

This retrieves the general information about your account.

res = Hoiio.account.info()

print res.uid
# 'AA-1234'

print res.name
# 'John Appleton'

print res.mobile_number
# '+16001234567'

print res.email
# 'John Appleton'

print res.country
# 'SG'

print res.currency
# 'SGD'

print res.prefix
# '1'