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

# Native Extension Mode

> Add AiSky as an extension on your existing PBX. Anyone in the office dials that extension to reach the AI.

<Info>
  **Audience**: PBX admin. **Time**: 5 to 10 minutes once you have the credentials. **Works with**: 3CX, Yeastar, FreePBX, Asterisk, Grandstream, and any SIP PBX that supports extension registration.
</Info>

## What it is

The default way to use AiSky is to give it a phone number (a DID) and route that DID to it. Native extension mode (sometimes called **register-direction** or **register-mode** in the dashboard) is the inverse: AiSky registers as an extension on **your** PBX, just like a desk phone. Once it's registered:

* Anyone in the office can dial that extension to reach the AI
* The AI shows up in your PBX directory
* You can include it in ring groups, call queues, or hunt groups
* Transfers from the AI to other extensions use your PBX's native transfer rules
* Caller ID on inbound calls reflects the original caller, not a relay

The trade-off is that you provision and manage the credentials on your PBX side. We register; you control the routing.

## When to use it

| Use native extension mode when…                               | Use the standard inbound trunk when…                        |
| ------------------------------------------------------------- | ----------------------------------------------------------- |
| You want the AI to be one of many phones on your existing PBX | You want a dedicated AI phone number that bypasses your PBX |
| Your team should be able to dial the AI from a desk handset   | Your callers come from outside (PSTN only)                  |
| You need ring-group or follow-me behaviour around the AI      | You want simpler setup with no PBX changes                  |
| Your PBX is your single source of truth for telephony         | You don't have a PBX or it's not the primary routing system |

Both modes coexist on the same AiSky tenant. You can have inbound trunks for some agents and native extensions for others.

## What you'll need

From your PBX:

* The SIP domain (e.g. `pbx.example.com` or `truenav.ycm.voipza.net`)
* An unused extension number (e.g. `1000`)
* Credentials for that extension: username + password
* Transport (UDP, TCP, or TLS, UDP works for most PBXes)
* Port (default 5060, or 5061 for TLS)

From AiSky:

* The agent you want this extension to route to (you'll link it after the trunk is created)

## Setup

<Steps>
  <Step title="Create the extension on your PBX">
    In your PBX admin console, create a new SIP extension just like you would for a desk phone. Note down the username and password the PBX assigns. Configure the extension's inbound DID routing if you want external callers to reach it via a public number.
  </Step>

  <Step title="Add it in AiSky">
    Go to **Phone Numbers, then Connect Your Carrier, then SIP Trunk**. Pick your PBX type. On the setup screen, switch the **Connection Type** toggle to **"Add AiSky as a phone on your PBX"**. Fill in:

    * Your PBX SIP domain
    * The extension number you assigned
    * Username and password
    * Transport and port (defaults work for most PBXes, change them only if your PBX requires it)

    Click **Connect to PBX**.
  </Step>

  <Step title="Wait for registration">
    AiSky will register with your PBX within 30 seconds. Open **Settings, then PBX Settings** to watch the status:

    * **Connecting**: registration in progress
    * **Registered as ext \<N>**: live and ready
    * **Failed**: shows the error message, usually wrong password or unreachable domain. Use the **Re-register** button after fixing.
  </Step>

  <Step title="Link an agent">
    Open the agent you want this extension to use. Go to its **Telephony** tab and pick the trunk from the dropdown. Save. Calls dialled to that extension on your PBX will now reach this agent.
  </Step>

  <Step title="Add your directory">
    Optional but highly recommended. Open the trunk in **Settings, then PBX Settings** and add the extensions you want the AI to be able to transfer callers to (e.g. extension 100 = Reception, extension 215 = Sarah in Accounts). Each row has a display name plus free-form aliases, so the AI matches a caller's request like "put me through to billing" or "speak to Sarah" to the right extension without you scripting every variation.
  </Step>

  <Step title="Bind extensions to phone numbers (optional)">
    If you want certain inbound DIDs to route directly to a named extension (e.g. `0871234567` always rings extension 6105), use **Phone Numbers → Connect PBX Extension** in the dashboard. The dialog filters to your register-mode trunks, asks for the extension number, the agent, the public DID, and a friendly label, and writes the binding without a support ticket. Existing phone-number rows route via your PBX's inbound rules; the dialog is for when you want AiSky to own the binding.
  </Step>
</Steps>

## Monitoring after setup

Every phone number on the **Phone Numbers** page has a **Diagnostics** button. Click it for any register-mode number to see:

* Live health: assignment, registration status, credentials valid
* Last 10 calls in 24h with friendly-label outcomes ("No answer", "Caller hung up", "Reached us, agent never started")
* Last 5 phone-related edge function errors in 24h

The friendly labels translate technical disconnect reasons so support conversations don't require knowledge of the underlying SIP stack.

## How transfers work

When a caller asks the AI to transfer them, the AI fires a SIP REFER on the existing call leg with the destination extension. Your PBX accepts the REFER and rings the target extension exactly as if the caller had been transferred from any other phone on your system. The AI's leg drops out of the call, leaving the caller bridged to the human.

Transfer rules, routing logic, voicemail fallback, and ring strategy are all handled by your PBX, we don't override them.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Status stuck on Connecting">
    AiSky is sending REGISTER requests but your PBX isn't responding. Check:

    * The SIP domain is reachable from the public internet (run `dig pbx.example.com` and confirm a public A record)
    * Your PBX firewall allows our registration source IP
    * The extension exists and isn't disabled on your PBX
  </Accordion>

  <Accordion title="Status: Failed, Authentication required">
    Wrong username or password. Re-enter the credentials and click **Re-register**.
  </Accordion>

  <Accordion title="Registered but dialling the extension goes to voicemail">
    Your PBX is registering us but routing the inbound DID elsewhere. Check the inbound route on your PBX:

    * The DID's destination is set to this extension (not directly to voicemail)
    * The "no answer" timeout is at least 20 seconds (not 0)
    * There isn't a follow-me / forwarding rule firing first
  </Accordion>

  <Accordion title="AI answers but transfers fail">
    Your PBX may have transfer permissions disabled for the extension. In your PBX admin, find the extension and ensure:

    * **Allow transfer** is enabled
    * REFER is permitted (some PBXes call this "Blind transfer" or "Attended transfer")
  </Accordion>

  <Accordion title="One-way audio or no audio">
    SIP signalling is working but media isn't. Usually a NAT or firewall issue:

    * Confirm RTP ports (10000 to 20000 by default on most PBXes) are open both ways
    * If your PBX is behind NAT, ensure its external IP is correctly advertised in SIP responses
  </Accordion>
</AccordionGroup>

## Limitations

* **Outbound calls**: native extension mode is for inbound only. Use the standard outbound trunk if you need the AI to make outbound calls
* **One agent per trunk**: link one agent at a time. To rotate agents, change the link in **Telephony**, takes effect on the next call
* **Container restart drops registration for \~30 seconds**: deploys are scheduled off-hours; planned

## Pricing

Same per-minute rate as standard AiSky calls. There's no extra fee for native extension mode.