Telephony Troubleshooting
Common situations met while connecting 3CX, setting up agents and handling calls, with the likely cause and the recommended resolution. Sections follow the order of the Telephony guides.
Five Checks to Make First
Most Telephony questions are answered by one of these five checks.
- Is the 3CX plugin enabled and saved? The 3CX entry under Configuration → System → Plugins must be on, with its host, client ID and API key filled in.
- Has the user been synced? The 3CX Users screen shows extensions and seats used.
- Is the agent on a shift? Without an active shift in a status that allows External Calls, call icons stay greyed out.
- Is the agent in the right group? Group membership decides which queue calls reach them.
- Does the user's role allow the action? A missing recording icon or a blocked screen is often a missing Telephony permission.
Getting Started
| Symptom | Likely Cause | Resolution |
|---|---|---|
| The phone icon beside a number is greyed out. | The agent has no active shift, the status does not allow External Calls, or no softphone is registered. | Start the shift in a status that allows External Calls and make sure the softphone is registered. |
| A call is placed but nothing happens on the phone. | Outbound rules are not set up for the dialed number in 3CX. | Configure the outbound rules in 3CX, then place the call again. |
3CX Plugin
| Symptom | Likely Cause | Resolution |
|---|---|---|
| The plugin saves but data does not arrive. | The API key lacks the access the guide lists, or the host cannot be reached. | Recreate the key with the required access and confirm the two systems can reach each other. |
| The Host field is locked. | A host is already attached to the plugin. | Use Detach to remove the current host, then enter the new one. |
3CX User Sync
| Symptom | Likely Cause | Resolution |
|---|---|---|
| The Sync button is disabled. | Commonly the seat limit has been reached, or a sync is already running. | Check Seats Used on the 3CX Users screen and free a seat, or wait for the sync to finish. |
| A user appears with Active set to No. | The user has been synced but not yet activated. | Open the user and use Activate. |
| The 3CX Users list says No data. | The Synced filter is on and no extension has been synced yet. | Turn the filter off or run a sync. |
Status Management
| Symptom | Likely Cause | Resolution |
|---|---|---|
| An agent cannot take calls although a shift is running. | The status in use logs the agent out of queues. | Move the agent to a status such as Available that keeps them logged into queues. |
| A call status such as Talking cannot be picked. | Call statuses are applied by the platform as a call progresses. | This is expected. Choose break and availability statuses manually only. |
Groups and Queues
| Symptom | Likely Cause | Resolution |
|---|---|---|
| An agent does not receive queue calls. | The agent is not a member of the queue, or is logged out of it by their status. | Add the agent under Groups and check their current status. |
| A ring group rings people who have left the team. | Membership was not updated. | Remove them from the group and save. |
AI Agent
| Symptom | Likely Cause | Resolution |
|---|---|---|
| An AI Agent cannot be created. | The AI Agent seat allowance may have been used up. | Check the Seats Used counter on the AI Agents screen. |
Call Module
| Symptom | Likely Cause | Resolution |
|---|---|---|
| A built in call field cannot be edited or deleted. | System fields are protected. | Add a new field instead. |
| The Layout Builder says No detail layouts found. | No layout has been built for Telephony. The Calls screen itself is built in. | Use New Layout only if the generic record view is used. |
IVR
| Symptom | Likely Cause | Resolution |
|---|---|---|
| The IVR Template dropdown is empty. | No menu exists on the connected 3CX server. | Create the menu on the 3CX server, then reopen the campaign. |
Calling from CRM
| Symptom | Likely Cause | Resolution |
|---|---|---|
| Clicking the phone icon does nothing. | The icon is disabled because there is no active shift or softphone. | Start the shift and register the softphone, then try again. |
Call Records
| Symptom | Likely Cause | Resolution |
|---|---|---|
| The play icon is greyed out for a call. | The call was not recorded. | This is expected for calls without a recording. |
| A user sees the list but cannot play or save a recording. | Listen Call Recordings or Download Call Recordings is set to No access. | Raise the permission on the user's role. |
| The Calls screen shows fewer calls than expected. | Access Call Logs is scoped to Own or Group, or a filter is applied. | Check the role's scope and clear the filters. |
Dispositions
| Symptom | Likely Cause | Resolution |
|---|---|---|
| The Disposition dropdown is empty. | Call Type has not been chosen, or no values are linked to it. | Choose the Call Type first, then check the dependency in the Disposition module. |
Live Call Controls
| Symptom | Likely Cause | Resolution |
|---|---|---|
| A supervisor cannot monitor or whisper. | Silent Monitoring or Call Whisper is set to No access on the role. | Grant the permission to supervisor roles only. |
System Workflows
| Symptom | Likely Cause | Resolution |
|---|---|---|
| An inbound call does not open a popup. | The Inbound Call Popup workflow is switched off or its condition is not met. | Open it under Configuration → Automation and check its status and History. |
Reports
| Symptom | Likely Cause | Resolution |
|---|---|---|
| Abandoned Calls shows only a Filters card. | Gated reports render after Generate Report is clicked. | Click Generate Report. The default date range is already set. |
| Inbound Live & Queue Monitor shows zero for yesterday's calls. | The Call Date filter defaults to Today. | Change the filter chip under the title. |
Permissions
| Symptom | Likely Cause | Resolution |
|---|---|---|
| A user cannot place calls. | Make Outbound Calls is switched off for the role. | Switch it on for the role. |