REST API & General

REST Format

Hoiio API is designed in a RESTful format and is available over HTTPS for secure requests and responses. For more information on REST, you may take a look here.

The API provides a set of endpoints to developers which allow them to interact with telephony services such as SMS and voice calls. Some examples of endpoints available are:

• sms/send
• voice/call
• user/get_balance

Currently, we support the use of 2 HTTP verbs for all requests: GET and POST. You may use them interchangeably for all of the endpoints. Parameters sent in requests should be URL-encoded.

Responses to API requests are encoded in JSON format. For more information on JSON, you may take a look here. An example of JSON formatted response is:

{
    "status":"success_ok",
    "entries_count":"2",
    "entries":[
        {
            "date":"2010-01-01 10:10:00",
            "duration":"7",
            "dest1":"+6511111111",
            "dest2":"+6522222222",
            "currency":"SGD",
            "rate":"0.020",
            "debit":"0.140"
        },
        {
            "date":"2010-01-01 16:10:00",
            "duration":"1",
            "dest1":"+6511111111",
            "dest2":"+6533333333",
            "currency":"SGD",
            "rate":"0.020",
            "debit":"0.040"
        }
    ]
}

Authentication

When you create an application in the Hoiio Developer Portal, you will be assigned an Application ID (app_id) and an Access Token (access_token).

Best Practices

You should keep your Access Token a secret. Anyone possessing the Access Token will be allowed to make API requests which might incur unauthorized charges to the rightful owner.

Like passwords, not sharing the Application ID and Access Token to anyone else is the best way of keeping your keys secret. However, you should avoid the common pitfall many beginner programmers fall into - unwittingly exposing the keys. The following highlight the do's and don'ts to avoid such a mistake.

• Do store your keys only in server-side code
  You should store the keys like how you would for your database password. It shouldn't show up on a client's browser.
  
  
• Don't embed your keys as hidden fields in HTML forms
  They show up when anyone view the page source.
  
  
• Don't embed your keys in Javascript
  Likewise, one can view the page source to find your keys. Obfuscating your javascript would not stop a determined cracker either.
  
  
• Don't embed your keys in codes that you will distribute
  The codes include desktop and mobile applications. The keys can be retrieved with reverse engineering. Likewise, obfuscation does not help.
  
  
• Don't embed your keys in Flash ®
  There are ways to reverse engineer the compiled binary back into source code. The keys will then be in plain sight.
  
  

API Limits

In order for us to provide a reliable service, we need to impose fair use restrictions on some of the APIs. This includes:

• No more than 8 concurrent calls/faxs per account
• No more than 8 participants in a conference room
• No more than 60 requests per minute per app for certain queries eg. query for voice/SMS rates

As different APIs have different limits, you will need to refer to the API Limits section for each of the API you use. Each API limit is also independent; exceeding the limit of one API does not affect the limit of another API.

Lastly, don't expect every API to have a limit. For instance, you can send SMS as fast as you want. We only impose limits to ensure fair use and reliability.

What happens when you exceed the limit?

When you exceed the limit for an API, you will receive an error response for the API request. You should always handle API limits error, and rectify as necessary eg. throttle your request or try again later.

If your app requires more than the given limits, you may email us at developer@hoiio.com and we will review on a case-by-case basis.

Tips

• Caching
  Cache information that are not frequently updated (such as user account information) instead of requesting them from Hoiio. This will also improve the response time of your application for a better user experience.
  
  
• Use Notifications for long running requests
  For APIs that may take some time to execute (such as making a call or the delivery status of a SMS), you can specify where Hoiio should send the result of your request to when it is ready. Avoid polling Hoiio server constantly to check on the result of your request. For example, if you need to know whether an SMS has been delivered, set the notify_url parameter in sms/send. Our server will send the delivery result to the URL you have specified when it is ready.
  
  
• Throttling
  Throttle the rate of your request by implementing a queue locally. This will allow you to control the rate of request that you are sending to our servers and lets you keep within the limit.
  
  
• Request for a higher limit
  If the default limit is insufficient for your needs, please email us.
  
  

Handling Notifications

Certain APIs produce events that developers will be interested in some time in the future. For example, after making a voice call request, you might be interested to find out the duration of a call when the call is hung up. For that, you should make use of Notifications (instead of constantly polling with voice status API).

Notifications are asynchronous and Hoiio will notify your web server as an event happens.

Some APIs that support Notifications are:

• sms/send
• voice/call
• ivr/answer

Handling Notifications

To receive notifications, there are 3 things that you'll need to do:

1. Configure a web server to receive HTTP POST requests from Hoiio.
   Your web server endpoint/script should process the content POST-ed by Hoiio. It should respond with a HTTP 200 OK status (the HTTP body is ignored).
   
   
2. Configure Notify URL for receiving a call/SMS.
   You have to specify the URL that Hoiio will POST to when your Hoiio Number receives a call/SMS. The URL is your web server URL. You can either use the Number API, or go the portal and configure for the number.
   
   
3. Set notify_url parameter in each API requests.
   Hoiio will POST to this URL for events related to this API request. You can have a different URL from (2), or none if you are not interested in the events.
   
   

Notifications will not be resent to your application if your URL is not properly configured. You may also receive more than 1 notification as time progresses (such as the delivery status of a SMS). The last notification will be the most updated result.

Notification Parameters

The notifcation parameters are in the URL query string. For example, Hoiio will HTTP POST to the following URL when you use sms/send (assuming your web server is at http://my.example.com/path/to/script).

http://my.example.com/path/to/script?to=%2B16501234567&debit=0.013&from=%2B16201234567&date=2012-10-30+12%3A20%3A50&msg=hoiio+world&txn_ref=AA-SI-85&currency=SGD

You could also provide pass-on parameters in your notify_url, which will subsequently be passed back to you when Hoiio POST the nofication. For example, you want to pass along a "username", set as such.

notify_url=http://my.example.com/path/to/script?username=dave

http://my.example.com/path/to/script?to=%2B16501234567&debit=0.013&from=%2B16201234567&date=2012-10-30+12%3A20%3A50&msg=hoiio+world&txn_ref=AA-SI-85&currency=SGD&username=dave

Tip: Pass-on parameters are especially useful for IVR APIs which you can pass on an "app_state" such as "gather1", "gather2", etc

Verifying Notifications

You can verify that a notification is genuinely sent from Hoiio.

This step is optional, but is highly advised.

If you do not verify the notifications, HTTP requests could be spoofed by malicious hackers, and you could be tricked into believing that Hoiio has sent you the notifications.

The Algorithm

payload = HTTP body
key = access_token
computed_signature = hex_encoded(hmac_sha256(payload, key))
notification_signature = HTTP Header X-Hoiio-Signature
if (computed_signature == notification_signature)
    // This is genuinely from Hoiio
    // Process..
else
    // This is from malicious hacker
    // Ignore!

In the algorithm, you compute a signature with the HTTP body and your access token (which is a secret only you and Hoiio know). On the other hand, Hoiio passes you a custom HTTP request header call X-Hoiio-Signature. If the 2 signatures are the same, then you can be sure the notification is genuinely from Hoiio.

You have to implement the above in your own development environment. You can refer to how signature are computed for Java, PHP and Python.

Currency Codes

Your credit balances are stored in your home country's currency. When you query your credit balances, these currency code will indicate how much credit balance you have.