Content Recommendation with Kentico Cloud

Personalize content using our integrated Recommendation engine.

Kentico Cloud Recommendation API

  • What is it?
    It's an API that you call when you want to recommend content in Kentico Cloud.

  • What does it do?
    It autonomously recommends relevant content items for your visitors and the content they are currently visiting.

  • How does it work?
    It uses machine learning to analyze your content and (optionally) visitor behavior to learn which pieces of content work well together and what content is most relevant for a specific audience.

  • Is it complicated to use?
    No, it's very simple – you need only a single API call to get your recommendations. All the tracking and decision making is being made by the underlying artificial intelligence.

Additional Features

  • Real-time Recommendation as a service
    Our API/(.NET) SDK returns the recommendations immediately after a visitor performs any action on your website or in your app.

  • Domain independence
    The underlying recommendation system is successfully being used to recommend news, cultural events, books, medical products, job offerings, and many more. It is easily adaptable to any domain.

  • Research and improvements
    Machine learning algorithms are continuously managed, tested, and improved by AI.

  • Flexibility and optimization
    There are many options to customize the outcome of the recommendation by filtering or boosting your results.

  • Optional Event Tracking
    Track all the different actions your visitors finish on your website and make your recommendations even better.

How does it all work together?

  1. A visitor arrives at your website/opens your application.
  2. Immediately, you request recommended content for this user by calling our Recommendation API. You provide the API with:
    • Identification of the user (hash/token id, optionally location, device, etc.).
    • What content they are viewing right now.
    • How many content items of a specific content type you want to recommend.
  3. The AI processes all the information and decides, based on other content interactions and content similarity, what additional content your visitor might be interested in.
  4. In the response, you receive a list of items to be recommended to the current visitor.

Recommendation Setup

Recommendations are tied to content types - you select what type of content items you want to recommend. The system automatically tracks user-item interactions and recommends the
best items for the current visitor and content item.

As this feature is currently in BETA, the setup has to be performed manually by one of our developers. Here is what we need to know:

  • Project ID
  • List of content types you want to recommend
  • List of properties of each content type you want the AI to take into account while recommending your content.

Send us an email with all the info mentioned above and we'll set up your recommendation database, populate it with already published content and send you an access token for the Recommendation API.

After that, you'll be able to request content recommendations through our SDK or directly through the API.

How to Access the API

Currently, there are two ways to access the content recommendation functionality.

  1. Use our Recommendation SDK for .NET
    There are currently two versions - one for .NET MVC 4.6 and one for .NET CORE 2.0+. The SDKs are private, but you can find the newest versions of the NuGet packages on G-drive.

  2. Connect to the Recommendation API directly
    If you prefer this approach, you can connect to the API from any REST client, just don't forget the authentication key and a correct token authentication header. See our API reference for more details.

Automatic updates

You can create a webhook pointing to one of our services that will handle automatic updates of all your recommended content. This will allow you to recommend new content immediately after it is published. Contact us for details.


The code below shows how to get 2 recommended articles for a visitor who is currently reading your article current_codename.

var recommendationClient = new RecommendationClient("recommendation_token", 5);
var recommendedArticles = await recommendationClient.GetRecommendationsAsync(
  			contentType: "article",
  			limit: 2);

Boosting and Filtering

As mentioned before, you can also filter and boost recommended results. The example below returns only articles written for a specific persona while also making it more likely for newer articles to be recommended.

var recommendationClient = new RecommendationClient("recommendation_token", 5);
var lastMonth = TimeSpan.FromDays(30).Milliseconds;
var recommendedArticles = await recommendationClient.GetRecommendationsAsync(
			contentType: "article",
			filterQuery: "\"personas=Barista\" in 'properties'", 
  			$"if 'lastupdated' >= now() - {lastMonth} then 2 else 1", 
			limit: 2);

A correct usage of filtering and boosting can be quite advanced and may seem complicated at first. Before we create more detailed documentation on this subject, don't hesitate to contact us and we will help you with your filters/boosters.

Suggestions for Implementation

  1. Always call the API asynchronously and set up a timeout for your client. The API is in beta and can occasionally take a longer time to get your response -- don't let it ruin your viewers' experience.
    When using MVC, we highly recommend rendering recommendations asynchronously by an ajax call while the rest of the page is being rendered independently.

Event Tracking (optional)

As said before, simply requesting your recommendation will track a default visitor-content interaction (visit), however, if you wish you can log visitor-content interactions by yourself. This can be achieved simply through the same SDK/API you'd be already using for the recommendations - see the API reference for details.

There are 3 types of interactions that can be logged:

  1. Visit - standard page visit,
  2. Conversion - further unspecified visitor action that benefits your business in some way (e.g. purchase, form submit, etc.)
  3. Portion View - optional call that specifies how big of a chunk of the page has the current visitor already read. Partial views may be logged multiple times during a single page visit as the visitor scrolls down the page and only the last one will be acknowledged by the AI. Using this feature will further improve your recommendations, although it may be more challenging to implement.

Contact us

If you need any help with content recommendation or have any questions or requests regarding this documentation, please contact us using the chat button in bottom right.