Skip to main content

IVR-IVA API

Suggest edit
Updated on March 11, 2021

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.

Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide

The security configuration API supports the following events and authentication parameters to provide bot responses using the IVR-IVA channel.

IVR-IVA API events

EventDescription
get_contactFetches the contact details corresponding to the Automatic Number Identification (ANI) and links the current interaction to the corresponding contact in Pega Customer Service
run_caseCreates and runs the corresponding case type in the channel
cancel_caseCancels the ongoing service case and changes the status to Resolved-withdrawn
call_endTerminates the current interaction and changes the status to Resolved-withdrawn

Authentication

The IVR-IVA API uses the following body parameters for authentication:

  • channel_id: The Pega IVR_IVA channel identifier that is generated on channel configuration.
  • session_id: The unique identifier of the ongoing call session. The external IVR system generates this ID and shares it with Pega Customer Service on every API call during an interaction.

Authentication error codes

Error codes

Error codeDescription
401Channel ID or Session ID is missing
500Internal error

get_contact event

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.

Request parameters

NameRequiredDescription
channel_idRequiredThe IVR-IVA channel identifier
session_idRequiredThe unique session identifier given by the IVR system. All API calls within an interaction need to have the same session_id
utteranceOptionalThe voice input of the user
event_nameRequiredget_contact
attributesRequiredAutomatic 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

ParameterRequiredDescription
case_keyOptionalThe key of the current service case
contact_idRequiredThe contact ID of the caller in Pega Customer Service
first_nameOptionalThe first name of the contact
interaction_keyRequiredThe current interaction key
last_nameOptionalThe 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 codeDescription
400 Bad request (if the ANI attribute is empty)
404Not found (if no matching contact is found)

Extension or customization points

Activity or field valuePurposeAvailable pageParameters
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 . cyEmptyANIShows the message when ANI is emptyNoneNone

Work-Channel-Interaction-IVRIVA pyMessageLabel . cyNotValidANI

Ends the interaction when ANI is invalidNoneNone

Customized call identifier

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.

run_case event

Use the run_case event to create and process a service case in the IVR-IVA channel based on the user input.

Request parameters

NameRequiredDescription
channel_idRequiredThe IVR-IVA channel identifier
session_idRequiredThe unique session identifier that the IVR system provides. All API calls within an interaction must have the same session_id.
utteranceRequiredThe 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_nameRequiredrun_case
attributesRequiredAutomatic 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

ParameterRequiredDescription
case_keyOptionalThe key of the current service case
case_endOptionalSet to true at the end of the service case processing
first_nameOptionalThe first name of the contact
interaction_keyRequiredThe current interaction key
last_nameOptionalThe last name of the contact
contentOptionalThe message text to communicate to the customer
choicesOptionalA list of options to communicate to the customer
Note:
  • You can configure the text analyzers in the IVR-IVA channel to consider an utterance as a bot command or as input to case type.
  • If a service case opens when another instance of the service case is open, the previous instance of the service case remains in the Open status. CSRs can retrieve such case types for further processing.

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 codeDescription
400 Bad request (if utterance is missing)
404Not found (if no matching response is found for the utterance)

Extension or customization points

Activity or field valuePurposeAvailable pageParameters
Data-Channel-Configuration-IVRIVA. cyPostCreateCaseExt Adds custom logic after creating a service casePrimary (Work-Channel-Interaction-IVRIVA) ServiceCase(Work-)None
Work-Channel-Interaction-IVRIVA pyMessageLabel. cyEmptyUtteranceShows the message when utterance is emptyNoneNone

Work-Channel-Interaction-IVRIVA pyMessageLabel. cyNotValidUtterance

Ends the interaction when utterance is invalidNoneNone

cancel_case event

Use the cancel_case event to cancel an ongoing service case.

Request parameters

NameRequiredDescription
channel_idRequiredThe IVR-IVA channel identifier.
session_idRequiredThe unique session identifier that the IVR system provides. All API calls within an interaction must have the same session_id.
utteranceOptionalThe 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_nameRequiredcancel_case
attributesOptionalAutomatic 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

ParameterRequiredDescription
case_keyOptionalThe key of the current service case
case_endOptionalSet to true at the end of the service case processing
first_nameOptionalThe first name of the contact
interaction_keyRequiredThe current interaction key
last_nameOptionalThe last name of the contact
contentOptionalThe message text to communicate to the customer
choicesOptionalA 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

Use the call_end event to resolve or terminate the current event.

Request parameters

NameRequiredDescription
channel_idRequiredThe IVR-IVA channel identifier.
session_idRequiredThe unique session identifier that the IVR system provides. All API calls within an interaction must have the same session_id.
utteranceOptionalThe 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_nameRequiredcall_end
attributesOptionalAutomatic 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

ParameterRequiredDescription
case_keyOptionalThe key of the current service case
case_endOptionalSet to true at the end of the service case processing
first_nameOptionalThe first name of the contact
interaction_keyRequiredThe current interaction key
last_nameOptionalThe last name of the contact
contentOptionalThe message text to communicate to the customer
choicesOptionalA 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 valuePurposeAvailable pageParameters
Work-Channel-Interaction-IVRIVA pyMessageLabel.Thank you for calling.Shows the interaction ending note to communicate to the customerPrimary (Work-Channel-Interaction-IVRIVA) ServiceCase(Work-)

Common IVR-IVA API extension points

The following are the common data transforms and activities to extend or customize the IVR-IVA API:

Extension or customization points

TypeNamePurposeAvailable page
Data transform Data-Channel-Configuration-IVRIVA. pyDefaultSets initial properties for the channelPrimary (Data-Channel-Configuration-IVRIVA)
Data transformData-Channel-Authentication-IVRIVA. cyCreateIVRRequestPageAdds custom parameters to a request pageJSON message (any); Request details (Embed-IVRIVA-RequestDetails)
Data transformData-Channel-Authentication-IVRIVA. cyCreateIVRResponsePageAdds custom parameters to a response pagepyInteractionCase(Work-Channel-Interaction-IVRIVA); Message (any)
ActivityData-Channel-Configuration-IVRIVA. cyAddIVRDefaultEventsExtAdds custom events while creating a IVR-IVA channelPrimary(Data-Channel-Configuration-IVRIVA)
ActivityData-Channel-Configuration-IVRIVA. pyOnNewChannelSaveAdds custom events after creating a IVR-IVA channelPrimary(Data-Channel-Configuration-IVRIVA)
ActivityWork-Channel-Interaction-IVRIVA.pyPostAcquireInteractionExtension point called when an interaction case is closedpyBotConfig Data-Channel-Configuration- IVRIVApyInteractionCase Work-Channel-Interaction- IVRIVApyClosedInteractionCase Work-Channel-Interaction- IVRIVA

Did you find this content helpful? YesNo

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us