Skip to main content
DocumentationAPI ReferenceVideo Tutorials

Troubleshooting

This guide helps you solve common issues with the Hanc.AI platform. Find your problem below and follow the solution steps.

Quick Diagnosis​

SymptomLikely CauseSolution Section
Can't log inAccount/password issueAccount Issues
Agent won't respondConfiguration problemAgent Issues
Wrong answersKnowledge base issueKnowledge Base Issues
Calls not connectingPhone setup issuePhone Issues
Poor audio qualityNetwork/settings issueAudio Issues
Widget not loadingDomain/browser issueWidget Issues
Call disconnects with "No Credits"Ran out of creditsCredit Issues
Feature not workingPlan limitationBilling Issues

Account Issues​

Can't Log In​

Symptoms:

  • Login page shows error
  • Password not accepted
  • Account seems locked

Solutions:

  1. Check email/password

    • Ensure correct email address
    • Check caps lock
    • Try copy-paste password

  2. Reset password

    • Click "Forgot Password"
    • Check email (including spam)
    • Click reset link within 1 hour
    • Create new password

  3. Clear browser data

    • Clear cookies for hanc.ai
    • Clear cache
    • Try incognito/private mode

  4. Try different browser

    • Chrome, Firefox, Safari, or Edge
    • Disable browser extensions

Still stuck? Contact support@hanc.ai

Can't Create Account​

Symptoms:

  • Registration fails
  • "Email already exists" error
  • Verification code not received

Solutions:

  1. Email already registered

    • Try "Forgot Password" to recover existing account
    • Use different email

  2. Phone verification failing

    • Ensure correct country code
    • Enter number without leading zero
    • Wait 60 seconds before requesting new code
    • Try different phone number

  3. Page errors

    • Refresh and try again
    • Clear browser cache
    • Try different browser

Agent Issues​

Agent Not Responding​

Symptoms:

  • Test call connects but agent silent
  • Agent doesn't speak greeting
  • Infinite loading

Diagnostic steps:

1. Check agent status is ACTIVE (not INACTIVE or DELETED)
2. Verify first message (greeting) is set
3. Check prompt is not empty
4. Check knowledge base is connected (if applicable)
5. Check you have available credits

Solutions:

  1. Check agent status

    • Go to Voice Agents
    • Ensure agent status is ACTIVE
    • If status is INACTIVE, activate it from agent settings

  2. Verify first message

    • Agent settings → First Message
    • Ensure text is present
    • Save after changes

  3. Check prompt and knowledge base

    • Ensure the prompt is not empty
    • If using a knowledge base, verify it is connected and contains content

  4. Test in browser

    • Click "Talk to agent"
    • Allow microphone
    • Wait for greeting

Agent Gives Wrong Information​

Symptoms:

  • Incorrect prices quoted
  • Wrong business hours stated
  • Made-up information

Cause: Usually a knowledge base or prompt issue.

Solutions:

  1. Check knowledge base content

    • Is the correct information present?
    • Is it clearly formatted?
    • Any conflicting information?

  2. Verify KB is connected

    • Agent settings → Knowledge Base
    • Correct KB selected?

  3. Strengthen prompt restrictions Add to prompt:

    CRITICAL: Only use information from the knowledge base.
    If information is not in the knowledge base, say "I don't have that information."
    NEVER make up prices, hours, or other specific details.

  4. Lower temperature

    • Reduce temperature to 0.3-0.5
    • More deterministic responses

Agent Doesn't Use Knowledge Base​

Symptoms:

  • Says "I don't know" for information that exists
  • Generic responses instead of specific

Solutions:

  1. Confirm KB connected

    • Agent settings → Knowledge Base section
    • Should show your KB selected

  2. Check KB content format

    • Clear headings
    • Simple structure
    • Question/answer pairs for FAQ

  3. Add FAQ format

    Q: What are your business hours?
    A: We are open Monday-Friday 9am-6pm, Saturday 10am-2pm.

  4. Verify file uploaded properly

    • Go to Knowledge Base
    • Check file appears in list
    • Check file size is not zero

