Skip to main content

How to Use Social Proof Experience Output API - Item Page

How to Use Social Proof Experience Output API - Item Page

Social Proof APIs help to display dynamic social proof messages, the details about how to use these APIs are described in the following sections:

How to obtain API Key

  1. Log in to Omnichannel Personalization.
  2. On the Omnichannel Personalization Dashboard page, on the left navigation rail, click the customer site name dropdown list and then select the required client name.
  3. Click  available next to the customer site name dropdown list. The Site-info window is displayed.

  4. From the Site-info window, copy the API Key and save it to your drive.

Request Call

GET method is used to get the responses.

GET /rrserver/api/engage/spMessages?apiClientKey={apiClientKey}&apiKey={apiKey}&sessionId={sessionId}&placements=list_page&p={pId1|pId2}&userId={userId}&rcs={remoteCookieStoreValue}

Required Parameters:

  • All target API parameters

  • All experiences API parameters

  • All social proof metrics API parameters (apiKey, apiClientKey, productId)

Request Call Parameters

The following parameters are used in social proof API.

Name Required or Optional Description



Valid API key corresponding to a particular site

apiClientKey Required

Valid API client key for a particular site

productId or p Required

Unique ID (external ID) for a product. This should be a key to look up in the catalog.

Note: If the specified Product ID is not present in the Personalization catalog, the system will not accept the request.

Used by

  • Social Proof API

    one or more external productIds separated by pipe delimiter.

  • Targeting API

    For item page, single productId will be there.

    For list/cart/category page, we can provide list of productIds separated by '|' delimiter.

placements Required

This pagetype is selected as a context in social proof experience.

For example: item_page, cart_page, and category_page.

sessionId or s Required

Used by all APIs

Identifies a single visit by a customer. Sessions are used by behavioral models (to scope user behavior in a shopping session) and reporting metrics.

Example: sessionId=93484

userId or u


Used by trackevent API



Algonomy Cookie String. This is the encrypted Algonomy cookie for the user associated with the API request. It should be passed exactly as it was received in a prior API response.

Clients should ensure to preserve the 'rcs' value just as it was served. The 'rcs' parameter is always alphanumeric and case-sensitive, with the token value including a mix of uppercase letters, lowercase letters, and numbers.

Note: The 'rcs' parameter allows merchants to effectively provide the Algonomy platform access to a user's Algonomy browser cookie by acting as a cookie proxy (or cookie pass-through). This process involves the merchant reading and writing a user's Algonomy browser cookie and passing it to and from Algonomy via the server-side API.



The category ID of the category the merchant wants to investigate. The value must match the external ID provided by the merchant to Algonomy for the category.

Example: categoryId=902312

rid Optional

Region ID. It must be consistent with the ID used in the product region feed.

Example: rid=Switzerland-France



Channel ID is used by some Algonomy reports to differentiate channels such as mobile or desktop.

Example values are WEB, WEB_PHONE, WEB_TABLET. It can be any API client key that an Algonomy consultant has set up for a customer.



The brand featured on the page. Used to set the seed for brand-seeded strategies, such as Brand Top Sellers.

Example: fpb=Microsoft



Supply user segments. Used for segment-targeted campaigns. List each segment using the format segment_number:segment_name, and then use the pipe "|" character to separate segments. You must pass both the segment ID and a segment name for each segment.

Example: sgs=101:NewUser|202:Male



Identifies the language requested using the language code.

Example: &lang=sv-SE

  • Notes:

    The 'lang' parameter is supported and utilized based on the setup configured for event metrics.

  • For more details on setting up the event metrics, see Event Metric Setup.
  • For more details on 'lang' parameter, see Language Parameter.


Sample Social Proof API Request and Response

API Request

API Response

  "dynamicSocialProofMessages": [
      "experienceId": xxxx,
      "variationId": xxxx,
      "locationSelector": "AboveATC",
      "displayDuration": 5000,
      "displayInformationList": [
          "productId": "xxx_xxx-xxxx-xxxx-xxx",
          "messageList": [
              "count": 576,
              "finalMessage": "576 people purchased today",
              "threshold": 1,
              "order": 1,
              "messageText": "@usercount people purchased today"
              "count": 612,
              "finalMessage": "612 people have added to cart today",
              "threshold": 1,
              "order": 2,
              "messageText": "@usercount people have added to cart today"
              "count": 16119,
              "finalMessage": "16119 people viewed today",
              "threshold": 1,
              "order": 3,
              "messageText": "@usercount people viewed today"
      "importance": 1,
      "multipleMessagesEnabled": true
  "error": null

Response Metrics Description

  • experienceId: It is the unique ID available for an experience.

    For example: (In this URL, 8060 represents the experience ID).

  • variationId: It is the unique ID available for a variation under the experience.

    For example: (In this URL, 5385 represents the variation ID.

  • locationSelector: It is the selector of the element for which the social proof message is inserted on the page. To place the message at the right location, it is important to identify the right UI component & identifier and use that parameter for inserting the social proof message. For a given location selector, the highest importance social proof experience will be considered.

  • displayDuration: It is the duration for each social proof message specified in milliseconds when multiple messages are enabled. Default value is 5000 milli seconds (5 seconds).

  • count: This is the user count or event count selected as part of the social proof experience setup.

  • messageText: This is the message text defined as part of social proof experience for each message type (metric & interval).

  • threshold: This is the threshold defined as part of the social proof experience for each message type (metric & interval).

  • order: This is the order in which social proof messages are to be displayed. (In case of multiple messages enabled). In case of multiple messages disabled, it will pick the message with the highest order that meets the threshold.

  • Final message: This is the final social proof output message. It is based on the text with user count or event count parameter replaced by count value.

Response Codes Description

Code Description


Bad request because of wrong parameter name or value

400 Invalid API key or invalid event type
200 Successful operation; returns SP metrics

How Social Proof Experience Output API Works

Using social proof setup configurations for server side or mobile app through an API to know what to show in a given variation, so that the user only needs to define how to display the social proof message.

  • Focuses on active Social Proof experiences - those currently active or Evergreen.

  • The Importance of the experience plays a key role when there are multiple conflicting experiences in a given context.

    • Automatically picks the experience with highest Importance when multiple experiences share the same location selector.

    • If the location selector is null, It picks the highest importance experience and show it as part of the response.

    • If the location selector and importance are the same, then it picks a message randomly.

  • Identifies the right experience/variation based on context and segment parameters passed from the API call.

  • Identifies the threshold based on the user count or event count parameter from the message text.

  • Identifies the event count or user count through the SP API for the given product and identify the final text to be shown.

  • Perform the following action when the “Display Multiple Messages” option is enabled or disabled:

    • If the ''Display Multiple Messages'' option is enabled, then identify all the messages that are meeting the threshold and defined to show all the messages as part of the response. This includes the following:

      • Message Text, Priority, and display Interval

      • Event count/User count based on what is defined in the text.


    • If the ''Display Multiple Messages'' option is disabled (single message scenario), then identify the highest priority message meeting the threshold that is defined to show the message as part of the response. This includes the following:

      • Message Text

      • Event count/User count based on what is defined in the text.

  • For category/list page templates, multiple product IDs can be passed. However multiple messages cannot be provided for a single product when multiple products are passed. It is a limitation of social proof API.

    For more details about how to set up the social proof experience, refer to Social Proof User Guide.

  • Was this article helpful?