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

# Extensions and Devices

> Configure SIP endpoints for desk phones, mobile, and browser

An extension is a SIP endpoint — the technical name for a phone (or app) that can place and receive calls on Hiveku. Every user who needs to take calls has at least one extension. Each extension has its own number (typically a 3- or 4-digit internal extension like 101, 215), credentials, and voicemail box.

Manage extensions in `/dashboard/communications/` under the **Extensions** tab.

## Device types

<CardGroup cols={2}>
  <Card title="Desk phone" icon="phone-office">
    Physical SIP phone — Polycom, Yealink, Cisco, Grandstream, etc. Auto-provisioned by MAC address. Plugged into Ethernet, ready in seconds.
  </Card>

  <Card title="Mobile softphone" icon="mobile">
    iOS and Android apps. Log in with your Hiveku credentials and your extension follows you.
  </Card>

  <Card title="Browser softphone" icon="browser">
    Built-in WebRTC phone in your Hiveku dashboard — no install. Best for hybrid teams that already live in the dashboard.
  </Card>

  <Card title="Bring your own SIP" icon="server">
    Any SIP-compliant device or software. Use the credentials Hiveku generates to register.
  </Card>
</CardGroup>

## Create an extension

<Steps>
  <Step title="Open Extensions">
    From `/dashboard/communications/`, click the **Extensions** tab and choose **New extension**.
  </Step>

  <Step title="Pick the user">
    Each extension belongs to one user account. The user gets the credentials and the voicemail.
  </Step>

  <Step title="Pick the extension number">
    A short internal number — 101, 215, 4001. Hiveku suggests the next available.
  </Step>

  <Step title="Configure outbound caller ID">
    Which DID this extension uses on outbound calls. Default is the account's primary number.
  </Step>

  <Step title="Set voicemail PIN">
    A 4-6 digit PIN protects the voicemail box. Required.
  </Step>

  <Step title="Pick a device type">
    Desk phone (auto-provision by MAC), mobile, browser, or BYO SIP.
  </Step>
</Steps>

## Auto-provisioning desk phones

Hiveku supports zero-touch provisioning for major SIP phone brands. Plug the phone in, register the MAC, and the device pulls config and reboots ready to use.

<Tabs>
  <Tab title="Polycom">
    Models: VVX 250/350/450, Edge E series. Add the MAC in the **Provisioning** tab, plug the phone into a network with internet, and on first boot it downloads its config from Hiveku's provisioning server.
  </Tab>

  <Tab title="Yealink">
    Models: T31/T33/T43/T46/T54. Same flow — register MAC, plug in, wait \~60 seconds.
  </Tab>

  <Tab title="Grandstream">
    GXP1620, GRP series. Supported via auto-provisioning.
  </Tab>

  <Tab title="Cisco">
    SPA series and Multiplatform (MPP) firmware models. Note: Cisco "Enterprise" firmware is not supported — convert to MPP first.
  </Tab>
</Tabs>

<Info>
  Auto-provisioning requires the phone's MAC address (printed on the underside of the device) and that the phone has factory firmware or a Hiveku-compatible provisioning URL pointed at it.
</Info>

## Mobile softphone

The Hiveku Phone app (iOS and Android) registers your extension to your phone. You can take calls anywhere with cell or wifi data.

<Steps>
  <Step title="Download">
    "Hiveku Phone" on the App Store and Google Play.
  </Step>

  <Step title="Sign in">
    Log in with your Hiveku account credentials.
  </Step>

  <Step title="Pick the extension">
    If you have multiple extensions, pick which one to register on this device.
  </Step>

  <Step title="Allow notifications">
    Push notifications wake the app for incoming calls. Without them, calls only ring when the app is in the foreground.
  </Step>
</Steps>

<Tip>
  Register the same extension on a desk phone AND a mobile softphone simultaneously — both ring on incoming calls. Pick up wherever's nearest.
</Tip>

## Browser softphone

The browser softphone is built into the dashboard — no download. Click the phone icon in the top nav of `/dashboard/communications/` and pick **Open phone**. A floating panel appears.

<Warning>
  The browser softphone needs microphone permission. Use Chrome, Edge, or Safari — Firefox WebRTC has compatibility quirks. For best audio, use a USB headset; built-in laptop mics produce noticeable echo.
</Warning>

The browser phone supports:

* Inbound and outbound calls
* Hold, mute, transfer (blind and attended), conference (3-way)
* Click-to-call from CRM contact pages
* Inline call recording (subject to compliance settings)
* Visual voicemail and call history

## Voicemail

Each extension has a voicemail box with a 4-6 digit PIN. When a call goes to voicemail:

* The caller hears the greeting (default or custom-recorded)
* A recording is saved
* The user gets an email with the audio attached and a transcription
* The voicemail shows up in the dashboard under **Calls** with a "Voicemail" filter

Configure greetings, transcription on/off, and email-to-voicemail address from the extension's detail page.

## Outbound caller ID

By default, an extension uses the account's primary DID for outbound caller ID. Override per-extension when:

* A sales rep should outbound from a regional local number
* A support agent uses the toll-free number on outbound
* A user has multiple personas (sales + recruiting on the same Hiveku account)

The override is enforced server-side — even if the device claims a different caller ID, Hiveku rewrites it to the configured DID.

## Multiple devices on one extension

You can register multiple devices to the same extension simultaneously — desk phone, mobile, and browser. All ring on inbound; outbound from any device shows the same caller ID. This is the standard "follow me" pattern.

## API

```bash theme={null}
# List extensions
curl https://api.hiveku.com/api/communications/extensions \
  -H "Authorization: Bearer hk_live_xxx"

# Create an extension
curl -X POST https://api.hiveku.com/api/communications/extensions \
  -H "Authorization: Bearer hk_live_xxx" \
  -d '{
    "user_id": "user_01",
    "extension": "101",
    "outbound_caller_id_did": "+14155551234",
    "voicemail_pin": "1234"
  }'
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Desk phone won't register">
    Check that the MAC address is entered correctly (usually printed on the bottom of the phone, no colons), the phone has internet access, and you've factory-reset before provisioning. Some old firmware versions need a manual upgrade first.
  </Accordion>

  <Accordion title="One-way audio on calls">
    Almost always a NAT/firewall issue. The phone (or computer) is behind symmetric NAT and can't establish RTP. Solutions: enable STUN, use a SIP-aware router, or use the browser softphone which handles NAT via WebRTC ICE.
  </Accordion>

  <Accordion title="Mobile app says 'no audio device' on iOS">
    Check Settings > Hiveku Phone > Microphone permission. Also check Bluetooth — if a paired headset disconnected mid-call, audio routes to a non-existent device.
  </Accordion>

  <Accordion title="Voicemail email isn't arriving">
    Check Settings > Email and confirm your sending domain is verified. Voicemail email goes through Hiveku Email.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Ring groups" icon="users" href="/communications/ring-groups">
    Group multiple extensions for inbound routing.
  </Card>

  <Card title="IVR" icon="list-tree" href="/communications/ivr">
    Add a "press 1 for sales" menu in front of your extensions.
  </Card>
</CardGroup>