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

# Connecting 3CX to Neo

> Add an API client for Neo on a client's 3CX and save it in Neo

You connect 3CX once for each client that uses it, with three values for that client's PBX: its address, and the Client ID and API key of an API client you add for Neo.

## Before you start

* The PBX runs 3CX V20, with a licence that includes the Configuration API (3CX requires an 8SC or larger licence for it).
* Neo reaches the PBX over the internet. Its web client must answer on a public address over HTTPS with a certificate from a public authority, as a 3CX-hosted PBX (`<name>.3cx.us`, `<name>.my3cx.de` and the like) does. A PBX that is reachable only inside the client's network needs a public address first. To allow only Neo, see [IP whitelisting](/integrations/ip-whitelisting).

## 1. Add an API client in 3CX

**1. Open the API page**

Sign in to the client's 3CX Admin Console and open **Integrations** → **API**. Click **Add**.

**2. Set up the API client**

Enter a **Client ID**: an extension number 3CX reserves for Neo. Check **3CX Configuration API Access**. Choose the **Department** and the **Role** Neo works with: a system admin role lets Neo manage users in every department, and a department admin role only in that department. On a PBX that hosts several of your clients, choose this client's department, so Neo reaches only this client.

**3. Copy the API key**

Save the API client. 3CX shows its **API key** once: copy it now.

> [!WARNING]
>
> 3CX keeps one active token per API client, so give Neo an API client of its own. Another app that uses the same API client ends Neo's token each time it signs in, and the other way round.

## 2. Add the connection in Neo

**1. Open Integrations**

In the Neo Dashboard, open [**Integrations** → **3CX**](https://dashboard.neoagent.io/integrations?open=threecx), under Communication.

**2. Pick the client**

In **Customer**, choose the client this PBX belongs to. The client must be on your **Companies** tab. For a second client, click **Add customer**.

**3. Save the connection**

Enter the **PBX URL** (the address of the client's 3CX web client, with its port when it is not 443, such as `https://pbx.example.com:5001`), the **Client ID** and the **API Key**. Click **Save settings**. Neo gets a token from the PBX and reads its configuration before it saves, so a wrong value is rejected straight away, with what to fix.

## 3. Turn 3CX on per agent

**1. Open the agent's tools**

Open the agent in the Neo Dashboard, go to its **Tools & Settings** tab and click **Communication**.

**2. Pick a preset**

Expand the **3CX** block and pick one of its **Presets**, or set each permission group by hand.

| Preset | What it does |
| - | - |
| **Read Only** | Reads users, departments, phones, call routing, call history, trunks and the system; changes nothing |
| **Helpdesk** | Reads the same; adding, changing or removing a user, a desk phone or a contact asks a technician |
| **IT Admin** | Changes users, departments, phones, call routing and trunks on its own; roles, integrations and system settings ask a technician |
| **Full Automation** | Every 3CX call Neo sends, without approval except the Safety Controls |

Read Only, Helpdesk and IT Admin keep **Recordings & Voicemail** off. Turn it on only for an agent that needs it.

## 4. Add 3CX to onboarding and offboarding

Give 3CX's **Users & Extensions** group to the agents that work your new starter and leaver tickets, and say in their instructions what to do on 3CX: which department a new starter goes in, which queues and ring groups they join, and whether a leaver's extension is disabled or deleted. Ask your Neo Support Agent to add these steps to your agents.


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