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

# Troubleshooting common phone system issues

> Resolve call quality, missed calls, voicemail, caller ID, call forwarding, and Twilio integration problems in the HoopAI platform.

When your phone system is not working as expected — dropped calls, poor audio quality, or missed inbound calls — the issue usually involves configuration, network conditions, or Twilio account settings. This guide walks you through the most common phone system problems in the HoopAI platform and how to fix them.

***

## Call quality issues

<Steps>
  <Step title="Check your internet connection">
    VoIP calls require a stable internet connection with at least 100 Kbps upload and download per concurrent call. Test your connection speed and switch to a wired connection if you are on Wi-Fi.
  </Step>

  <Step title="Close bandwidth-heavy applications">
    Video streaming, large file downloads, and other VoIP calls on the same network can degrade call quality. Close unnecessary applications during calls.
  </Step>

  <Step title="Use a headset">
    Built-in laptop microphones and speakers often cause echo and feedback. Use a dedicated headset with a microphone for the best audio quality.
  </Step>

  <Step title="Check browser permissions">
    Ensure your browser has permission to access your microphone. In Chrome, click the lock icon in the address bar and confirm **Microphone** is set to **Allow**.
  </Step>
</Steps>

<Note>
  If call quality issues affect all users in your account, the problem may be network-wide. Contact your internet service provider or network administrator to check for bandwidth throttling or packet loss.
</Note>

***

## Missed calls and inbound call failures

| Issue                          | Cause                                        | Fix                                                                       |
| ------------------------------ | -------------------------------------------- | ------------------------------------------------------------------------- |
| Calls go straight to voicemail | No users available or ring timeout too short | Increase the ring timeout in **Settings > Phone Numbers > Call Settings** |
| Inbound calls not ringing      | Call routing not configured                  | Assign the phone number to a user or ring group in phone number settings  |
| Calls ring but no audio        | Browser microphone blocked                   | Grant microphone access in your browser settings                          |
| Caller hears a busy signal     | All users in the ring group are on calls     | Add more users to the ring group or enable call queuing                   |

<Warning>
  If you recently ported a phone number to Hoop, inbound calls may not work for 24–48 hours while the port completes. Check the porting status in **Settings > Phone Numbers**.
</Warning>

***

## Voicemail issues

<Steps>
  <Step title="Verify voicemail is enabled">
    Navigate to **Settings > Phone Numbers**, select the number, and confirm that **Voicemail** is toggled on.
  </Step>

  <Step title="Check the voicemail greeting">
    If your voicemail greeting is not playing, re-upload or re-record it in the voicemail settings. Ensure the audio file is in MP3 or WAV format and under 5 MB.
  </Step>

  <Step title="Confirm notification settings">
    Go to **Settings > Notifications** and ensure voicemail notifications are enabled. You can receive notifications via email, in-app, or both.
  </Step>

  <Step title="Check voicemail transcription">
    If voicemail transcription is not working, verify it is enabled in your phone settings. Transcription requires an active Twilio account with the transcription add-on enabled.
  </Step>
</Steps>

***

## Caller ID issues

<Steps>
  <Step title="Set the outbound caller ID">
    Navigate to **Settings > Phone Numbers** and select the number used for outbound calls. Set the **Caller ID** to display either your business number or business name.
  </Step>

  <Step title="Register your caller ID">
    Unregistered caller IDs may show as "Unknown" or "Spam Likely" on recipients' phones. Register your number with free caller registry services and with major carriers.
  </Step>

  <Step title="Verify the number is not flagged">
    If your number is being flagged as spam, contact your carrier and Hoop support. High call volumes or recipient reports can trigger spam flags on carrier networks.
  </Step>
</Steps>

<Tip>
  Register your business phone number with STIR/SHAKEN attestation through your Twilio account settings. This verifies your caller identity and reduces the likelihood of being flagged as spam.
</Tip>

***

## Call forwarding failures

| Issue                                        | Cause                                       | Fix                                                                             |
| -------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------- |
| Forwarded calls not reaching the destination | Forwarding number is incorrect              | Verify the destination number in **Settings > Phone Numbers > Call Forwarding** |
| Forwarded calls drop immediately             | Destination number rejects forwarded calls  | Test the destination number directly and check if it blocks unknown callers     |
| Forwarding delay is too long                 | Ring timeout set too high before forwarding | Reduce the ring timeout so calls forward faster                                 |
| Caller hears ringing but no one answers      | Destination phone is off or out of range    | Set up a fallback number or voicemail for when forwarding fails                 |

***

## Twilio integration and phone number registration

<Steps>
  <Step title="Verify your Twilio account balance">
    Log into your Twilio console and check your account balance. If the balance is zero or negative, all calls and SMS will fail until you add funds.
  </Step>

  <Step title="Check Twilio service status">
    Visit the Twilio status page to confirm there are no active incidents affecting voice services in your region.
  </Step>

  <Step title="Register for A2P 10DLC (US numbers)">
    US phone numbers require A2P 10DLC registration for business messaging and calling. Navigate to **Settings > Phone Numbers > Compliance** and complete the registration form.
  </Step>

  <Step title="Confirm number capabilities">
    Not all Twilio numbers support voice. In your Twilio console, verify that the number assigned to Hoop has **Voice** capability enabled.
  </Step>
</Steps>

<Info>
  A2P 10DLC registration is required by US carriers for all business phone numbers. Without registration, your calls and texts may be blocked or filtered. Registration typically takes 1–5 business days.
</Info>

***

## FAQs

<AccordionGroup>
  <Accordion title="Why do my outbound calls show a different number than expected?">
    Check the outbound caller ID setting for the user or phone number in **Settings > Phone Numbers**. Each user can have a different outbound caller ID assigned. Ensure the correct number is selected.
  </Accordion>

  <Accordion title="Can I use my existing phone number with Hoop?">
    Yes, you can port your existing number to Hoop. Go to **Settings > Phone Numbers > Port Number** and follow the steps. Porting typically takes 1–3 weeks depending on the carrier.
  </Accordion>

  <Accordion title="Why are my international calls failing?">
    International calling must be enabled in your Twilio account settings. Additionally, some countries require geographic permissions to be explicitly enabled. Check Twilio's geographic permissions in your console.
  </Accordion>
</AccordionGroup>