Agent Won't Stop Talking​

Symptoms:

  • Very long responses
  • Doesn't wait for user
  • Overwhelming information

Solutions:

  1. Add to prompt:

    - Keep responses to 1-2 sentences
    - Ask one question at a time
    - Wait for the customer to respond
    - Be concise and direct

  2. Lower max tokens

    • If available in settings
    • Limits response length

Knowledge Base Issues​

File Upload Fails​

Symptoms:

  • Error when uploading
  • File rejected
  • Processing stuck

Solutions:

  1. Check file format

    • Supported: .pdf, .docx, .doc, .xlsx, .xls, .txt, .md, .csv, .rtf, .json
    • Not supported: images, audio, video files

  2. Check file size

    • Maximum 10 MB per file
    • Maximum 10 files per knowledge base
    • Try splitting large documents

  3. Check file content

    • Not password protected
    • Not corrupted
    • Contains actual text (not scanned images)

  4. Try different format

    • Convert PDF to .txt or .docx
    • Copy text into new document

Information Not Found​

Symptoms:

  • Agent says "I don't know"
  • Information exists in KB but not used

Solutions:

  1. Improve structure

    • Clear headings for topics
    • FAQ format for common questions
    • Avoid long paragraphs

  2. Use exact phrases

    • Match how customers ask
    • Include variations of questions

  3. Add more context

    • Don't just list prices
    • Include service names and descriptions

Example improvement:

❌ Poor:

25, 35, 55

✅ Good:

## Haircut Prices
- Men's haircut: €25
- Women's haircut: €35
- Children's haircut (under 12): €20

Phone Issues​

Calls Not Connecting​

Symptoms:

  • Calls go to voicemail or error
  • Ringing but no answer
  • Call dropped immediately

Solutions:

  1. Check phone number connection

    • Integration → Phone Numbers
    • Status should be "Connected"
    • If not, check your setup

  2. Verify number assignment

    • Phone Numbers section
    • Number has agent assigned?
    • Agent is active?

  3. Check phone number status

    • Number is active?
    • Account has credit balance?

  4. Test with browser

    • Use "Talk to agent" in dashboard
    • If this works, issue is phone-side

Wrong Agent Answers​

Symptoms:

  • Expected Agent A, got Agent B
  • Wrong greeting

Solutions:

  1. Check number assignment

    • Phone Numbers → Click the number
    • Verify correct inbound agent selected

  2. Check for webhook conflicts

    • Verify webhook points to Hanc.AI
    • No other services intercepting

Audio Issues​

Poor Call Quality​

Symptoms:

  • Robotic voice
  • Choppy audio
  • Delays in conversation

Solutions:

  1. Check internet connection

    • Minimum 5 Mbps recommended
    • Wired connection better than WiFi

  2. Check network conditions

    • High latency or packet loss degrades call quality
    • Try a different network if possible
    • Close bandwidth-heavy applications

  3. Check browser compatibility

    • Use a modern browser (Chrome, Firefox, Safari, Edge)
    • Ensure WebRTC and Web Audio API are supported
    • Update browser to the latest version

  4. Try different voice

    • Some voices perform better on different connections
    • Test alternatives in agent settings

  5. For browser test calls

    • Close other tabs/applications
    • Use wired headset if possible
    • Check microphone isn't muted

Agent Can't Understand Caller​

Symptoms:

  • Agent asks to repeat
  • Misunderstands words
  • Wrong transcription

Solutions:

  1. Language settings

    • Verify correct language selected
    • Match caller's expected language

  2. Prompt for clarity Add to prompt:

    If you don't understand, politely ask the caller to repeat.

  3. Test speech recognition independently

    • Use test call feature
    • Speak clearly and note issues
    • May be accent or audio quality

Billing Issues​

Feature Not Available​

Symptoms:

  • Button grayed out
  • "Upgrade required" message
  • Can't create more agents

