Triggering a real-time container with the Container REST service
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.
The URL pattern for this service is:
http://<host>:<port>/prweb/PRRestService/PegaMKTContainer/V3/ContainerSwagger document
To help you configure the service, you can refer to the following Swagger document: Swagger document for Container and Capture Response v3.
POST Service Request
For the POST request, the service expects a JSON Object with the following attributes:
| Name | Required | Description |
SubjectID | Optional for the Web and Mobile channels | The identifier for the specified context. |
ContextName | ✓ | 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 | ✓ | 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 | ✓ | Identifier of the channel calling the container, where the results will be rendered. To find the identifier of the channel, navigate to Customer Decision Hub tab. |
Direction | ✓ | 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 | Required | Description |
SubjectID | Optional for the Web and Mobile channels | The identifier for the specified context. |
ContextName | ✓ | The singular friendly name of the context entity that indicates the type for SubjectID. |
ContainerName | ✓ | Name of the Container to trigger. |
Channel | ✓ | Identifier of the channel calling the container, where the results will be rendered. To find the identifier of the channel, navigate to Customer Decision Hub tab. |
Direction | ✓ | 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,TileService 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 for the Container REST service
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 browser-based identity matching (such as Pega's identity matching, or a third-party identity solution), as well as server-side OAuth authentication.
Previous topic Using real-time container APIs Next topic Identity management for the Container REST service