Strategy Message Service API

Description

The Strategy Message Service API provides a secure, OAuth 2.0–enabled interface to retrieve and manage strategy-specific messages used across different pages of a site (such as item pages, category pages, or cart pages). This service is typically used to control dynamic UI messaging associated with personalization strategies—allowing marketers and developers to update messaging in a programmatic way without requiring manual intervention in the dashboard.

Authentication to Algonomy Gateway

The authentication to the Algonomy API gateway is facilitated using OAuth2.0- grant-type client credentials.

Note: Contact your Algonomy Customer Support Team to request a client_id and client_secret for your exclusive use.

Algonomy will create client_id and client_secret for each site (configured for each customer) and will share them in the requested method.

The client_id and client_secret key are required to obtain bearer tokens for accessing the Strategy Message Service. Bearer tokens have a system-defined time-to-live (TTL) validity period. Once TTL is reached, customer systems need to request a new bearer token with the provided client_id & client_secret.

Note: The bearer token Time to Live (TTL) for the Strategy Message Service API is set at 8 hours, equivalent to 28,800 seconds. To ensure uninterrupted utilization of the service without encountering authorization failures, it is recommended to request a new bearer token every 8 hours.

Creating Tokens

Hosts

Production

Copy

https://gateway.richrelevance.com/

Staging

Copy

https://staging-gateway.richrelevance.com/

Note: You need to create different tokens for each environment. For example, tokens created for the Production environment can be used only in the Production environment. You cannot use it in the Staging environment.

To create tokens, use the request syntax below:

Copy

POST https://<host>/api/v1/oauth2/token?grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>

Note: Replace client_id and client_secret with the corresponding values provided to you by the Algonomy consultant.

Sample Request

To obtain a token for the Strategy Message Service in the Production environment.

In this example, the client_id is 5934de97c95e1ced and the client_secret is 2l9dr0jkink11ad49hg93it52d. Each customer will have a unique client_id and client_secret.

Copy

POST https://gateway.richrelevance.com/api/v1/oauth2/token?grant_type=client_credentials&client_id=5934de97c95e1ced&client_secret=2l9dr0jkink11ad49hg93it52d

Sample Response

Copy

{
"token_type": "bearer",
"access_token": "M6w0M0K9QbQGHC8xgvb91ZgLMKaW4xOd",
"expires_in": 28800 
}

Note: The "expires_in" value returned in the OAuth token response indicates the duration of the bearer token's validity in seconds. This directly corresponds to the token's Time to Live (TTL). For example, if "expires_in" is set to 28,800 seconds, the token remains valid for exactly 28,800 seconds, which is 8 hours. After 8 hours, the token will expire, and a new token will need to be requested to continue accessing the API.

Example with cURL:

Copy

curl -X POST "https://gateway.richrelevance.com/api/v1/oauth2/token" -d "grant_type=client_credentials" -d "client_id=5934de97c95e1ced" -d "client_secret=2l9dr0jkink11ad49hg93it52d"

Requests to Algonomy Gateway Require the Bearer Token

For every API call, the bearer token value that was obtained in the Creating Tokens step should be included as part of the Authorization header.

Copy

https://<host>/strategy-message-service/v1/<apiKey>
Authorization: Bearer <tokenValue>

Example: To save or update strategy messages for a specific site, use the following API request:

Copy

POST https://gateway.richrelevance.com/strategy-message-service/v1/<apiKey>/save
Authorization: Bearer M6w0M0K9QbQGHC8xgvb91ZgLMKaW4xOd

Example with cURL:

Copy

curl -H "Authorization: Bearer <tokenValue>" "https://gateway.richrelevance.com/strategy-message-service/v1/<apiKey>?strategyName=similar_items_v2&pageType=item_page"

API Endpoints

GET API – Retrieve Strategy Messages

Fetches all strategy messages published to production for all locales based on the given strategyName and pageType combinations.

