LinkedIn
Copied!

Table of Contents

Triggering a real-time container with the Container REST service

Version:

Only available versions of this content are shown in the dropdown

The Container service is available to make a Next-Best-Action decision in inbound, real-time channels such as web self-service, call center and mobile applications. The Container REST API supports both the POST and GET HTTP methods. The Container service provides a layer of abstraction between the calling channel and the specific decision logic that is executed so a user can easily change the content delivered to the channel without changing the interface or parameters in the API.

This service supports both Pega and third-party identity matching for the Web and Mobile channels.

The URL pattern for this service is:

http://<host>:<port>/prweb/PRRestService/PegaMKTContainer/V3/Container

POST Service Request

For the POST request, the service expects a JSON Object with the following attributes:

Name Optionality Description
SubjectID Optional for the Web and Mobile channels The identifier for the specified context.
ContextName Required The singular friendly name of the context entity that indicates the type for SubjectID.
ExternalID Optional When using third-party identity management, this represents the identifier for the user.
ContainerName Required Name of the Container or Containers to trigger. Can be a single value or a comma-separated list of Containers, for example, NextBestAction, BestOffer.
Channel Required Channel calling the container, where the results will be rendered.
Direction Required Direction of communication (Inbound or Outbound)
Placements Optional Comma-delimited list of placement types (for example, Tile, Hero) that will limit the number of treatments returned to the top treatments that match the specified placement types.
Contexts Optional Situation data from channel such as customer mood, current web page.

Contexts attributes

Name Description
Key Identifier for context info.
Type Type of context data.
Value Value for the specified key.

A sample request JSON Object is shown below:

  • {
  • "SubjectID":"AID-100",
  • "ContextName":"Account",
  • "ContainerName": "NextBestAction",
  • "Channel": "Web",
  • "Direction": "Inbound",
  • "Placements":"Hero,Tile,Tile,Tile",
  • "Contexts":[
  • {
  • "Type":"",
  • "Value":"",
  • "Key":""
  • }]}

GET Service Request

For the GET request, the service expects a JSON Object with the following attributes:

Name Optionality Description
SubjectID Optional for the Web and Mobile channels The identifier for the specified context.
ContextName Required The singular friendly name of the context entity that indicates the type for SubjectID.
ContainerName Required Name of the Container to trigger.
Channel Required Channel calling the container, where the results will be rendered
Direction Required Direction of communication (Inbound or Outbound).
Placements Optional Comma-delimited list of placement types (for example, Tile, Hero) that will limit the number of treatments returned to the top treatments that match the specified placement types.
ContextKey Optional Situation data from channel such as customer mood, current web page.
ContextValue Optional Situational data value.

A sample GET URL is shown below:

http://<HOST>:<PORT>/prweb/PRRestService/PegaMKTContainer/V3/Container? SubjectID=AID-100&ContextName=Account&ContainerName=NextBestAction&Channel=Web&Direction=Inbound&Placements=Hero,Tile,Tile,Tile

Service Response

For the response, the service returns a JSON Object with the following attributes:

Name Description
Status OK for successful result.
ContainerName Name of the container.
RankedResults An array containing one or more actions returned by Strategy execution.

RankedResults attributes for each action:

Name Description
Name Name of the action.
Issue Issue to which the action belongs.
InteractionID

Decision results identifier for the Container call. Decision results are stored in a Cassandra datastore (pxDecisionResults) as part of the Adaptive Analytics delayed learning feature. The InteractionID is required during the CaptureResponse process to match the response to the original decision result, so that adaptive models can learn from the interaction.

Rank Action rank based on Strategy configuration.
SubjectID The identifier for the specified context.
ContextName The singular friendly name of the context entity that indicates the type for SubjectID.
SubjectName Business-friendly name for the SubjectID (value set in TransformSROutput data transform).
Category Category to which the action belongs.
CustomerCost Cost of this product/service to the customer.
ContentFormat Type of content in ImageURL (HTML fragment/Image).
Label Business friendly description of the action.
Benefits Benefits to the customer.
WhyRelevant Why this action is relevant for the customer.
Direction Direction in which the interaction was initiated, Inbound or Outbound.
ShortDescription Short description of the action.
GroupID Identifier for the SubjectID's parent entity.
PaidAudienceName Name of the paid audience.
Identifier Unique identifier for the action.
Placement Type of treatment.
Pricing Description of the pricing.
Journey Name of the associated customer journey.
JourneyStage Name of the associated customer journey stage.
JourneyStep Name of the associated customer journey step.
EligibilityDescription Criteria for customers to be eligible for this action.
Propensity Action propensity value.
AgentCompensation Agent compensation amount if customer accepts action.
ClassIdentifier Internal class for the action results.
Priority Action priority based on Strategy configuration.
Channel Channel the interaction occurred on.
BundleName Name of the action bundle.
ImageURL URL to the associated action image.
BundleParent Indicates if this action is a bundle parent.
Variant Variation of the action (for example, 64gb, 128gb, 256gb).
Treatment The name of the action treatment.
InternalCost The internal company cost of the action.
CampaignID Work ID of the active Campaign associated with this Container.
OfferValue The value the customer receives from this action.
ClickThroughURL

