Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

IVR-IVA API events

Updated on May 10, 2021

Provide a personalized experience by integrating the IVR-IVA channel with an IVR that is capable of text-to-speech and speech-to-text (TTS/STT) translation.

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 Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide

In the absence of TTS/STT capabilities, the IVR can perform the following subset of events:

  • Find a customer
  • Set the customer's context before escalating to a CSR
  • Use the NLP-based bot channel responses similar to other Multichannel processor (MCP)-based channels
The IVR-IVA API contains the following events for the IVR channel, which must be triggered by the IVR's RESTful web interface:

Summary of IVR-IVA API events

EventDescription
find_contactFetches the contact details corresponding to the Automatic Number Identification (ANI), and then links the current interaction to the corresponding contact in Pega Customer Service.
Note: ANI must be unformatted (for example, 16178931234).
set_contextSets the context for a specific session whose context is already known.
get_recommendations

Using the current context, processes the personalized inquiries and case offerings configured on the IVR-IVA channel’s Personalized service tab.

create_caseCreates and starts the instance of a service case configured on the channel.
process_case

Submits the user-provided answer for the prompt for a requested case step. This event is called per case question, and the response will include the subsequent prompt of the next question in the conversation flow. The response will also indicate when the end of the case flow has been reached.

cancel_caseIf the IVR detects that the user quits processing a running case (for example, pressing 0 to abort or says Cancel), the IVR invokes this event to change the status of the active case to Resolved-Withdrawn.
call_end

Terminates the current interaction and changes the interaction case status to Resolved-Completed. The session context will be capped so that subsequent calls for the same session_id do not potentially expose inappropriate data

Authentication

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

  • channel_id: The Pega Customer Service IVR-IVA channel identifier that is generated on channel configuration, found on the Channel tab.
  • 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

find_contact

The find_contact event performs no user verification. It is the responsibility of the IVR to verify the customer before invoking the find_contact event. This event fetches the contact details of the IVR caller using the Automatic Number Identification (ANI) – it is mostly useful for demo purposes. One or more matching contacts will be returned. If multiple matching contacts are returned, it is the responsibility of the IVR to identify the correct contact and use set_context to pass in the correct contact_id. The ANI provided must be unformatted (for example, 16178931234).

Request elements

Request element: Parameters

Parameters

Required/OptionalDescription
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
event_nameRequiredfind_contact

Request element: Attributes

Attributes

Required/OptionalDescription
aniRequiredAutomatic Number Identification (ANI) of the caller

Sample request

{
    "channel_id": "<pyChannelId of IVR channel>",
    "session_id": "<UUID for voice session>",
    "event_name": "find_contact",
    "attributes": {
        ...
        "ani": "+16175551212"
    }
}

Response elements

This response can be extended to return additional contact details such as Account level status of Platinum that can be included into the customer’s greeting.

Response element: Attributes

AttributesRequired/OptionalDescription
aniRequiredAutomatic Number Identification (ANI) of the caller
contact_idRequiredThe contact ID of the caller in Pega Customer Service
verified RequiredIs always false. Pega Customer Service does not verify customers. The IVR verifies callers and passes a verification flag in the set_context response which will be written to the IVR- IVA call transcript.
account_numberRequiredThe account number of the contact
first_nameOptionalThe first name of the contact
last_nameOptionalThe last name of the contact
interaction_keyRequiredThe current interaction key

Sample response

