Call Flow

A Call Flow is the set of actions, attached to a Link, that will be executed when a Call is initiated by the initiateCall() API method, or by calling one of your VoxNumbers. In short, they tell they system what to do with the incoming call.

A Call Flow can be managed via the REST API, please refer to the CallFlow interface functions. You can also use the user interface in the IOVOX Enterprise portal.

Structure

The callFlow element contains all individual Call Flow Rules. For Rules, see the Rules section below

<callFlow name="This Is An Empty Call Flow" notes="It does not have any rules">
      <!-- Rules -->
</callFlow>

Element callFlow Attributes

Name Definition
name The name of the Call Flow for reference in the API and portal
notes A text description of what the Call Flow does

Rules

The rules are the actions that are taken during a Call Flow. See below for a list of possible Call Flow Rules. The general structure of each Rule XML segment is:

<[ruleName] id="rule 1" label="Rule Lablel">
        <!-- Rules -->
</[ruleName]>

Attributes

Name Definition
id The unique identifier of the Rule in the Call Flow. This can be used to reference the Rule through the API
label This value will be displayed in the analytics if a caller hangs up during this rule in the call flow. This will be helpful to evaluate where most callers drop out of your flow

The tag ruleName in a Rule XML will be replaced for any of the following available Rules.  The details of each rule will be explained in each rule below.

List of possible Call Flow Rules

ruleName Description
play Play a message to the Caller
call Forward the Call to a Contact in your account
messageKeypress Allow the caller to press options on their phone's keypad (DTMF) to allow them to choose a direction in your Call Flow
sendSMS Send an SMS to a specified Contact
voicemail Record a voice message from the caller and have it sent as an MP3 attachment to a specified email address
httpRequest Send information about the current call to a given URL as a HTTP Request
timeBased Check the current time and choose a direction in your call flow based on that time
evaluate Perform a condition against a call variable (Call Origin, current date etc) and specify a route in your Call Flow based
on the result. E.g. currentDayName()=SATURDAY or $callOrigin=Withheld

Dynamic CallFlow

What are the Variable Values in a Call Flow?

This term appears when we want to apply the same Call Flow to a set of Links but have one or more different parameters for each Link (e.g. a different Call Forwarding). This is how you will see it in the IOVOX Enterprise portal:

If you have a set of Links which you want to apply a Call Flow to, you probably don't want the same Contact to be called on each Link. In this situation you can create a Call Flow containing a Call Rule whose Contact is a Variable Value. This functionality allows you to reuse the same template for multiple Links. Therefore if you decided to change another rule in the Call Flow, you will only have to change it once.

So when your Call Flow is applied to two Links, you specify who the Contact is for each individual Link:

Link 1 Link 2

As you can see we applied the same Call Flow to different Links without having to create two separate Call Flows.

XML Schema

An XSD can be used to validate the CallFlow XML : https://ent.iovox.com/schema/callflow_schema.xsd

User Example Cases

First off let's just explain the structure of every Rule available, then let's start creating some Call Flows.

The following examples are based on a style of IOVOX Enterprise account like an online Directory Website where each Node is a business, and the Links are the Listings for that business.

Example 1 - Call Flow with a Call Rule with a fixed welcome message, email alert and recorded call

Aim: We want to apply a Call Template to play a welcome message to the caller and then call a Contact. It must call a unique Contact for every Link I attach it to but play the same welcome message. It must also send an email alert if the call hangs up without being answered and all calls must be recorded. To achieve this, Call Flow XML will be as below:

<?xml version="1.0" encoding="utf-8"?>
<callFlow name="Call With Fix Welcome Message" notes="It does not have any rules">
    <call id="call_1" label="Call" destinationContactId="?" destinationPhoneNumber="?" record="true" recordingLabel="callRecorded" recordCallNotificationLabel="defaultRecordMessage" sendCallAlert="MISSED_CALLS">
        <callerMessage>
            <soundFile soundLabel="Welcome"/>
        </callerMessage>
    </call>
 </callFlow>

