GraphQL: NPS and surveys

Client operations for NPS settings and responses (score 0 to 10) and for survey definitions and responses.

NPS and surveys share a pattern with notifications: the widget reads the configuration, decides locally whether to show (device, URL rules, timing, throttling — the same passesWidgetTargeting model), then submits the visitor response. Appearance for surveys is resolved from account appearance.survey defaults unless the survey stores a custom override.

NPS settings

query {
  client_getNpsSettings {
    enabled
    showOnDesktop
    showOnMobile
    showOnTablet
    requireScoreConfirmation
    enableFeedback
    firstTimeDelay
    showAgainDelay
    showAfterDeclineDelay
    showDelay
    hideDelay
    throttling
    urlWhitelist { id url settings { enabled showDelay hideDelay } }
    urlBlacklist
    messagesMode
    messages {
      general
      lowScore
      highScore
      closeButton
      confirmButton
      declined
    }
  }
}

Delays are configured in the admin app: showDelay and hideDelay in seconds; firstTimeDelay, showAgainDelay and showAfterDeclineDelay in days. throttling is the percentage of visitors who can be asked.

Submitting an NPS response

The score is an integer from 0 to 10. A visitor who closes the widget without scoring is recorded as declined. feedback carries the optional comment. The widget also sends context fields such as origin, device, OS, browser, language and referrer.

mutation {
  client_saveNpsResponse(
    response: {
      score: 9
      feedback: "Loved the onboarding"
      origin: "https://example.com/pricing"
      device: "desktop"
    }
  ) {
    id
    score
  }
}

mutation {
  client_updateNpsResponse(id: "RESPONSE_ID", response: { feedback: "Added a comment" }) {
    id
    feedback
  }
}

Monthly response limits

NPS responses are limited per plan: Free 50, Standard 5,000, Premium 50,000 per month. Responses beyond the limit are not accepted from your site. See Plans and limits.

Surveys

query {
  client_getSurveys {
    id
    name
    state
    enabled
    showOnDesktop
    showOnMobile
    showOnTablet
    showDelay
    hideDelay
    firstTimeDelay
    showAgainDelay
    showAfterDeclineDelay
    throttling
    urlWhitelist { id url settings }
    urlBlacklist
    questions
    appearance
  }
}

questions and appearance are JSON. Question types are binary, choice, numeric and text, each with optional follow-up questions and routing rules based on the answer.

Submitting a survey response

mutation {
  client_saveSurveyResponse(
    response: {
      surveyId: "SURVEY_ID"
      completed: true
      answers: { QUESTION_ID: "Yes" }
      origin: "https://example.com/pricing"
    }
  ) {
    id
    completed
  }
}

Set declined: true when the visitor closes the survey without answering. The answers JSON maps question IDs to values.

Subscriptions

client_npsSettingsUpdated
client_surveyUpdated, client_surveyDeleted

Do not submit fake responses

Response endpoints are meant for the widget UI. Scripts that submit scores on behalf of visitors distort your data and count against your NPS response limit.