{
    "attributes": {
        "ani": "+16175551212",
        "contact_id": "<contact primary key>",
        "verified": false,
        “contacts: [
            {
        "account_number": "<account primary key>",
        "first_name": "John",
        "last_name": "Smith",
        ...
        "interaction_key": "<interaction pzInsKey>"
    }
}

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.

set_context

The set_context event sets the context for a specific session whose Contact ID is already known. Keys such as contact ID, account number, or other tokens set the context for the rest of the session. This event allows for passing any verification data that the IVR collects. The passed verification data is written to the customer transcript.

Request element: Parameters

Parameter nameRequired/OptionalDescription
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
event_nameRequiredset_contact

Request element: Attributes

Attribute nameRequired/OptionalDescription
aniRequiredAutomatic Number Identification (ANI) of the caller
contact_idRequiredThe contact ID of the caller in Pega Customer Service.
account_numberRequiredThe account number of the contact
custom_tokenOptionalA third-party customer token can be provided
verifiedRequired

Pega Customer Service returns the verification value that is passed. Customer verification is implemented in the IVR.

verification_dataRequiredOptions such as the last four digits of SSN, and Pet name.

Sample request

{
    "channel_id": "<pyChannelId of IVR channel>",
    "session_id": "<UUID for voice session>",
    "event_name": "set_context",
    "attributes": {
        "ani": "+16175551212",
        "contact_id": "<contact primary key>",
        "account_number": "<account primary key>",
        "custom_token": "<app extension token>",
        "verified": <true|false>,
        "verification_data": {
            "Last4SSN": "1234",
            "PetName": "Ruby"
        }        
        }
}

The custom_token will be available in the channel’s running context and can be used in any capacity immediately required by the integrating application. The BuildApplicationUserContext activity (extension point) will allow for building the user context using another data source.

Response elements

The response validation data could be used to customize interaction and case-based customer verification to indicate which security questions have already been answered, so a CSR knows the verification questions prompted by the IVR.

Response element: Attributes

Attribute nameRequired/OptionalDescription
aniRequiredAutomatic Number Identification (ANI) of the caller
contact_idRequiredThe contact ID of the caller in Pega Customer Service
account_numberRequiredThe account number of the contact
custom_tokenOptionalThe application extension token
verified RequiredReturns the value passed in the request.
first_nameOptionalThe first name of the contact
last_nameOptionalThe last name of the contact
interaction_keyRequiredThe current interaction key

Sample response

 "attributes": {
        "ani": "+16175551212"
        "contact_id": "<contact primary key>",
        "account_number": "<account primary key>",
        "custom_token": "<app extension token>",
        "verified": <true|false>,
        "first_name": "John",
        "last_name": "Smith",
        ...
        "interaction_key": "<interaction pzInsKey>"
    }
}

Error codes

Error codeDescription
400 Bad request (if contact_id is missing)
404Not found (if no matching response is found for contact_id)

If the channel session is already in the state of processing a case, issuing this event again, prior to completion of the active case will result in a 400 Bad Request status.

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

get_recommendations

The get_recommendations event processes the business condition logic associated with the channel’s configured personalized inquiries and cases to find applicable inquiries and cases, based on the current context on the IVR-IVA channel's Personalized service tab. This event should only be performed after the IVR verifies the contact.

Request elements

Request element: Parameters

Parameter nameRequired/OptionalDescription
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
event_nameRequiredget_recommendations

Request element: Attributes

AttributesRequired/OptionalDescription
None--

Sample request

 
    "channel_id": "<pyChannelId of IVR channel>", 
    "session_id": "<UUID for voice session>", 
    "event_name": " get_recommendations", 
    "attributes": { 
        ... 
    } 

}

Response elements

Response element: Message

MessageRequired/OptionalDescription
content_typeOptionalType of content
inquiry_promptsOptionalThe message text to communicate to the customer
case_offeredRequiredThe name of the case offered to the caller
case_promptRequiredProvides the prompt text for the case configured in the Personalized IVR-IVA channel, to which the customer responds with either yes or no

Response element: Attributes

AttributesRequired/OptionalDescription
None--

Sample response

{ 
    "message": { 
        "content_type": "PlainText", 
        "inquiry_prompts": ["<Inquiry info>"], 
        "case_offered": "<case_name>", 
        "case_prompt": "<Case y/n?>", 
    }, 
    "attributes": { 
        ... 
    } 

}

create_case

The create_case event creates an instance of the conversational case in the IVR channel based on the customer’s response to the case’s prompt text. The utterance is the case command keyword of the customer’s positive response to the case prompt.

Request elements

Request element: Parameters

Parameter nameRequired/OptionalDescription
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.
utteranceRequiredCase name or case command configured in the IVR-IVA channel’s work flow
event_nameRequiredcreate_case

Request element: Attributes

Attribute nameRequired/Optional Description
None--

Sample request

{
    "channel_id": "<pyChannelId of IVR channel>",
    "session_id": "<UUID for voice session>",
    "utterance": " <case name or keyword>",
    "event_name": " create_case",
    "attributes": {
        ...
    }
}

Response elements

Response element: Messages

Message nameRequired/OptionalDescription
content_typeOptionalType of content
contentOptionalThe message text to communicate to the customer
optionsOptionalA list of options to communicate to the customer

Response element: Attributes

Attribute nameRequired/OptionalDescription
case_endOptionalSet to true at the end of service case processing
case_keyRequiredThe key of the current service case

Sample response

{
    "message": {
        "content_type": "PlainText",
        "content": "<First case prompt>",
        "options": ["multiple choice answers"],
    },
    "attributes": {
        ...
        "case_end": false,
        "case_key": "<case pzInsKey>"
    }
}

Error codes

Error codeDescription
400 Bad request (if an utterance is missing). If the channel session is already in the state of processing a case, issuing this event again prior to completion of the active case will result in a 400 Bad Request status.
404Not found (if no matching response is found for the utterance). If the utterance sent as the case name does not match a configured case command in the channel, a 404 error will be returned.

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

process_case

The process_case event submits the user-provided answers to a prompt for the requested case. This event is called per-question answer provided, and the response will include the prompt for the next question in the conversation flow. The response will also indicate when the end of the case flow has been reached.

Request elements

Request element: 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 caller's voice input, where the input is the caller’s answer to the previous event.
event_nameRequiredprocess_case

