Hoiio Open API

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:

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 notification 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 https://my.example.com/path/to/script).

https://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=https://my.example.com/path/to/script?username=dave

During notification, you will get back the parameter(s) you set.

https://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