Skip to main content
Version: 26.01

Star Rating - Create Widget

Endpoint​

/i/feedback/widgets/create

Overview​

Creates a new star-rating widget.

Authentication​

Pass api_key or auth_token as a query parameter, or send countly-token as a header. See Authentication.

Permissions​

Requires star_rating Create permission.

Request Parameters​

ParameterTypeRequiredDescription
api_keyStringConditionalRequired if auth_token is not provided.
auth_tokenStringConditionalRequired if api_key is not provided.
app_idStringYesApp ID the widget belongs to.
statusBoolean/StringYesActive flag for the widget.
popup_header_textStringNoHeader text of the feedback popup.
popup_comment_calloutStringNoText of the comment field.
popup_email_calloutStringNoText of the "contact me by e-mail" option.
popup_button_calloutStringNoText of the popup button.
popup_thanks_messageStringNoText of the thank-you message.
trigger_positionStringNoPosition of the feedback trigger button.
trigger_sizeStringNoSize of the feedback trigger button.
trigger_bg_colorStringNoBackground color of the trigger button.
trigger_font_colorStringNoFont color of the trigger button.
trigger_button_textStringNoText of the trigger button.
hide_stickerBoolean/StringNoHide the trigger button by default.
target_pagesArray/StringNoJSON array string of pages to show the widget on (fallback ["/"]).
target_pageStringNoTarget page setting.
targetingObject/StringNoJSON object string with targeting conditions.
linksArray/StringNoJSON array string of consent links. A link whose linkValue does not start with http:// or https:// is saved with an empty linkValue.
consentBooleanNoConsent flag.
finalTextStringNoFinal text of the widget.
contact_enableBooleanNoEnable the contact option.
comment_enableBooleanNoEnable the comment field.
ratings_textsArray/StringNoJSON array string of rating labels. Defaults to five labels from "Very dissatisfied" to "Very Satisfied".
rating_symbolStringNoSymbol used for ratings.
logoStringNoLogo file name.
logoTypeStringNoLogo type.
globalLogoBooleanNoUse the global logo.
internalNameStringNoInternal widget name.
appearanceObjectNoAppearance settings.
showPolicyStringNoShow policy setting.

Examples​

Create a widget​

/i/feedback/widgets/create?
  api_key=YOUR_API_KEY&
  app_id=6991c75b024cb89cdc04efd2&
  status=true&
  popup_header_text=How was your experience?&
  target_pages=["/","/pricing"]

Response​

Success Response​

HTTP status 201.

{
  "result": "Successfully created 6256d161e8faa7b449e2dd6b"
}

Response Fields​

FieldTypeDescription
resultStringSuccessfully created followed by the ID of the new widget.

Error Responses​

  • 400
{
  "result": "Invalid params: ..."
}
  • 400
{
  "result": {
    "error": "Failed to set cohort",
    "widgetId": "6256d161e8faa7b449e2dd6b"
  }
}
  • 500

The database error message is returned in result.

Standard authentication/authorization errors from create validation can also be returned.

Behavior​

  • Applies the same field preprocessing as Edit Widget, then validates the payload.
  • New widgets start with zero shown count, zero ratings, and the afterPageLoad show policy.
  • If the Cohorts plugin is enabled and targeting is provided, a cohort is created for the widget and linked to it.

Impact on Other Data​

  • Inserts one widget into countly.feedback_widgets.
  • May create a cohort in countly.cohorts (when the Cohorts plugin is enabled).
  • Writes an audit event to system logs.