Request element: Attributes

Attributes nameRequired/Optional Description
case_keyRequiredThe key of the current service case

Sample request

{ 
    "channel_id": "<pyChannelId of IVR channel>", 
    "session_id": "<UUID for voice session>", 
    "utterance": " <user’s answer>", 
    "event_name": " process_case", 
    "attributes": { 
        ... 
        "case_key": "<case pzInsKey>" 
    } 
}

Response elements

Response element: Messages

Message nameRequired/OptionalDescription
content_typeOptionalType of the content
contentOptionalThe case’s next question and or message to communicate to the caller.
optionsOptionalA list of options to communicate to the customer

Response element: Attributes

Attribute nameRequired/OptionalDescription
case_endOptionalSet to true at the end of the service case processing
case_keyRequiredThe key of the current service case
Note:
  • This event is used in a loop to submit the answers supplied by the IVR caller and to get the next question.
  • If the flow has reached the end, and there are no further prompts that need to be answered by the customer, then the case_end attribute value will be set to true.

Sample response

{ 
    "message": { 
        "content_type": "PlainText", 
        "content": "<Next case prompt>", 
        "options": ["multiple choice answers"], 
    }, 
    "attributes": { 
        ... 
        "case_end": <false|true>, 
        "case_key": "<case pzInsKey>" 
    } 
}

Error codes

Error codeDescription
400 Bad request (if utterance is missing)
404Not found (if no matching response is found for the utterance)

Invoking the event when there isn’t an active case, either because it was never created or because the input collection processing is already complete, will result in a 400 Bad Request status.

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. cyNotValidUtteranceEnds the interaction when utterance is invalidNoneNone

cancel_case

The cancel_case event cancels an ongoing service case if the user wants to quit processing a running case. This event will result in a Resolved-Withdrawn status for the active case.

Request elements

Request element: Parameters

Parameter nameRequired/OptionalDescription
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 caller's voice input, where the input can be a case name or a case command keyword
event_nameRequiredcancel_case

Request element: Attributes

Attribute nameRequired/OptionalDescription
case_keyRequiredThe key of the current service case

Sample request

{ 
    "channel_id": "<pyChannelId of IVR channel>", 
    "session_id": "<UUID for voice session>", 
    "event_name": " cancel_case", 
    "attributes": { 
        ... 
        "case_key": "<case pzInsKey>" 
    } 
}  
}

Response elements

Response element: Messages

Message nameRequired/OptionalDescription
contentOptionalThe message text to communicate to the customer

Response element: Attributes

Attribute nameRequired/OptionalDescription
case_endOptionalSet to true at the end of the service case processing
case_keyRequiredThe key of the current service case

Sample response

{ 
    "message": { 
        "content": "<cancel message>" 
    } 
    "attributes": { 
        ... 
        "case_end": true, 
        "case_key": "<case pzInsKey>" 
    }

Error codes

Error codeDescription
400 Bad request (if the channel session isn't processing a case)

Using this event will change the current case’s status to Resolved-Withdrawn and conclude processing prior to completing the case flow to an end shape. The IVR triggers this event as a result of the user signaling that they want to exit the current work.

To configure the <cancel message> returned, override the pySetInitialBehaviour Activity.

call_end

The call_end event resolves the current session indicating the end of a given session. As a result, the interaction case associated with the IVR channel session instance will be resolved and its status changed to Resolved-Completed.

Request elements

Request element: Parameters

Parameter nameRequired/OptionalDescription
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.
event_nameRequiredcall_end

Request element: Attributes

Attribute nameRequired/OptionalDescription
None--

Sample request

{ 
    "channel_id": "<pyChannelId of IVR channel>", 
    "session_id": "<UUID for voice session>", 
    "event_name": " call_end", 
    "attributes": { 
       ... 
    } 

}

Response elements

Response element: Attributes

Attribute nameRequired/OptionalDescription
interaction_keyRequiredThe current interaction key

Sample response

{ 
    "attributes": { 
        ... 
        "interaction_key": "<interaction pzInsKey>" 
    } 
}

Error codes

Error codeDescription
403 Forbidden status

To mitigate session context exposure, the Data-Channel-User associated with that session_id will be rendered inoperable after call_end such that no additional API calls can be invoked relative to it. Effectively it terminates the session from the IVR-IVA channel perspective. Any additional usage of this session_id after this event has been received will result in a 403 Forbidden status.

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-)NA

Common IVR-IVA API extension points

Extend or customize the IVR-IVA API using the common data transforms and activities.

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 an IVR-IVA channelPrimary(Data-Channel-Configuration-IVRIVA)
ActivityData-Channel-Configuration-IVRIVA. pyOnNewChannelSaveAdds custom events after creating an 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

Have a question? Get answers now.

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

Did you find this content helpful?

Want to help us improve this content?

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