Example 2.-  Call Flow with Call Rules and Events

Aim: A Call Flow that calls a unique Contact for every Link I apply it to. Calls must be recorded and send an email alert to the Contact if the call is missed. If the call is answered we would like to send a HTTP GET with the call information to a specified URL (http://mysite.example.com/mypage.php?callorigin=442071200300&nodename=demoNode&nodeid=demoNodeId&myStaticVar=sameForEveryCall). If the call destination is BUSY then we would like to play a message stating the line is busy. If the call cannot connect for any other reason, we would like to play a message to the caller stating we could not connect the call. The XML will be as follows:

The following example has a Call Rule where we will control a set of events:

  • ANSWERED: If the Call is Answered we will send a HTTP to your URL
  • BUSY: We will Play a message saying that the line is busy at the moment. This will override the default telephony BUSY tone
  • FAILURE: If none of the previous events has happened, we will play a message stating we could not connect the call
<?xml version="1.0" encoding="utf-8"?>
<callFlow name="Call Controlling Events" notes="It does not have any rules">
    <call id="call_1" label="Call" destinationContactId="?" destinationPhoneNumber="?" record="true" recordingLabel="callRecorded" recordCallNotificationLabel="defaultRecordMessage" sendCallAlert="MISSED_CALLS">
        <eventHandlers>
            <callEvent action="onMatchResult" result="ANSWERED">
                <httpRequest id="httpRequest_1" label="Send Information" url="http://yourplatform.com/yourpage.php" requestMethod="GET">
                    <params>
                        <param name="callorigin" value="$_callOrigin"/>
                        <param name="nodename" value="$_nodeName"/>
                        <param name="nodeid" value="$_nodeId"/>
                        <param name="myStaticVar" value="sameForEveryCall"/>
                    </params>
                </httpRequest>
            </callEvent>
            <callEvent action="onMatchResult" result="BUSY">
                <play id="play_1" label="Say Welcome">
                    <soundFile soundLabel="The Line is busy"/>
                </play>
            </callEvent>
            <failure id="failure_1" label="Failure" attempts="3">
                 <failureMessage>
                    <soundFile soundLabel="Sorry we could not contact the call"/>
                </failureMessage>
            </failure>
        </eventHandlers>
    </call>
 </callFlow>

Example 3.- DTMF Options Call Flow

Aim: A Call Flow that offers a keypress (DTMF) menu to the caller giving them the option to press 1 to connect to the Sales Team or 2 for the Support Team. If the caller presses an invalid key 3 times a Good Bye message is played and the call hangs up.

  • 1: The Keypress 1 which will redirect with our Support Team.
  • 2: The Keypress 2 which will redirect with our Sales Team.
  • FAILURE: Which will announce that the key pressed is incorrect or not entered. After three failed attempts we will play Good Bye message. On the messageKeypress rule itself there is a timeout of 10 seconds which will also lead to this failure outcome if reached
<?xml version="1.0" encoding="utf-8"?>
<callFlow name="DTMF Options" notes="It does not have any rules">
    <messageKeypress id="messageKeypress_1" label="Keypress Menu" captureKeypress="false" timeout="10">
        <play id="play_0" label="">
            <soundFile soundLabel="Options Messages"/>
        </play>
        <eventHandlers>
            <keyEvent action="onMatchKeypressSequence" keypressSequence="1">
                <call id="call_1" label="Support Team" record="false" sendCallAlert="NONE" destinationPhoneNumber="?" destinationContactId="?"/>
            </keyEvent>
            <keyEvent action="onMatchKeypressSequence" keypressSequence="2">
                <call id="call_2" label="Sales Team" record="false" sendCallAlert="NONE" destinationPhoneNumber="?" destinationContactId="?"/>
            </keyEvent>
            <failure id="failure_1" label="Key Pressed Incorrect" attempts="3">
                <keypressFailureMessages>
                    <keypressFailureMessage behaviour="onNoKeypress">
                        <soundFile soundLabel="You did not pressed anything"/>
                    </keypressFailureMessage>
                    <keypressFailureMessage behaviour="onUnmatchedKeypress">
                        <soundFile soundLabel="Wrong key pressed"/>
                    </keypressFailureMessage>
                </keypressFailureMessages>
                <play id="_play_1" label="Bye Message">
                    <soundFile soundLabel="Good Bye"/>
                </play>
            </failure>
        </eventHandlers>
    </messageKeypress>
</callFlow>

Example 4.- Time Based Call Flow

This is a fairly complex example based on Time events that are previously created in the portal or API (see Rules->createTimeTemplate).

Aim: A call flow that will check the current time and go to a specific part of the flow based on that:

  • "Mon - Fri: 6pm - 9am": Look at the times matches in the Time Template called "Mon - Fri: 6pm - 9am" and if the time matches, go here and then:
    • If Call Is BUSY,NO ANSWER,HANGUP, the call will be go through to a voicemail. The voicemail has a variable voicemail greeting and Contact depending on the business.
  • "Weekends:Sat & Sun"**:** If the current time matches this Time Template, go here and then:
    • If Call Is BUSY,NO ANSWER,HANGUP, the call will be go through to a voicemail. The voicemail has a variable voicemail greeting and Contact depending on the business.
  • "Failure": If the call is does not match any of the events then the call will go here, and:
    • Will leave a Voicemail. The voicemail has a variable voicemail greeting and Contact depending on the business.
<?xml version="1.0" encoding="utf-8"?>
<callFlow name="Time Based Call Flow" notes="It does not have any rules">
    <timeBased id="timeBased_1" label="Weekly Action">
        <eventHandlers>
            <timeEvent action="onMatchTime" timeTemplateLabel="Mon - Fri: 6pm - 9am">
                <call id="call_1" label="Call Weekly Support" destinationPhoneNumber="?" destinationContactId="?" record="false" sendCallAlert="NONE">
                    <eventHandlers>
                        <callEvent action="onMatchResult" result="BUSY|NO_ANSWER|CANCELLED">
                            <voicemail id="voicemail_1" label="Week Voicemail" from="noreply@iovox.com" fromName="IOVOX Mailing" subject="IOVOX Enterprise voicemail" silence="2" maxDuration="300" templateName="defaultTemplate" destinationEmailAddress="?" destinationContactId="?">
                                <voicemailMessage>
                                    <soundFile soundLabel="?"/>
                                </voicemailMessage>
                            </voicemail>
                        </callEvent>
                    </eventHandlers>
                </call>
            </timeEvent>
            <timeEvent action="onMatchTime" timeTemplateLabel="Weekends:Sat/Sun">
                <call id="call_2" label="Call Weekend Support" destinationPhoneNumber="?" destinationContactId="?" record="false" sendCallAlert="NONE">
                    <eventHandlers>
                        <callEvent action="onMatchResult" result="BUSY|NO_ANSWER|CANCELLED">
                            <voicemail id="voicemail_2" label="Weekend Voicemail" from="noreply@iovox.com" fromName="IOVOX Mailing" subject="IOVOX Enterprise Voicemail" silence="2" maxDuration="300" templateName="defaultTemplate" destinationEmailAddress="?" destinationContactId="?">
                                <voicemailMessage>
                                    <soundFile soundLabel="?"/>
                                </voicemailMessage>
                            </voicemail>
                        </callEvent>
                    </eventHandlers>
                </call>
            </timeEvent>
            <failure id="failure_1" label="Extra Time Support" attempts="0">
                <voicemail id="voicemail_3" label="Failure Voicemail" from="noreply@iovox.com" fromName="IOVOX Mailing" subject="IOVOX Enterprise Voicemail" silence="2" maxDuration="300" templateName="defaultTemplate" destinationEmailAddress="?" destinationContactId="?">
                    <voicemailMessage>
                        <soundFile soundLabel="?"/>
                    </voicemailMessage>
                </voicemail>
            </failure>
        </eventHandlers>
    </timeBased>
 </callFlow>