Give the Interviewer Context About Your Product

Give the interviewer the product facts it needs to understand a participant's answer or respond to a product question during Talk. Start with a short description; connect a knowledge endpoint when it needs to look up more detail.

Add a small amount of context

1. In Project Settings, describe what the product does, who uses it, and any terms with a specific meaning.
2. In the Study's Research goal, state what you want to learn.
3. In Interview flow, add relevant facts to Private notes for the interviewer on the step that needs them.

For example:

A project is a shared inbox for one team. An owner can invite teammates; members cannot. We want to understand whether new owners can set up their first project without help.

Keep facts separate from instructions. Put “Ask what they expected before explaining the owner role” in What the interviewer should do. Private notes are not displayed to participants, but the interviewer can draw on them when speaking; do not include secrets.

Connect an existing knowledge service

Use this when you already have an HTTPS search or question-answering endpoint for your product documentation. UserTold connects one read-only endpoint per Project. It does not ingest uploaded documents or build a knowledge base for you.

1. Open Project Settings → Knowledge.
2. Enter an Action name, such as “Product help.”
3. In When to use, describe what it answers: “Use for factual questions about project roles and account limits.”
4. Choose GET or POST, enter the HTTPS URL, and add any required authentication Headers. For POST, configure the JSON body. Choose a Response path if the useful answer is nested inside the response.
5. Choose Save action. Run the test with a question whose answer you know and inspect the returned text.

Complete GET example

Suppose your existing service accepts a q query parameter and returns an answer under data.answer:

Set the action name to “Product help” and When to use to “Factual questions about project roles and account limits.” Choose GET and enter https://knowledge.example.com/search?q={{query}} as the HTTPS URL. Set Response path to data.answer.

If your service needs a token, add an Authorization header with the value Bearer YOUR_ENDPOINT_TOKEN.

Replace the endpoint and token with your service's values. For the test query “Who can invite teammates?”, the service would return:

{
  "data": {
    "answer": "Only project owners can invite teammates."
  }
}

The test should show “Only project owners can invite teammates.” If it shows no knowledge, check the HTTP result, authentication, response shape, and Response path before trying an interview.

For a POST service, use its endpoint URL and set JSON body to {"query":"{{query}}"} if that is the body it expects. Use the same Response path only if it returns the same response shape. GET and POST must both perform read-only lookups.

Available variables are {{query}}, {{page_url}}, and {{site_hostname}}. URL variables are percent-encoded; body variables are replaced inside JSON string values. Requests run server-side and configured header values do not reach the widget. Use a direct public HTTPS endpoint: redirects and private-network destinations are rejected, and responses are limited to 20 KB.

Enable it for the interview

Saving the Project action does not enable it for every Study.

1. Open the Study's Interview flow → Talk defaults → Grounded context.
2. Enable Knowledge action and save the Study.
3. If a Talk step has its own settings, open advanced options → Grounded context overrides and make sure Knowledge action inherits On or is explicitly On.
4. In that Talk step's What the interviewer should do, explain when an answer is useful: “When asked a factual question about project roles, consult Product help. If the lookup does not answer it, say so rather than guessing.”

In a script, the capability is experimental_capabilities.realtime_knowledge_query: true, at Study level or on the relevant Talk segment. The interviewer can then use query_knowledge when needed; enabling the action does not force a lookup on every turn.

Check an actual conversation

Run the saved Study and ask “Who can invite teammates?” during Talk. Confirm that the response agrees with the known endpoint answer. Check your endpoint's request log to confirm the lookup occurred; a correct answer alone does not prove the action was called. Then ask something the endpoint cannot answer and check that the interviewer does not invent a product fact.

Knowledge lookup is available during Talk. It does not provide automatic help during Observe. For usability research, let the participant try the task first and ask what they expected before explaining how the product works.

If you need public website information instead, Web search searches the current website; private or unindexed pages may be missing. Read-only page context supplies an outline of the current page. These are separate Talk sources, not document-upload options.