IVR-IVA API
Use the Pega Customer Service IVR-IVA API to trigger events for the
IVR-IVA channel to gather additional contact details, process the case types configured in
the channel, cancel ongoing case flow, and end a call. The security configuration API supports the following events and authentication
parameters to provide bot responses using the IVR-IVA channel. The IVR-IVA API uses the following body parameters for authentication: Use the get_contact event to fetch the contact details of the IVR
caller using the Automatic Number Identification (ANI) in Pega Customer Service and
link the current interaction to the contact. Work-Channel-Interaction-IVRIVA pyMessageLabel .
cyNotValidANI Pega Customer Service identifies the caller by using the ANI attribute in
the request body. You can customize it by setting a value of call identifier to
RequestDetails.czCallIdentifier in the
cyCreateIVRRequestPage activity. Use the run_case event to create and process a service case in the
IVR-IVA channel based on the user input. Work-Channel-Interaction-IVRIVA pyMessageLabel.
cyNotValidUtterance Use the cancel_case event to cancel an ongoing service
case. Use the call_end event to resolve or terminate the current
event. The following are the common data transforms and activities to extend or customize
the IVR-IVA API:IVR-IVA API events
Event Description get_contact Fetches the contact details corresponding to the Automatic Number
Identification (ANI) and links the current interaction to the
corresponding contact in Pega Customer Service run_case Creates and runs the corresponding case type in the channel
cancel_case Cancels the ongoing service case and changes the status to
Resolved-withdrawn call_end Terminates the current interaction and changes the status to
Resolved-withdrawn Authentication
Authentication error codes
Error codes
Error code Description 401 Channel ID or Session ID is missing 500 Internal error get_contact event
Request parameters
Name Required Description channel_id Required The IVR-IVA channel identifier session_id Required The unique session identifier given by the IVR system. All API
calls within an interaction need to have the same
session_id utterance Optional The voice input of the user event_name Required get_contact attributes Required Automatic Number Identification (ANI) of the caller Request
{
"channel_id":"3bc1c3b45ea911ea88f277fee9bcd8c0",
"session_id":"ea6a1e1e-b311-43fb-ad63-d4b9582261",
"utterance":"",
"event_name":"get_contact",
"attributes": {
"ani": "613-543-1234"
}
}Response parameters
Parameter Required Description case_key Optional The key of the current service case contact_id Required The contact ID of the caller in Pega Customer Service
first_name Optional The first name of the contact interaction_key Required The current interaction key last_name Optional The last name of the contact Response
{
"attributes": {
"case_key": "",
"contact_id":"CONT-1",
"first_name":"Sara",
"interaction_key":"PEGA-CA-WORK-INTERACTION I-23",
"last_name": "Connor"
},
"message": {
"content": ""
}
}
Error codes
Error code Description 400 Bad request (if the ANI attribute is empty) 404 Not found (if no matching contact is found) Extension or customization points
Activity or field value Purpose Available page Parameters Work-Channel-Interaction-IVRIVA.
BuildApplicationUserContext Sets the contact context on current interaction, channel user
page, and template operator Primary (Work-Channel-Interaction-IVRIVA)
channelUser(Data-Channel-User)
Caller ANI: The ANI call identifier used to fetch the
contact details
Work-Channel-Interaction-IVRIVA pyMessageLabel .
cyEmptyANI Shows the message when ANI is empty None None Ends the interaction when ANI is invalid None None Customized call identifier
run_case event
Request parameters
Name Required Description channel_id Required The IVR-IVA channel identifier session_id Required The unique session identifier that the IVR system provides. All
API calls within an interaction must have the same
session_id. utterance Required The voice input of the user. If the channel is configured for
outside service case context, it processes the utterance as a case
command. If the channel is configured for inside service case
context, it takes the utterance as an input for case
processing. event_name Required run_case attributes Required Automatic Number Identification (ANI) of the caller. Request
{
"channel_id":"3bc1c3b45ea911ea88f277fee9bcd8c0",
"session_id":"ea6a1e1e-b311-43fb-ad63-d4b9582261",
"utterance":"statement",
"event_name":"run_case",
"attributes": {
"ani": ""
}
}Response parameters
Parameter Required Description case_key Optional The key of the current service case case_end Optional Set to true at the end of the service case processing first_name Optional The first name of the contact interaction_key Required The current interaction key last_name Optional The last name of the contact content Optional The message text to communicate to the customer choices Optional A list of options to communicate to the customer Response
{
"attributes": {
"case_key": "PEGACA_WORK S-13",
"contact_id":"CONT-1",
"first_name":"Sara",
"interaction_key":"PEGA-CA-WORK-INTERACTION I-23",
"last_name": "Connor"
},
"message": {
"content": "Which account are you interested in?",
"options": [
"Commercial Checking : 111110000",
"Platinum Rewards Card : 1234500078963456",
"Personal Checking: 12457890",
" 30 year fixed mortgage : 6543210023"
]
}
}
Error codes
Error code Description 400 Bad request (if utterance is missing) 404 Not found (if no matching response is found for the
utterance) Extension or customization points
Activity or field value Purpose Available page Parameters Data-Channel-Configuration-IVRIVA. cyPostCreateCaseExt
Adds custom logic after creating a service case Primary (Work-Channel-Interaction-IVRIVA)
ServiceCase(Work-) None Work-Channel-Interaction-IVRIVA pyMessageLabel.
cyEmptyUtterance Shows the message when utterance is empty None None Ends the interaction when utterance is invalid None None cancel_case event
Request parameters
Name Required Description channel_id Required The IVR-IVA channel identifier. session_id Required The unique session identifier that the IVR system provides. All
API calls within an interaction must have the same
session_id. utterance Optional The voice input of the user. If the channel is configured for
outside service case context, it processes the utterance as a case
command. If the channel is configured for inside service case
context, it takes the utterance as an input for case
processing. event_name Required cancel_case attributes Optional Automatic Number Identification (ANI) of the caller. Request
{
"channel_id":"3bc1c3b45ea911ea88f277fee9bcd8c0",
"session_id":"ea6a1e1e-b311-43fb-ad63-d4b9582261",
"utterance":"",
"event_name":"cancel_case",
"attributes": {
"ani": ""
}
}Response parameters
Parameter Required Description case_key Optional The key of the current service case case_end Optional Set to true at the end of the service case processing first_name Optional The first name of the contact interaction_key Required The current interaction key last_name Optional The last name of the contact content Optional The message text to communicate to the customer choices Optional A list of options to communicate to the customer Response
{
"attributes": {
"case_key": "",
"contact_id":"",
"first_name":"",
"interaction_key":"PEGA-CA-WORK-INTERACTION I-23",
"last_name": ""
},
"message": {
"content": "Your case has been canceled. You can start from the beginning.",
}
}
call_end event
Request parameters
Name Required Description channel_id Required The IVR-IVA channel identifier. session_id Required The unique session identifier that the IVR system provides. All
API calls within an interaction must have the same
session_id. utterance Optional The voice input of the user. If the channel is configured for
outside service case context, it processes the utterance as a case
command. If the channel is configured for inside service case
context, it takes the utterance as an input for case
processing. event_name Required call_end attributes Optional Automatic Number Identification (ANI) of the caller. Request
{
"channel_id":"3bc1c3b45ea911ea88f277fee9bcd8c0",
"session_id":"ea6a1e1e-b311-43fb-ad63-d4b9582261",
"utterance":"",
"event_name":"call_end",
"attributes": {
"ani": ""
}
}Response parameters
Parameter Required Description case_key Optional The key of the current service case case_end Optional Set to true at the end of the service case processing first_name Optional The first name of the contact interaction_key Required The current interaction key last_name Optional The last name of the contact content Optional The message text to communicate to the customer choices Optional A list of options to communicate to the customer Response
{
"attributes": {
"case_key": "",
"contact_id":"",
"first_name":"",
"interaction_key":"PEGA-CA-WORK-INTERACTION I-23",
"last_name": ""
},
"message": {
"content": "Thank you for calling",
}
}
Extension or customization points
Field value Purpose Available page Parameters Work-Channel-Interaction-IVRIVA
pyMessageLabel.Thank you for calling. Shows the interaction ending note to communicate to the
customer Primary (Work-Channel-Interaction-IVRIVA)
ServiceCase(Work-) Common IVR-IVA API extension points
Extension or customization points
Type Name Purpose Available page Data transform Data-Channel-Configuration-IVRIVA.
pyDefault Sets initial properties for the channel Primary
(Data-Channel-Configuration-IVRIVA) Data transform Data-Channel-Authentication-IVRIVA.
cyCreateIVRRequestPage Adds custom parameters to a request page JSON message (any); Request details
(Embed-IVRIVA-RequestDetails) Data transform Data-Channel-Authentication-IVRIVA.
cyCreateIVRResponsePage Adds custom parameters to a response page pyInteractionCase(Work-Channel-Interaction-IVRIVA);
Message (any) Activity Data-Channel-Configuration-IVRIVA.
cyAddIVRDefaultEventsExt Adds custom events while creating a IVR-IVA channel Primary(Data-Channel-Configuration-IVRIVA) Activity Data-Channel-Configuration-IVRIVA.
pyOnNewChannelSave Adds custom events after creating a IVR-IVA channel Primary(Data-Channel-Configuration-IVRIVA) Activity Work-Channel-Interaction-IVRIVA.pyPostAcquireInteraction Extension point called when an interaction case is closed pyBotConfig Data-Channel-Configuration-
IVRIVApyInteractionCase
Work-Channel-Interaction-
IVRIVApyClosedInteractionCase
Work-Channel-Interaction- IVRIVA
Previous topic Creating the IVR-IVA channel Next topic Email