Skip to main content
LinkedIn
Copied!

Table of Contents

IVR-IVA API events

Version:

Only available versions of this content are shown in the dropdown

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:

  • 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

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.
ANI must be unformatted (for example, 16178931234).
set_context Sets 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_case Creates 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_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

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

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

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

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

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.

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

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

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"
        }        
        }
}

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

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

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

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

Work-Channel-Interaction-IVRIVA pyMessageLabel. cyNotValidUtterance

Ends the interaction when utterance is invalid None None

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

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
  • 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 code Description
400 Bad request (if utterance is missing)
404 Not 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 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

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

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

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

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

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
Suggest Edit
Did you find this content helpful?

100% found this useful

Have a question? Get answers now.

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

Ready to crush complexity?

Experience the benefits of Pega Community when you log in.

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

Pega Community has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice
Contact us