URL to invoke the CaptureWebClickThrough API. The encrypted parameter in this URL contains the actual click-through URL specified as part of the action’s details. Typically, this leads to a link or file that provides more details about the action.

DecisionTime The time of the decision.

A sample response from the invocation of this service is shown below:

  • {
  • "Status": "OK",
  • "ContainerList": [
  • {
  • "Status": "OK",
  • "ContainerName": "UPlusBankWSS",
  • "RankedResults": [
  • {
  • "Group": "CreditCards",
  • "Issue": "Sales",
  • "InteractionID": "-5826878382873476460",
  • "Category": "",
  • "SubjectName": "14",
  • "CustomerCost": 0.0,
  • "ContentFormat": "Image",
  • "Label": "Signup for Platinum Rewards Card",
  • "Benefits": "The Platinum Card …",
  • "WhyRelevant": "U+ Financial Personal Card...",
  • "Direction": "Inbound",
  • "Name": "PlatinumRewardsCard",
  • "ShortDescription": "Great benefits with access to a higher credit line",
  • "GroupID": "",
  • "PaidAudienceName": "",
  • "Identifier": "/Sales/CreditCards/PlatinumRewardsCard",
  • "Placement": "Tile",
  • "Pricing": "INTEREST ...",
  • "JourneyStage": "",
  • "JourneyStep": "",
  • "EligibilityDescription": "Offer only available to U.S. residents 18 and older.",
  • "Propensity": 0.008158007388236195,
  • "AgentCompensation": 4,
  • "ClassIdentifier": "Offer",
  • "Priority": 0.05588235060941794,
  • "Channel": "Web",
  • "BundleName": "",
  • "ImageURL": "http://host:port/image.jpg",
  • "Rank": 7,
  • "BundleParent": "false",
  • "Variant": "",
  • "Treatment": "Plat__Card_Tile_02",
  • "InternalCost": 0,
  • "CampaignID": "NBA",
  • "OfferValue": 0,
  • "ClickThroughURL": "https://PM85-autotest2.pegamkt.io/prweb/PRHTTPService/PegaMKTContainer/Services/CaptureClickThrough?Px=%7Bpr%7DyB%",
  • "SubjectID": "14",
  • "Journey": "",
  • "DecisionTime": "20200805T164224.957 GMT",
  • "ContextName": "Customer"
  • }
  • ]
  • }
  • ]
  • }

Identity Management

The Web and Mobile channels support using identity matching to uniquely identify and track anonymous users when making Next-Best-Action decisions. The Container service supports using Pega's identity matching, or a third-party identity solution, depending on your requirements.

Identity matching has the following stages:

  1. Check if identity matching is enabled.
  2. Check if the SubjectID is provided.
  3. Check if the ExternalID is provided.
  4. Check if MKTLoadCustomerFromIdentityMatch is enabled.
  5. Look up SubjectID from ExternalID or MKTID.

Pega identity matching

In order to use Pega identity matching, set the MKTLoadCustomerFromIdentityMatch Dynamic System Setting to true. Once enabled, Pega will automatically generate a unique ID and place a MKTID cookie in the users' browser.

The MKTID cookie will contain the unique identifier and all interactions will be captured using this ID. If the Container service passes the SubjectID (representing identified customer), the Container service will automatically create an association between the MKTID and the SubjectID. This allows Pega to merge the anonymous and identified profiles and behaviors and make a Next-Best-Action decision based on the combined history.

Third-party matching

You can also leverage an existing third-party identity management solution with the Container service. The optional ExternalID parameter of the service is used for the third-party identifier. If only the ExternalID is provided then all interaction history will be captured using this identifier. If the SubjectID and the ExternalID are both provided, an association between these will be created and the SubjectID will be used to capture the interaction history.

Did you find this content helpful?

Have a question? Get answers now.

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