Skip to main content

This content has been archived and is no longer being updated.

Links may not function; however, this content may be relevant to outdated versions of the product.

Customizable Interaction API for text analytics

Suggest edit Updated on September 10, 2021

The Interaction API provides a customizable interface for handling interactions through conversational channels such as email channels and instant messaging platforms. Beginning with Pega Platform™ 8.3, the API integrates text analytics with strategies, propositions, and interaction history to provide the context for making better next-best-action decisions. By considering such factors as previous interactions and an applicable decision strategy, you ensure that the next-best-action decisions that you make by using the Interaction API are consistent and accurate.

In addition, the Interaction API uses a generic Data-Decision-Request/Response class structure for input and output. The new structure facilitates creating a channel-specific API configuration that inherits properties from the parent class, for example, Data-Decision-Request-Chat, Data-Decision-Response-Email, and so on.

This article covers the following topics:

Interaction API components

The Interaction API includes multiple default components under the Data-Decision-Request and Data-Decision-Response classes. These components include the pyInteractionDF data flow, decision strategies, decision tables, and the default pyInteractionTA text analyzer. You can extend these rules to adjust the API to your business needs.

The Data-Decision-Request class contains the rules to handle the interaction input. These rules are combined into the pyInteractionDF data flow that drives the Interaction API. This class has the following data model:

Data-Decision-Request data model
Property nameModeString type
pyTextSingle valueText
pySubjectIDSingle valueText
pyDecisionIDSingle valueText
pyChannelSingle valueIdentifier

The Data-Decision-Response class contains the rules to handle the interaction output, for example, the outcome of natural language processing and decision results. This class has the following data model:

Data-Decision-Response data model
Property nameModeString type
pySubjectIDSingle valueText
pyStatusSingle valueText
pyDecisionIDSingle valueText
pyDecisionResultsPage ListPage List

The strategy outcome is captured in the pyDecisionResult property that belongs to the Data-pxStrategyResult class.

pyInteractionDF data flow

The pyInteractionDF data flow performs natural language processing (NLP) through the referenced text analyzer and feeds the outcome to the interaction strategy. When the data is processed, the data flow generates a response as part of the pyNLPOutcome property on the Data-pxStrategyResult page. In addition, the interaction results are recorded as part of the interaction history.

See the following figure for reference:


pyInteractionDF configuration

The pyInteractionDF data flow is customizable and you can adjust its configuration to your business needs. To prevent the interaction history size from becoming too large, the data flow checks whether the record is a result of a simulation run. If true, the data flow prevents the simulation records from being saved in the interaction history.

Next, the data flow filters out all entities. As a result of natural language processing, each record becomes associated with a single value for sentiment (that is, the opinion that is expressed, for example, positive, negative, or neutral) and topic (that is, the talking point). However, the text analyzer can detect multiple entities in each record. Common examples include names of people, emails, postal codes, names of companies, products, and so on. Because of that, such records as emails can contain multiple entities. Therefore, avoid saving entities in the interaction history to prevent any system issues that could be caused by an increased interaction history size.

Decision strategies

The pyInteractionStrategy is the top-level decision strategy that is called from the pyInteractionDF data flow. This strategy references the following substrategies:

  • pyConvertNLPOutcome – This strategy integrates the NLP outcome from the text analyzer that is referenced in the pyInteractionDF data flow with other next-best-action components. As a result of this strategy, the detected topics and entities are put into the pxStrategyResult class.
  • pyGetActionStrategy – This strategy initiates a case type, based on the mapping defined in the pyGetActionFromIVAConfig decision table.
  • pyGetBestPropositions – This strategy presents the next best action, based on natural language processing. You can extend this strategy by importing channel-specific propositions or referencing any of your existing strategies to provide the next best action.

The following figure provides an overview of the strategy structure within the Interaction API:

