This overview is made of 5 sections:

1. Designing your IVR App
2. An Example - Customer Helpline
3. Controlling IVR Behavior
4. Text-To-Speech
5. Charges

Designing your IVR App

We have separated the lifetime of an IVR call into 3 different stages: Start, Middle and End.

In each stage, there are building blocks that you can use to construct your call flow.

The rule is this: You can use only 1 Start block, any number of chaining Middle blocks, and finally 1 End block.

For example, during the start of a call, you can choose to Answer an incoming call, or Dial out to a phone number.

During the middle stage, you could Play a text message/MP3, Gather keypad responses, Record voice messages, or start to Monitor the phone conversation.

Towards the end of the call, you may wish to Hangup or Transfer the call to another number.

It’s entirely up to you to decide the call flow!

An Example - Customer Helpline

We will use an example of a Customer Helpline app to illustrate how you can use the building blocks to construct a typical call flow. In this example, it starts with a caller calling a Hoiio Number, and the call flow begins.

As you can see, we have used Answer, Gather, Play and Transfer blocks. You can, of course, choose to use any other blocks as long as it fits the rule (1 Start block, any number of chaining Middle blocks, and 1 End block).

Read the next section on how we control the IVR behavior.

Controlling IVR Behavior

You are able to control the behavior of the call flow in realtime via our RESTful API. When you receive an incoming call or dial out a call, Hoiio will send you a notification containing the session for that particular call.

Read more about Notifications.

With the session, you will then be able to choose the next block to use by calling one of the available IVR API. A notification will be sent each block is completed. It may also include other information eg. the keypad response (aka DTMF) for a Gather block.

You always have to indicate the next block to use after receiving the notification, until the call ends.

Here is a sequence diagram showing the full server interactions between you and Hoiio, using the Customer Helpline as an example.

Other than Answer (which is implicitly used), you would have used 3 IVR APIs in succession: Gather > Play > Transfer.

Text-To-Speech

All of the building blocks allow you to specify a text message to play, so you do not need to worry about recording your own voice messages. A Text-to-Speech service is included in the API. You can simply specify the text message you want to play over the phone call, and our service will automatically generate the voice message for you.

Languages and Gender

To change the language or gender of the voice, use the <speech> markup. E.g.

<speech language="zh-HK" gender="female">請稍等，我們正在處理您的訂單。</speech>

Supported languages and gender are:

• English (en), male and female
• English (British) (en-UK), male and female
• English (Australian) (en-AU), female only

• English (Canadian) (en-CA), female only

• Chinese (zh), male and female
• Chinese (Taiwanese) (zh-TW), female only

• Cantonese (zh-HK), female only

• Portuguese (pt), male and female

• Portuguese (Brazilian) (pt-BR), female only

• French (fr), male and female

• French (Canadian) (fr-CA), male and female

• Spanish (es),male and female

• Spanish (United States) (es-MX), male only

• Japanese (ja), male and female
• Korean (ko), male and female
• Danish (da), male and female
• German (de), male and female
• Italian (it), male and female
• Turkish (tr), male and female

• Russian (ru), male and female

• Hungarian (hu), female only
• Catalan (ca), female only
• Czech (cs), female only
• Danish (da), female only
• Finnish (fi), female only
• Norwegian (no), female only
• Polish (po), female only
• Swedish (sv), female only
• Greek (el-GR), female only

The default language is English and the default gender is Female. If you are using the default, you can leave out the Speech markup.

We are also working on supporting more languages.

Custom Recordings

If you would like to use your own voice recordings (instead of the synthesized speech), use the <url> markup to specify the audio file to use. We will download the file and use it as the voice message. E.g.

<url>https://example.com/myrecording.mp3</url>

Supported file formats are .mp3, .wav and .gsm (8000 Hz, mono channel). File size must be 10MB or less. If your URL contains the ampersand (&) character, it needs to be encoded as &.

Note: There will be a slight delay when downloading the file for the first time. To enable us to cache your file locally for subsequent calls, please include the “Last-Modified” HTTP header and make sure your file hosting web server respond to our HTTP header “If-Modified-Since” in our request with a “304 Not Modified”. Subsequent calls will not have the delay if we are able to cache your file. If you have updated your file, just make sure your file hosting web server respond to us with the updated file instead of “304 Not Modified”.

Charges

For receiving incoming calls, you will be charged the incoming call rate to the Hoiio Number. For outgoing calls, you will be charged the outgoing call rate depending on the destination number.

If you used the Transfer block, you will be charged an additional outgoing call rate depending on the destination number that the call was transferred to.

For details on the incoming and outgoing call rate, please refer to the Pricing Section.