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

# Connect a 3CX Extension to VoiceInfra

> Register a VoiceInfra AI agent as a user extension on 3CX — pull the SIP credentials from the extension's config file and connect it in a few minutes.

VoiceInfra registers with 3CX as a normal **user extension**. From 3CX's point of view nothing unusual is happening: an extension is registered, and calls route to it the same way they route to a desk phone.

That means your AI agent can be part of ring groups, queues, and call flows without any changes to how 3CX works.

## Prerequisites

| Requirement | Why |
| - | - |
| VoiceInfra workspace on an active subscription | Agents and extensions need a plan. |
| **Workspace Admin** role | Only an admin can add extensions. |
| 3CX admin access | You need to create or edit a user extension. |
| The VoiceInfra SIP host and whitelist IP | Copy them from the portal — see below. |

## Step 1: Prepare the extension in 3CX

<Steps>
  <Step title="Open the Users list">
    Log in to 3CX and go to **Admin → Users**.
  </Step>

  <Step title="Pick or create the extension">
    Select an existing user to use as your AI agent's extension, or **create a new one**. A dedicated extension is easier to reason about later — for example `Agent 101`.
  </Step>

  <Step title="Open the user's details">
    Click the user to open their details page.
  </Step>

  <Step title="Set the connection policy">
    Open the **Options** tab and enable **Block remote non-tunnel connections (Insecure!)**.

    <Note>
      This blocks SIP registrations that do not come through the 3CX tunnel or SBC — which is exactly what VoiceInfra is. The **next step is what lets VoiceInfra through anyway**: whitelisting its IP. Enable the block for security, then whitelist VoiceInfra so it is the one exception.
    </Note>
  </Step>

  <Step title="Get the extension's SIP credentials">
    Open the **General** tab. You can either configure the extension's credentials yourself, or keep 3CX's generated defaults and read them from the provisioning file:

    1. Click the **QR code** button.
    2. Scan the QR code with any reader — it decodes to a URL.
    3. Open that URL to get the **config file**.

    From the config file, you need three values:

    ```xml theme={null}
    <AuthID>your_auth_id</AuthID>
    <AuthPass>your_auth_password</AuthPass>
    <PBXLocalAddr>yourcompany.3cx.cloud</PBXLocalAddr>
    ```
  </Step>
</Steps>

| Value in the config file | What it is | Where it goes in VoiceInfra |
| - | - | - |
| `<AuthID>` | The SIP authentication username | **SIP Username** |
| `<AuthPass>` | The SIP authentication password | **SIP Password** |
| `<PBXLocalAddr>` | Your 3CX PBX address | **SIP Domain** |

## Step 2: Register the extension in VoiceInfra

<Steps>
  <Step title="Add a phone number">
    In the VoiceInfra portal, go to **Phone Numbers → Add Phone Number** and choose **PBX Extension**.
  </Step>

  <Step title="Enter the extension details">
    | Field | Value |
    | - | - |
    | Display Name | A label you will recognise, for example "AI Agent 101" |
    | Extension Number | The 3CX extension number, for example `101` |
    | Call Direction | **Both** for two-way calling, or **Inbound Only** |
  </Step>

  <Step title="Fill in the SIP configuration">
    This is where the three values from the config file go:

    | Field | Value |
    | - | - |
    | SIP Domain | `<PBXLocalAddr>` — for example `yourcompany.3cx.cloud` |
    | SIP Username | `<AuthID>` |
    | SIP Password | `<AuthPass>` |
  </Step>

  <Step title="Set the transport">
    Under **Advanced**, set **Transport** to match what your 3CX extension accepts — **UDP** or **TCP**. If registration fails, this mismatch is the first thing to check.
  </Step>

  <Step title="Create and assign an assistant">
    Click **Create**, then assign an **Inbound AI Assistant** and/or an **Outbound AI Assistant** to the new extension. Without an assistant, calls connect but nothing answers.
  </Step>
</Steps>

## Step 3: Whitelist VoiceInfra in 3CX

Because you enabled the remote-connection block in step 1, 3CX will reject VoiceInfra until its IP is trusted.

1. Copy the **whitelist IP** from the portal: **Phone Numbers → your extension → Connection details**. The value is region-scoped, so copy it rather than using one from a guide.
2. Add that IP to your 3CX firewall's allowed SIP list.

## Step 4: Test

| Direction | How to test | What should happen |
| - | - | - |
| **Inbound** | Dial the extension from another 3CX extension or through a call flow | Your AI assistant answers |
| **Outbound** | Trigger an outbound call from your assistant | The destination rings |

The extension's registration status is visible in 3CX under **Admin → Users**, and in VoiceInfra on the extension's detail page.

## Troubleshooting

| Symptom | What to check |
| - | - |
| Registration fails | **Transport** must match between 3CX and VoiceInfra — try the other of UDP/TCP. |
| Registration fails with the block enabled | VoiceInfra's IP is not yet whitelisted in 3CX. Copy the current IP from the portal and add it. |
| Nothing answers inbound calls | No **Inbound AI Assistant** assigned to the extension. |
| Outbound calls fail | The extension's **Call Direction** is set to **Inbound Only** — change it to **Both**, and make sure an **Outbound AI Assistant** is assigned. |
| Credentials rejected | `AuthID` and `AuthPass` must be copied exactly. They are case-sensitive, and regenerating the extension in 3CX invalidates the old ones. |
| Calls connect but there is no audio | Check your firewall allows the RTP port range between 3CX and VoiceInfra. |

<Warning>
  If you regenerate or re-provision the extension in 3CX, its `AuthPass` changes. VoiceInfra will stop registering until you update the SIP Password on the extension.
</Warning>

## Quick reference

| VoiceInfra field | 3CX source |
| - | - |
| SIP Domain | `<PBXLocalAddr>` |
| SIP Username | `<AuthID>` |
| SIP Password | `<AuthPass>` |
| Extension Number | The 3CX extension number |
| Transport | Match your 3CX extension (UDP or TCP) |

**Where to find things**

| What | Where |
| - | - |
| The user's SIP credentials | 3CX **Admin → Users → \[user] → General** |
| The connection policy | 3CX **Admin → Users → \[user] → Options** |
| VoiceInfra's SIP host and whitelist IP | VoiceInfra **Phone Numbers → your extension → Connection details** |

## Setup checklist

* [ ] Extension created or selected in 3CX and added to the VoiceInfra portal
* [ ] **Block remote non-tunnel connections** enabled on the user
* [ ] `AuthID`, `AuthPass`, and `PBXLocalAddr` copied from the config file
* [ ] SIP Domain, Username and Password entered in VoiceInfra
* [ ] Transport matches on both sides
* [ ] VoiceInfra's IP whitelisted in your 3CX firewall
* [ ] AI assistant assigned for inbound and/or outbound
* [ ] Test calls in both directions succeed


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.