Interaction API strategies


    Decision table

    The pyGetActionStrategy is a strategy that includes the pyGetActionFromIVAConfig decision table. You can use this decision table to map text analyzer topics from the channel configuration to case types, as shown in the following example:


    A sample mapping between topics and NLPSample cases

    The Command column contains the topics to be detected by the text analyzer. The Return column contains case types names to initiate when the corresponding topic is detected. The NO_COMMAND_FOUND action is returned when no topics that are listed in the decision table were detected. Depending on your business needs, you can customize the pyGetActionStrategy strategy to take action when no topic is detected, for example, by presenting a proposition.

    Interaction taxonomy

    The Interaction taxonomy contains an empty rule-based topic detection model. Populate this model with your topic-keyword configuration or override this model, based on your channel configuration. For more information about how to create a topic detection model, see:

    Text analyzer

    The Interaction API contains a default pyInteractionTA text analyzer rule. You can override this rule through the channel configuration menu to provide channel-specific treatment. This text analyzer rule supports sentiment analysis, topic detection, and text categorization. By default, the pyInteractionTA text analyzer rule performs email parsing. The following figure shows the pyInteractionTA text analyzer configuration in the pyInteractionDF data flow:

    Parsing emails in Interaction API

    When email is the conversational channel, the pxEmailParser text extraction rule identifies such email components as signature, greeting, body, and disclaimer. You can choose what type of analysis to perform on each email component, depending on your business needs, as shown in the preceding example.

    Extending the Interaction API

    Customize the Interaction API to suit your business needs. You can use different combinations of text analyzers and decision strategies by creating channel-specific classes that inherit from Data-Decision-Request/Response classes, depending on the conversation channel. In general, to configure the Interaction API, perform the following actions:

    1. For each channel, create a class that inherits from the Data-Decision-Request class, for example, Data-Decision-Request-Email.
    2. Use the Save as option to copy the following rules to the request class that you created:
      • pyInteractionDF
      • pyInteractionStrategy
      • pyInteractionTA
    3. Optional: Customize each rule to suit your business needs.
    4. Create a class that inherits from the Data-Decision-Response class, for example, Data-Decision-Response-Email.
    5. Optional: Create channel-specific properties.
    6. Invoke the pyRunInteraction activity that calls the channel-specific instance of the pyInteractionDF data flow.

    Example: Interaction history application in natural language processing

    You can customize the Interaction API in multiple ways, the most common of which is to provide a custom strategy for interaction with users through a conversation channel. The following example demonstrates how to customize the pyGetBestPropositions strategy to combine natural language processing with interaction history. The goal of this strategy is to make a proposition to the user, based on natural language processing outcome. By default, the strategy uses the topic of customer input to determine the best proposition to offer. The interaction history comes into play when determining customer sentiment with regards to the analyzed input record. If the negative sentiment is detected, the strategy checks previous customer inputs for negative sentiment. If three consecutive negative sentiments are detected, the sentiment analysis takes precedence over topic detection in determining the best proposition for customers.

    The following strategies provide an example of how you can customize the Interaction API to combine natural language processing with interaction history to detect multiple negative sentiments and react to them by making a proposition.

    Natural language processing outcomes from previous interactions

    First, determine how to take advantage of previous interactions that involved natural language processing. In the following example, the InvokeIH strategy imports previous interactions for the last three days, and then groups them by the sentiment value. The results are propagated further if the sentiment value of the last two interactions was negative.

    Extracting previous interactions whose sentiment value was negative


    Negative sentiment detection

    In the next step, the pyGetPropositionsForSent strategy checks whether customer input has been negative twice in a row and compares previous results with the currently analyzed record. If there are three consecutive negative sentiments, then a proposition is made to the customer based on the rank.

    Reacting to a history of consecutive negative sentiments


    A next-best-action strategy

    Finally, the top-level pyGetBestPropositions strategy combines sentiment and topic detection to provide the next best action to customers.

    By default, the strategy configuration analyzes the topic of the customer input to determine the proposition to offer. However, the strategy can take the retention steps for unhappy customers by using the pyGetPropositionsForSent strategy if three negative sentiment values for customer input were detected consecutively.

    A strategy for offering propositions to customers based on natural language processing


    Did you find this content helpful? YesNo

    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. is not optimized for Internet Explorer. For the optimal experience, please use:

    Close Deprecation Notice
    Contact us