There are 2 ways to start an IVR: receive an incoming call at a Hoiio Number or dial out to a destination number. We will discuss about the first method here. For dialing out to a destination number, please refer to the Dial block.

To receive an incoming call, you have to first sign up for a Hoiio Number. After you have signed up for a Hoiio Number, you will be able to configure the number to send a notification to your application whenever there is an incoming call. After you receive the notification informing you of an incoming call, you can send the appropriate request with the next action for the call to take.

The Answer block is actually a pseudo-block and there is no need to explicitly answer a call. You will only receive a notification when there is an incoming call. If your next action is any Middle block (eg Play, Gather) or the Transfer block, then the call will be automatically answered.

Note: If your account is a trial developer account, you can only receive calls made from your registered number. To remove this restriction, please make a credit top-up. See Free Trial for details.

API URL:

None

Notifications

You must configure your Hoiio Number to send a notification to your application. This is the only way you can receive an incoming call. When there is an incoming call to your Hoiio Number, a notification will be sent to the URL you specified with the following parameters:

Notification Parameters

ivr_block	This is an identifer for the type of block this notification is for. You can use this to differenciate between notifications.This block notification can be identified by the value answer.
session	This is a unique session ID for this particular call. Include this session in your subsequent requests to select what action to take next.
txn_ref	The unique reference ID for this transaction.
from	The incoming Caller ID of this call. Phone numbers start with a "+" and country code (E.164 format), e.g. +6511111111.
to	The dialed number of this call (your Hoiio Number). Phone numbers start with a "+" and country code (E.164 format), e.g. +6511111111.
call_state	The current state of this call. Possible values are: ringing - This call has not been answered yet. You should follow up with one of the Midde or End blocks. If you choose to hang up, the call will not be charged. See Hangup for more details.

API Limits

None

Charges

If you choose to hang up the incoming call immediately (when call_state=ringing) without using any Middle (Play, Gather) blocks, you will not be charged. Refer to Hangup for more details.

You will be charged the incoming call rate if you use any of the Middle (eg Play, Gather) blocks or Transfer block. If you use the Transfer block later on in this call, an additional outgoing call rate (depending on the destination number of the transfer) will be charged. For details of the incoming and outgoing call rate, please refer to the Pricing Section.