Solutions:

  1. Check current plan

    • Settings → Billing
    • Review plan limits and features

  2. Can't create agent

    • The Free plan is limited to 1 agent
    • Upgrade to Starter or higher for unlimited agents

  3. Check usage

    • Near or at limits?
    • Wait for next billing cycle or upgrade

  4. Upgrade plan

    • If needed, upgrade from Billing page

Payment Failed​

Symptoms:

  • "Payment failed" error
  • Service interrupted
  • Can't update subscription

Solutions:

  1. Check card details

    • Card not expired?
    • Sufficient funds?
    • Correct billing address?

  2. Contact bank

    • International payments blocked?
    • Suspicious activity flag?

  3. Update payment method

    • Settings → Billing → Update Payment
    • Try different card

  4. Contact support

Widget Issues​

Widget Not Loading​

Symptoms:

  • Widget button does not appear on website
  • Widget shows error or blank space
  • Widget loads but call does not connect

Solutions:

  1. Check domain whitelist

    • Go to your agent's widget settings
    • Ensure your website domain is added to the allowed domains list
    • Include all variations (with/without www)

  2. Check browser requirements The Hanc.AI widget requires the following browser capabilities:

    • WebGL 2.0 — for rendering the widget UI
    • Web Audio API — for audio processing
    • WebRTC — for real-time voice communication

    Most modern browsers (Chrome, Firefox, Safari, Edge) support these. If users report issues, ask them to update their browser.

  3. Check widget embed code

    • Verify the embed script is correctly placed in your HTML
    • Check browser console for JavaScript errors
    • Ensure no ad blockers or script blockers are interfering

  4. Test in incognito mode

    • Open your website in an incognito/private window
    • This rules out extension conflicts

Credit Issues​

Call Disconnects with "No Credits"​

Symptoms:

  • Call ends abruptly mid-conversation
  • Disconnection reason shows NO_CREDITS
  • Agent stops responding during an active call

Cause: Your account ran out of credits while a call was in progress. The platform disconnects calls when there are no remaining credits to cover the usage.

Solutions:

  1. Check your credit balance

    • Go to Settings → Billing
    • Review remaining credits

  2. Add more credits

    • Upgrade your plan for more monthly credits
    • Credits from your subscription are available immediately

  3. Monitor usage proactively

    • Review analytics regularly to track credit consumption
    • Set up usage alerts if available

  4. Understand credit rollover

    • Unused credits roll over to the next month
    • 100% of your subscription fee converts to credits

Browser Issues​

Page Not Loading​

Solutions:

  1. Refresh page (Ctrl/Cmd + R)
  2. Clear cache (Ctrl/Cmd + Shift + Delete)
  3. Try incognito mode
  4. Try different browser
  5. Check internet connection

Buttons Not Working​

Solutions:

  1. Disable ad blockers for hanc.ai
  2. Enable JavaScript
  3. Clear cookies
  4. Update browser to latest version

Integration Issues​

Phone Numbers Not Connecting​

Solutions:

  1. Verify phone number setup

    • Number is active?
    • Agent is assigned?

  2. Check account status

    • Account active and has credits?

  3. Try reconnecting

    • Disconnect and reconnect the number
    • Contact support if issues persist

Webhook Not Receiving Events​

Solutions:

  1. Verify URL

    • URL is publicly accessible
    • HTTPS (not HTTP)
    • No authentication required

  2. Check server response

    • Must return 200 status
    • Within 30 seconds

  3. Test with webhook.site

    • Use test URL to verify events sending
    • Debug from there

Getting Help​

Before Contacting Support​

Gather this information:

  • Account email
  • Agent name/ID (if applicable)
  • Screenshot of error
  • Steps to reproduce issue
  • Browser and device used

Contact Support​

Email: support@hanc.ai

Include:

  • Clear description of issue
  • When it started
  • What you've tried
  • Screenshots if helpful

Response time:

  • Standard: Within 24 hours
  • Pro/Business: Within 4 hours

Status Page​

Check platform status for outages:

  • System status announcements
  • Planned maintenance windows
  • Historical uptime