Multiple strategyName and pageType values can be passed in a single request. Both parameters are mandatory. Missing or invalid values will result in an error.

strategyName values must be URL-encoded.
pageType values must be passed as lowercase, underscore-separated strings (for example, home_page, item_page, category_page, email_page).

Endpoint

GET /strategy-message-service/v1/<api_key>

Path Parameter

Parameter	Required	Description
apiKey	Yes	The API key of the site for which strategy messages are being fetched.

Query Parameters

Parameter	Required	Description
strategyName	Yes	List of strategy names to filter the messages. Strategy names should be encoded in case of special characters while sending in Query params.
pageType	Yes	List of page types to filter the messages. Page types must be passed as lowercase, underscore-separated strings (for example., home_page, item_page, category_page, email_page).

Ensure that valid strategyName, pageType, and apiKey values are provided; otherwise, the request will return an error response.

Sample Request

Copy

curl --location 'https://gateway.richrelevance.com/strategy-message-service/v1/<api_key>?strategyName=similar_items_v2&pageType=item_page&pageType=category_page' \
--header 'Authorization: Bearer <access_token>'

Sample Response

Copy

[
  {
    "strategyName": "similar_items_v2",
    "pageType": "item_page",
    "localeMessages": [
      {
        "languageTag": "default",
        "strategyMessage": "Similar Products"
      },
      {
        "languageTag": "fr-CA",
        "strategyMessage": "Produits Similaires"
      }
    ]
  },
  {
    "strategyName": "similar_items_v2",
    "pageType": "category_page",
    "localeMessages": [
      {
        "languageTag": "default",
        "strategyMessage": "Alternative Products"
      },
      {
        "languageTag": "fr-CA",
        "strategyMessage": "Autres Produits"
      }
    ]
  }
]

Note: "default" in languageTag refers to the default strategy message.

POST API – Save Strategy Messages

Saves and publishes strategy messages to production for the specified strategy name and page type combinations across all locales. Supports bulk requests, where each combination is processed independently.

The default message must use languageTag as default, while localized messages should use valid locale identifiers (for example., fr-CA). Failed entries are skipped, and the response includes a summary of successes and errors.

Endpoint

POST /strategy-message-service/v1/<api_key>/save

Description

Saves or updates strategy messages for a given site ID.

Sample Request

The request body follows the same JSON format as the GET API response.

Copy

[
  {
    "strategyName": "similar_items_v2",
    "pageType": "item_page",
    "localeMessages": [
      {
        "languageTag": "default",
        "strategyMessage": "Similar Products"
      },
      {
        "languageTag": "fr-CA",
        "strategyMessage": "Produits Similaires"
      }
    ]
  },
  {
    "strategyName": "similar_items_v2",
    "pageType": "category_page",
    "localeMessages": [
      {
        "languageTag": "default",
        "strategyMessage": "Alternative Products"
      },
      {
        "languageTag": "fr-CA",
        "strategyMessage": "Autres Produits"
      }
    ]
  }
]

Sample Response

Copy


            {
            "successCount": 2,
            "skippedCount": 0,
            "errorDetails": []
            }

Response Behavior

Bulk processing supports partial success.
If any error occurs for a strategy and page type combination, it is skipped and processing continues.
Only valid inputs are published.

Error Handling

400 Bad Request – Missing or invalid request body
Invalid strategyName – Skipped with error detail
Invalid pageType – Skipped with error detail
Invalid languageTag – Entire combination is skipped

Usage Notes and Best Practices

Request Guidelines

Ensure all required parameters are provided
URL-encode query parameters where necessary
Use valid API key and OAuth token

Input Handling

Use valid strategy names and page types configured for the site
Ensure locale values are valid (for example, fr-CA)
Use "default" for default messages

Response Handling

Handle partial success responses appropriately
Review errorDetails in the response for skipped entries
Validate successful updates using GET API