IVR-IVA API events
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. In the absence of TTS/STT capabilities, the IVR can perform the following subset of
events: Using the current context, processes the personalized inquiries
and case offerings configured on the IVR-IVA channel’s
Personalized service tab. 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. 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 The IVR-IVA API events use the following body parameters for authentication: The Parameters Attributes 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. 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. 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. Pega Customer Service returns the verification value that is
passed. Customer verification is implemented in the IVR. The 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. 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. 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. 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. Work-Channel-Interaction-IVRIVA pyMessageLabel.
cyNotValidUtterance 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. 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. 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
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 The 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. Extend or customize the IVR-IVA API using the common data transforms and activities. Summary of IVR-IVA API events
Event Description find_contact Fetches the contact details corresponding to the Automatic Number
Identification (ANI), and then links the current interaction to the
corresponding contact in Pega Customer Service. set_context Sets the context for a specific session whose context is already
known. get_recommendations create_case Creates and starts the instance of a service case configured on
the channel. process_case cancel_case If 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 Authentication
Authentication error codes
Error codes
Error code Description 401 Channel ID or Session ID is missing 500 Internal error find_contact
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
Required/Optional 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 event_name Required find_contact Request element: Attributes
Required/Optional Description ani Required Automatic 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
Response element: Attributes
Attributes Required/Optional Description ani Required Automatic Number Identification (ANI) of the
caller contact_id Required The contact ID of the caller in Pega Customer Service
verified Required Is 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_number Required The account number of the contact first_name Optional The first name of the contact last_name Optional The last name of the contact interaction_key Required The 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 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
set_context
Request element: Parameters
Parameter name Required/Optional 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 event_name Required set_contact Request element: Attributes
Attribute name Required/Optional Description ani Required Automatic Number Identification (ANI) of the caller contact_id Required The contact ID of the caller in Pega Customer Service. account_number Required The account number of the contact custom_token Optional A third-party customer token can be provided verified Required verification_data Required Options 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"
}
}
}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
Response element: Attributes
Attribute name Required/Optional Description ani Required Automatic Number Identification (ANI) of the caller contact_id Required The contact ID of the caller in Pega Customer Service
account_number Required The account number of the contact custom_token Optional The application extension token verified Required Returns the value passed in the request. first_name Optional The first name of the contact last_name Optional The last name of the contact interaction_key Required The 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 code Description 400 Bad request (if contact_id is missing) 404 Not found (if no matching response is found for
contact_id) 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 get_recommendations
Request elements
Request element: Parameters
Parameter name Required/Optional 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 event_name Required get_recommendations Request element: Attributes
Attributes Required/Optional Description 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
Message Required/Optional Description content_type Optional Type of content inquiry_prompts Optional The message text to communicate to the customer case_offered Required The name of the case offered to the caller case_prompt Required Provides 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
Attributes Required/Optional Description None - - Sample response
{
"message": {
"content_type": "PlainText",
"inquiry_prompts": ["<Inquiry info>"],
"case_offered": "<case_name>",
"case_prompt": "<Case y/n?>",
},
"attributes": {
...
}
}create_case
Request elements
Request element: Parameters
Parameter name Required/Optional 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 Case name or case command configured in the IVR-IVA channel’s
work flow event_name Required create_case Request element: Attributes
Attribute name Required/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 name Required/Optional Description content_type Optional Type of content content Optional The message text to communicate to the customer options Optional A list of options to communicate to the customer Response element: Attributes
Attribute name Required/Optional Description case_end Optional Set to true at the end of service case processing case_key Required The 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 code Description 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. 404 Not 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 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 process_case
Request elements
Request element: 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 caller's voice input, where the input is the caller’s answer
to the previous event. event_name Required process_case Request element: Attributes
Attributes name Required/Optional Description case_key Required The 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 name Required/Optional Description content_type Optional Type of the content content Optional The case’s next question and or message to communicate to the
caller. options Optional A list of options to communicate to the customer Response element: Attributes
Attribute name Required/Optional Description case_end Optional Set to true at the end of the service case
processing case_key Required The key of the current service case 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 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
Resolved-Withdrawn status for the active case.Request elements
Request element: Parameters
Parameter name Required/Optional 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 caller's voice input, where the input can be a case name or a
case command keyword event_name Required cancel_case Request element: Attributes
Attribute name Required/Optional Description case_key Required The 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 name Required/Optional Description content Optional The message text to communicate to the customer Response element: Attributes
Attribute name Required/Optional Description case_end Optional Set to true at the end of the service case
processing case_key Required The key of the current service case Sample response
{
"message": {
"content": "<cancel message>"
}
"attributes": {
...
"case_end": true,
"case_key": "<case pzInsKey>"
}Error codes
Error code Description 400 Bad request (if the channel session isn't processing a
case) <cancel message> returned, override the
pySetInitialBehaviour Activity. call_end
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 name Required/Optional 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. event_name Required call_end Request element: Attributes
Attribute name Required/Optional Description 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 name Required/Optional Description interaction_key Required The current interaction key Sample response
{
"attributes": {
...
"interaction_key": "<interaction pzInsKey>"
}
}Error codes
Error code Description 403 Forbidden status 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-) NA 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 an IVR-IVA channel Primary(Data-Channel-Configuration-IVRIVA) Activity Data-Channel-Configuration-IVRIVA.
pyOnNewChannelSave Adds custom events after creating an 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 an IVR-IVA channel Next topic Example Pega data utilization by an IVR