What can we help you with?

e.g. Getting Started, Build Dashboards

Top

AI Recommendations

Follow

With this API, you can request recommendation content that is generated for one widget or one dashboard (first three widgets on the dashboard) in a customer account. The result returned from the recommendations API is a JSON object that contains the recommendation text associated with the selected mode.


Pre-requisites:

  • AI Service enabled for customer account
  • AI Service enabled for user the clientId and clientSecret is tied to
  • Permission to assets listed
  • Permission to use model selected (if using openAI, key needs to be configured, customer setting must allow openAI for this feature)Parse suggestion
  • Returns results of parsed NLP query
     

Get Recommendations for a Widget

Query

GET /api/1.0/widgets/<objectId>/insights/aiRecommendations?contentFilters={content_filters}

ParameterRequiredComments
<objectId>Yeswidget id
contentFiltersNo

The contentFilter is a JSON array of the field name, value, and operator of filters to be applied to the widget, which allows using of the same widget as a kind of template and generates different recommendations based on configured filters.

[{"fieldName": "page", "values":["Products"], "operator":"="}]

Available Operators for Content Filters: "Greater than" (>), "Greater than or equals" (>=), "Less than" (<), "Less than or equals" (<=), "Not Equals" (!=), "Equals" (=), "Contains", "Does Not Contain", "Range", "like", "not like", "in", "not in", "regexp", "is null", and "is not null"

Note: All operators are applied to all field types, it depends on the field type for which operator they are required and some operators may not be applied.

contextNoA custom prompt used to guide the recommendation output. If a recommendation widget id is passed through, that widget's configured prompt is used instead. Otherwise, this value replaces the default prompt.
limitNoNumber of recommendations to return. Accepts values from 1 to 10. Defaults to 5.

Response

HTTP StatusResponse
200 OK

Output example:

{
  "stats": {
    "dataTruncated": true,
    "rowsCountUsed": 147,
    "rowsCountTotal": 810,
    "widgetCount": 1,
    "duration": 50066
  },
  "dataTruncated": true,
  "rowsCountUsed": 147,
  "rowsCountTotal": 810,
  "widgetCount": 1,
  "rec": [
  {
    "insight": "Marketing emails have significantly higher sent volumes and conversions compared to transactional emails.",
    "action": "Focus more resources on marketing campaigns, especially those with high conversion rates."
  },
  {
    "insight": "Emails sent around Christmas (Dec 25) show higher engagement metrics like opens and clicks.",
    "action": "Plan holiday themed campaigns for peak seasonal periods to boost performance."
  },
  {
    "insight": "Facebook and Target consistently have the highest number of conversions across both marketing and transactional emails.",
    "action": "Prioritize partnerships with these customers or replicate their successful strategies."
  },
  {
    "insight": "Transactional 'Account' type emails tend to have lower bounce rates compared to other types.",
    "action": "Use account related emails for critical communications where delivery reliability is important."
  },
  {
    "insight": "Marketing campaigns with discounts (e.g., '30% off Limited Sale') show higher click through rates.",
    "action": "Incorporate promotional offers in marketing emails to drive more engagement."
  }
]
}
400 BAD_REQUEST
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
  • Something went wrong during the recommendation processing
401 UNAUTHORIZED
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN
{
    "message": "Current user is not allowed to use natural language processing",
    "documentation_url": "https://knowi.com/docs/managementAPI.html"
}


Common error details:

  • Current user is not allowed to use recommendations
curl -i -X GET -H "Authorization: Bearer CRA31ajr5KeV6zH5OjeoipkerP0w56O3vFVVaNRWMTCQie" 'https://staging.knowi.com/api/1.0/widgets/46871/insights/aiRecommendations?context=generate%20recommendations%20for%20general%20public%20and%20oakland%20residents&limit=10'


Get Recommendations for a Dashboard

Query

GET /api/1.0/dashboards/<objectId>/insights/aiRecommendations?contentFilters={content_filters}

ParameterRequiredComments
<objectId>Yesdashboard id
It will take the first 3 widgets with datasets (from top to bottom) and provide recommendations. 
contentFiltersNo

The contentFilter is a JSON array of the field name, value, and operator of filters to be applied to the dashboard, which allows using of the same dashboard as a kind of template and generates different recommendations based on configured filters.

[{"fieldName": "page", "values":["Products"], "operator":"="}]

Available Operators for Content Filters: "Greater than" (>), "Greater than or equals" (>=), "Less than" (<), "Less than or equals" (<=), "Not Equals" (!=), "Equals" (=), "Contains", "Does Not Contain", "Range", "like", "not like", "in", "not in", "regexp", "is null", and "is not null"

Note: All operators are applied to all field types, it depends on the field type for which operator they are required and some operators may not be applied.

contextNoA custom prompt used to guide the recommendation output. If a recommendation widget id is passed through, that widget's configured prompt is used instead. Otherwise, this value replaces the default prompt.
limitNoNumber of recommendations to return. Accepts values from 1 to 10. Defaults to 5.

Response
 

HTTP StatusResponse
200 OK

Output example:

{
  "stats": {
    "dataTruncated": false,
    "rowsCountUsed": 810,
    "rowsCountTotal": 810,
    "widgetCount": 1,
    "duration": 0
  },
  "dataTruncated": false,
  "rowsCountUsed": 810,
  "rowsCountTotal": 810,
  "widgetCount": 1,
  "rec": [
  {
    "insight": "Marketing emails have significantly higher sent volumes and conversions compared to transactional emails.",
    "action": "Focus more resources on marketing campaigns, especially those with high conversion rates."
  },
  {
    "insight": "Emails sent around Christmas (Dec 25) show higher engagement metrics like opens and clicks.",
    "action": "Plan holiday-themed campaigns for peak seasonal periods to boost performance."
  },
  {
    "insight": "Facebook and Target consistently have the highest number of conversions across both marketing and transactional emails.",
    "action": "Prioritize partnerships with these customers or replicate their successful strategies."
  },
  {
    "insight": "Transactional 'Account' type emails tend to have lower bounce rates compared to other types.",
    "action": "Use account-related emails for critical communications where delivery reliability is important."
  },
  {
    "insight": "Marketing campaigns with discounts (e.g., '30% off Limited Sale') show higher click-through rates.",
    "action": "Incorporate promotional offers in marketing emails to drive more engagement."
  }
]
}
400 BAD_REQUEST
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
  • Something went wrong during the recommendation processing
401 UNAUTHORIZED
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN
{
    "message": "Current user is not allowed to use natural language processing",
    "documentation_url": "https://knowi.com/docs/managementAPI.html"
}


Common error details:

  • Current user is not allowed to use recommendations
 curl -i -X GET -H "Authorization: Bearer HEREISYOUR_BEARER" 'https://www.knowi.com/api/1.0/dashboards/197821/insights/aiRecommendations?contentFilters=%5B%7B%22fieldName%22%3A%22page%22%2C%22values%22%3A%5B%22Products%22%5D%2C%22operator%22%3A%22%3D%22%7D%5D'

 

Was this article helpful?
0 out of 0 found this helpful
Return to top

Related articles