Some applications require that you communicate with your campaign while a call is in progress. For example, if the keys pressed by the person on the phone represent an account PIN, your application will need to receive those key presses, do a database lookup, and report the results of that lookup back to your campaign in real-time.
Not all calls require this real-time level of communication. Most outbound calls don't. You generally know all the variable information before the call is placed and can pass that information in the XML post that initiates the outbound call. See the basic outbound alert campaign.
Another scenario exists where you want to know the key presses entered during a phone call, but you don't need the information during the actual phone conversation. Receiving the key presses and other call information immediately on completion of the call will do in this case. Call Summary was designed for this purpose.
Inbound calls in general do require your application to process some key presses, as do some outbound calls. Keep in mind if a key press is always playing the same message, transferring to the same number, going to the same mailbox or jumping to the same location in a campaign, you should have the campaign handle it directly rather than handling it in your application to save development time and effort.
Below is an example of Real-time PIN Authentication:
Lets look at an example of an inbound call, where a caller enters a PIN. While this example will be an inbound call, it could just as easily be an outbound call as well. VoiceShot inbound and outbound campaigns have the same functionality.
Below is the inbound campaign for this example:
Figure 1: Campaign with PIN authentication through the API
The API sends key presses to your application in real time with Call Events. (Click here to learn more about Call Events) To configure Call Events for your campaign do the following:
|
|
|
|
Figure 2: Configuring Call Events
Then determine on which prompts you want Call Events sent to your application. For the example, we want Call Events on the first prompt, which plays the Enter PIN.wav message. To enable Call Events for the first prompt, do the following:
|
|
|
|
Figure 3: Turning Call Events On for Prompt Id 1
When Call Events are enabled for a prompt, its icon changes to 
Next in our example, a person would dial a phone number that is linked to your campaign. The number rings and your campaign answers. The caller hears Enter PIN.wav and keys in a PIN. Your application would receive the following Call Event:
|
to which your application would do something like:
|
Your application sends back <prompt goto="2"/> if the PIN number is valid. <prompt goto="2"/> is a Call Command. This Call Command is directing the flow of the campaign to Prompt Id 2, which is the menu we want callers to hear if they have a valid PIN number.
If the PIN is not valid, your application sends back nothing and the OTHER action plays the Invalid PIN.wav message.
This example is constructed around the premise of an inbound call, but Call Events and Call Commands can be used with outbound calls as well. In practice are not as relevant for outbound calls as most data from your application can be passed in the post that initiates the outbound call.
The entire example above illustrates how you can build sophisticated IVR applications with just a few lines of code. By leveraging the VoiceShot API model, you can offload as much work to the campaign as possible and use your application code only where necessary.
That being said, here is a note for those who want to write everything on their side. To do so, you would create the most generic of campaigns, one with Call Events enabled, a single message and a jump back to that message:
Figure 4: Generic campaign with Call Events
and respond back with the Call Command <prompt goto="1" filename= ...> to the Call Events. You could implement the call structure represented in Figure 1 completely in your code. It is a bit of reinventing the wheel, as handling responses and actions directly in the campaign will save time and development effort.