Conversational surveys

Text conversations are available in production and development, subject to the workspace's AI settings and allowance. Production commands use the default API; add --dev only when working with a development site.

Pip asks the opening question and relevant follow-ups. Normal completion sends the visitor’s own words immediately and shows the thank-you. Text conversations start with the opening question, without an AI introduction or notes overview. If a connection fails or the interview is interrupted, the words stay available for an explicit recovery Send.

Where a conversation fits

A conversation occupies the whole survey, or starts one version of an experiment at the start. It cannot follow a rating or another question, and it has no next question. An experiment decides the version before the invitation appears: the standard version shows its usual invitation, while the conversation version shows Pip and Message.

The editor has Questions, Targeting, and Look & words. In Questions, write the goal and opening, optionally add up to three topics and context, and choose the depth. Topics guide useful follow-ups; they are not required boxes for the visitor to fill.

Quick feedback is the default. A clear answer may need no follow-up.

Adjust limits changes the follow-up and time ceilings. Pip stops earlier when the answer is clear or the visitor declines. Choose a longer invitation estimate for longer conversations.

A complete definition

The wire format remains kind: "text" with a versioned conversation setting. The opening question is prompt. Save this complete file as conversation.json:

{
  "schema_version": 1,
  "name": "Scheduled reports feedback",
  "content": {
    "schema_version": 1,
    "title": "Scheduled reports",
    "description": null,
    "thank_you": null,
    "questions": [
      {
        "id": "reports",
        "kind": "text",
        "prompt": "What were you hoping scheduled reports would do for you?",
        "required": false,
        "max_length": 10000,
        "conversation": {
          "schema_version": 1,
          "goal": "Understand how customers use scheduled reports and what gets in the way",
          "topics": [
            { "id": "use", "description": "What they do with exported reports" },
            { "id": "obstacle", "description": "What got in the way" }
          ],
          "preset": "quick",
          "input": "text_only",
          "language": "prompt",
          "context": "Reports can be emailed weekly or monthly.",
          "invitation": {
            "heading": "Can Pip ask you about scheduled reports?",
            "minutes": null,
            "decline_forever": true
          },
          "thank_you": {
            "title": "Thanks, that really helps!",
            "text": "Your answers went to the team."
          }
        }
      }
    ]
  },
  "rules": {
    "schema_version": 1,
    "audience": { "type": "always" },
    "triggers": [{ "type": "page_load" }],
    "frequency": { "mode": "site_default" }
  },
  "sampling_percent": 100,
  "priority": 0,
  "enrollment_epoch": "reports-conversation-v1"
}

Use input: "text_only" to remove Talk and the microphone. Optional overrides are max_followups (0–6), stop_new_questions_after_seconds (10–180), and voice_session_limit_seconds (15–180). Stop new questions before the voice limit. Optional greeting holds up to 500 characters and is used for voice only. The invitation heading allows 80 characters; thank-you title and text allow 80 and 200.

Validate and save with the project-local CLI. Replace the UUID placeholders with your workspace and site IDs. Add --dev to each command for the development API.

npx --no-install userreason prompt validate --workspace WORKSPACE_UUID --site SITE_UUID --file conversation.json
npx --no-install userreason prompt create --workspace WORKSPACE_UUID --site SITE_UUID --file conversation.json

Saving a draft does not publish it. Review the returned edit link and publish the approved survey through the existing prompt publish command with its current revision. Preserve question IDs and enrollment_epoch during normal edits.

Test before publishing

The dashboard preview starts in Scripted mode. Pre-written visitor scenarios exercise short and detailed answers, vague complaints, positive feedback, early exit and off-topic input without model use. Live tests use the real controller and the workspace allowance. Neither creates visitor responses.

Pip's log shows the sequence and why a follow-up or finish decision happened. Verify automatic completion, explicit recovery Send, connection failure, time limits and plain-text fallback. The timer measures the active interview, and the log labels each decision and message. Conversational voice remains unavailable in previews as well as live surveys.

Voice and languages

Conversational voice is pre-GA and unavailable. Visitors currently use typed input, including for surveys whose saved definition still contains input: "text_or_voice". Keep new definitions on input: "text_only". Voice-specific settings remain in the schema for compatibility, not as a promise of availability.

Pip follows the survey language. Interface translations remain subject to review; language support does not imply that conversational voice is available.

Allowance and fallback

Workspace AI allowance is shared by typed conversations and live editor tests. A notice appears at 80%. At exhaustion, conversations show the opening question as a plain text answer instead. Standard surveys keep working. Workspace owners/admins can pause conversations; site editors can maintain About your product.

npx --no-install userreason workspace ai get --workspace WORKSPACE_UUID --site SITE_UUID
npx --no-install userreason results conversations PROMPT_UUID --workspace WORKSPACE_UUID --site SITE_UUID
npx --no-install userreason conversation get CONVERSATION_UUID --workspace WORKSPACE_UUID --site SITE_UUID

Use workspace ai set --file SETTINGS.json for a requested settings change. Omitted fields keep their values. The voice_enabled setting is retained for compatibility; setting it to true cannot enable pre-GA conversational voice. Site product context requires --site. The legacy {"product_context":"Facts about this product."} remains supported. Structured settings use {"product_context_settings":{"name":"Acme","description":"Scheduled reports","audience":"Operations teams","terms":"Use report, not export job","enabled":true}}. The sharing switch controls whether product facts enter new conversation sessions. Money and large usage counts are decimal strings, preserving their precision.

Reading answers

The accepted answer contains the visitor’s own words. The transcript records automatic versus explicit submission, what Pip and the visitor said, typed/spoken origin, recorded lines versus live follow-ups, and interrupted playback. Historical reviewed answers preserve their original note and any edits. Results include started/seen counts, completion outcomes, median duration, follow-up counts and cited topic coverage.

Any AI summary or topic analysis is marked generated and includes supporting turn IDs. It is not a replacement for the visitor's answer. In an experiment, compare assigned versions, including plain-text fallbacks, rather than treating people who voluntarily used voice as a random cohort.