> ## Documentation Index
> Fetch the complete documentation index at: https://docs.listen.land/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting ListenLand: Fix Common Issues Fast

> Step-by-step solutions for the most common problems in ListenLand — covering interviews, voice mode, webhook delivery, and account access.

If something isn't working as expected, the sections below cover the most common issues and how to resolve them.

## Interview Issues

<AccordionGroup>
  <Accordion title="My interview isn't accepting responses">
    Check that your interview's status is set to **Active**. Interviews in Draft or Inactive status will not accept new conversations — respondents who open the link will see a message that the interview is unavailable.

    To activate your interview:

    1. Open the interview from your dashboard.
    2. Navigate to **Settings**.
    3. Set the status to **Active** and save.
  </Accordion>

  <Accordion title="Respondents are getting an access denied error">
    If your interview is configured to use **Access Code** mode, respondents must enter the correct code alongside the interview link. Common causes:

    * The code was not included in the link you shared — make sure you send both the URL and the access code together.
    * The respondent mistyped the code — codes are case-sensitive.
    * The code was regenerated after the original was shared — check the current code under **Settings → Access**.

    If you don't need restricted access, you can switch the interview to **Open** mode in settings.
  </Accordion>

  <Accordion title="The AI isn't asking relevant follow-up questions">
    The quality of the AI's follow-up questions depends heavily on the **Overview** field of your interview. A vague or empty overview gives the AI little context to probe meaningfully.

    To improve follow-up quality:

    * Add a clear description of your research goal (e.g., *"We're exploring why enterprise customers churn in the first 90 days"*).
    * Describe who the respondents are and what context they bring.
    * Increase the **follow-up depth** setting to Medium or High on individual questions where you want deeper exploration.
  </Accordion>
</AccordionGroup>

## Voice Mode Issues

<AccordionGroup>
  <Accordion title="Voice mode isn't starting">
    Voice mode relies on **WebRTC**, which has two requirements:

    1. **A supported browser** — Chrome 90+, Firefox 90+, or Safari 17+. If a respondent is on an unsupported browser (e.g., an older version or an uncommon browser), ask them to switch to Chrome.
    2. **Microphone permission** — the browser must be granted access to the microphone. If the respondent previously denied permission, they'll need to reset it in their browser settings. In Chrome, go to **Settings → Privacy & Security → Site Settings → Microphone** and allow access for the interview URL.

    If voice mode still won't start after confirming both conditions, the respondent can use **text mode** as a fallback — all questions and follow-ups are identical.
  </Accordion>

  <Accordion title="The AI's voice sounds cut off or choppy">
    Audio choppiness is almost always caused by network instability. Voice mode streams bidirectional audio over WebRTC, which requires a **stable, low-latency connection**.

    Ask the respondent to try:

    * Moving to a stronger Wi-Fi signal or switching to a wired connection.
    * Closing other bandwidth-heavy applications or browser tabs.
    * Restarting the conversation from a different network (e.g., mobile hotspot) to test if the issue is network-specific.

    If poor connectivity is unavoidable, suggest they use **text mode** instead — it has no audio streaming requirements and produces the same transcript and summary.
  </Accordion>

  <Accordion title="The conversation ended before the respondent finished">
    All ListenLand conversations have a **hard 20-minute limit**. When the limit approaches, the AI will attempt to wrap up the conversation naturally — but once the timer expires, the session ends regardless of where the respondent is in the interview.

    If respondents are regularly hitting this limit, consider:

    * Reducing the number of questions or follow-up depth to leave more room for each topic.
    * Splitting a long interview into multiple shorter interviews sent in sequence.

    This limit applies equally to text and voice mode.
  </Accordion>
</AccordionGroup>

## Webhook Issues

<AccordionGroup>
  <Accordion title="My webhook endpoint isn't receiving events">
    Work through this checklist:

    1. **HTTPS only** — ListenLand only delivers to HTTPS endpoints. Plain HTTP URLs will be rejected.
    2. **Publicly reachable** — your endpoint must be accessible from the internet. `localhost` URLs won't work in production.
    3. **Use the test event button** — on the integrations page, click **Send Test Event** to fire a sample payload and inspect the response directly in the dashboard.
    4. **Respond with 2xx within 10 seconds** — if your endpoint takes longer than 10 seconds to respond, ListenLand treats the delivery as failed. Move any heavy processing to a background job and return `200 OK` immediately on receipt.
    5. **Check your server logs** — confirm the request is arriving but being dropped or erroring somewhere in your handler.
  </Accordion>

  <Accordion title="Signature verification is failing">
    Webhook payloads are signed using an HMAC signature. Verification fails for a few common reasons:

    * **Body mutation before verification** — you must read the **raw request body as a string** before parsing it as JSON. Any middleware that parses the body first may alter the byte representation, which breaks the signature. Verify against the raw bytes, then parse.
    * **Wrong secret** — make sure the secret in your webhook configuration matches the one shown when you created the endpoint in ListenLand. If you're unsure, see the tip below about regenerating the secret.
    * **Encoding mismatch** — ensure you're computing the HMAC over UTF-8 encoded bytes and comparing against the hex-encoded signature in the `X-ListenLand-Signature` header.

    See the [Webhook Verification](/integrations/webhook-verification) documentation for a full verification code example.
  </Accordion>
</AccordionGroup>

## Account Issues

<AccordionGroup>
  <Accordion title="I didn't receive a magic link email">
    Magic link emails are sent from **[hello@listen.land](mailto:hello@listen.land)**. If the email hasn't arrived:

    1. Check your **spam or junk folder** — some filters flag authentication emails.
    2. Add `hello@listen.land` to your safe-senders list to prevent this in the future.
    3. Wait up to 2 minutes — email delivery can occasionally be delayed.
    4. Try requesting a new magic link from the sign-in page.

    If you signed up with Google, use **Continue with Google** instead of the magic link flow.
  </Accordion>

  <Accordion title="I lost my webhook secret">
    The webhook secret is displayed **only once** — at the moment you create the endpoint. It is not stored in a recoverable form after that.

    If you've lost it:

    1. Go to the interview's **Integrations** page.
    2. Delete the existing webhook endpoint.
    3. Create a new webhook endpoint — a new secret will be shown at creation. Copy and store it somewhere secure immediately.
    4. Update your webhook handler's configuration with the new secret.

    Events that were delivered to the old endpoint are not replayed to the new one, but all future `conversation.completed` events will route to the new endpoint.
  </Accordion>
</AccordionGroup>

<Note>
  If you can't resolve your issue with the steps above, reach out via the chat widget in the dashboard or email [hello@listen.land](mailto:hello@listen.land).
</Note>