LinkedIn
Copied!

Table of Contents

IVR-IVA API

Version:

Only available versions of this content are shown in the dropdown

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.

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

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 code Description
401 Channel ID or Session ID is missing
500 Internal 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

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

Work-Channel-Interaction-IVRIVA pyMessageLabel . cyNotValidANI

Ends the interaction when ANI is invalid None None

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

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
  • 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 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

Work-Channel-Interaction-IVRIVA pyMessageLabel. cyNotValidUtterance

Ends the interaction when utterance is invalid None None

cancel_case event

Use the cancel_case event to cancel an ongoing service case.

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

Use the call_end event to resolve or terminate the current 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

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

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

Have a question? Get answers now.

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