# Connect 3CX

Connect your 3CX phone system to EspoCRM for caller lookup, call logging, the Call button, recordings and the ringing pop-up.

With 3CX, routing, queues, voicemail and hours stay in 3CX. EspoCRM adds:

- **Who's calling** in 3CX's app: name, company and a link to the record in EspoCRM.
- **Call logging**: when a call ends, a **Call** is logged on the Contact, Lead or Account (inbound, missed, outbound
  or unanswered, with its duration), assigned to the user with that 3CX extension. Callers who aren't in the CRM aren't
  logged.
- **Call button**: opens 3CX's web client dialer, or the 3CX app.
- With the 3CX API client (below): **recordings** that play in EspoCRM and the **ringing pop-up**.

## In EspoCRM

:::steps
1. Open **Administration → Integrations → S+M EspoCRM VOIP · 3CX**, tick **Enabled** and fill in **3CX address**
   (for example `https://yourcompany.3cx.us`). In **Call button opens**, choose *3CX web client* or *3CX app (tel:
   links)*. Optionally, choose who gets missed calls that have no assigned user. Save.
2. Open **Administration → S+M EspoCRM VOIP → 3CX Template**. It downloads `SMEspoCRMVOIP.xml` with this CRM's
   addresses and secret filled in.
3. For each person, set **3CX Extension** on their User (for example `101`).
:::

> [!WARNING]
> Keep the template file private: it contains the secret that lets 3CX read your CRM.

## In the 3CX Admin Console

:::steps
1. Open **Integrations → CRM** and note what is selected today, so you can switch back.
2. Choose **Add Template** and upload the file. Keep its name `SMEspoCRMVOIP.xml`: 3CX refuses names with spaces,
   dashes, "+" or "(1)".
3. In the CRM list, choose **SMEspoCRMVOIP**. The addresses and the secret are already filled in. Keep **Enable Call
   Journaling** on and turn **Always query** on. Save.
4. Use **TEST** with a number that is in the CRM: it should show the name.
:::

3CX has one CRM connection for the whole system: from now on, its calls are logged in this CRM. To go back, choose the
previous CRM there again.

## Recordings and the ringing pop-up (optional)

These need a 3CX API client.

:::steps
1. In the 3CX Admin Console, open **Integrations → API** and choose **Add**. Client ID: for example `espocrm`.
2. Tick **XAPI Access**: Department *DEFAULT*, Role **Owner** (other roles can't read the call history and
   recordings).
3. Tick **3CX Call Control API Access** and add the agents' extensions (not DID numbers).
4. Save and copy the API key; 3CX shows it only once.
5. In EspoCRM's 3CX settings, fill in **3CX API Client ID (recordings, live calls)** and **3CX API key (secret)**.
   Save.
6. Open **3CX Lookup Test** and choose **Test the 3CX API**.
:::

Recordings stay in 3CX: EspoCRM streams them after checking the user may see that Call, and stores nothing.

## Test

1. Call in from a number that's in the CRM, answer in 3CX, hang up: a held "Inbound call" appears on the record,
   assigned to that extension's user.
2. Call again and don't answer: a "Missed call" is logged and the user gets a notification. Calls that only reached a
   receptionist, ring group or queue are logged as missed too.

## Change the secret

Clear **Secret for 3CX** in EspoCRM's 3CX settings, save, download the template again and upload it in 3CX.
Downloading the template again without clearing it keeps the same secret.

If lookups don't work, see [Troubleshooting](https://docs.sapiensandmachines.com/en/espocrm-voip/troubleshooting#3cx).