EspoCRM VoIP integration with 3CX, Asterisk and Twilio

Connect EspoCRM to your phone system with the official VoIP Integration extension, choosing the PBX or service that fits your telephony and planning each setup before build.

On this page

How the official VoIP extension links EspoCRM to your phone system

A sales or service team that wants calls logged and matched to CRM records needs a connector between the phone system and EspoCRM, and the supported route is the official VoIP Integration extension. The EspoCRM VoIP Integration documentation lists connectors for 3CX PBX, the Twilio service, Asterisk servers, Starface servers, the Binotel service and iexPBX servers. Each has its own setup guide, so the first decision is which of these matches the telephony you already run or plan to buy. Confirm with the vendor or provider that your exact version or hosted plan fits the connector you pick before you commit to a design.

This section walks through what the extension needs from each side: the phone system, the EspoCRM instance it talks to, and the network path between them. The rest of this page covers choosing a system, the per-system setup guides, running the connector in Docker, customization and troubleshooting. Read the overview and the guide for your chosen system together, because the connector settings, credentials and reachability requirements differ from one platform to the next. Plan for the PBX or provider side to be reachable from the connector and for administrators on both sides to agree on who owns each credential.

Before you select a PBX, check four things with the vendor and your network team: whether your chosen connector is listed in the documentation for your deployment model, whether the phone system can be reached from wherever the connector runs, who will hold and rotate the API or account credentials, and whether your telephony provider's terms and regions match where your customer data is stored. Note that cloud providers and self-hosted PBXs impose different constraints on firewalls and call routing, so the answers can change the architecture. Treat these checks as inputs to the scope of work, not as afterthoughts once phones are on the desk.

Which PBX or service the VoIP Integration supports

The EspoCRM VoIP Integration extension documents six connectors, split between cloud telephony services and servers you run yourself. Your phone platform decides where call data flows, who maintains the connector, and which setup guide you follow, so confirm the fit before you plan the build.

3CX PBX

3CX is a self-hosted PBX that runs on your own server, so the connector talks to a system your team operates. Confirm which 3CX version your installation runs against the 3CX setup guide in the extension docs, and check that your installation can reach EspoCRM over the network path you plan to use. Ask who on your side manages PBX upgrades, because each upgrade can affect the connection.

Twilio

Twilio is a hosted cloud telephony service, so calls and call metadata pass through Twilio's platform rather than a server you control. Confirm the account type, phone numbers and features your use case needs in the Twilio setup guide, and review the data path with your privacy and security team. Twilio is the only hosted option in this list, which changes how you plan for vendor accounts and billing.

Asterisk server

Asterisk is an open-source PBX engine that you install and operate on infrastructure you control, so your team owns its dial plan, trunks and upgrades. Confirm the Asterisk release and integration method against the Asterisk setup guide before you commit, because the connector's supported features depend on that choice. Plan who will maintain the Asterisk configuration after the EspoCRM project closes.

Starface server

Starface is a self-hosted PBX server, so it sits on your network and the connector depends on its local reachability from EspoCRM. Check the Starface setup guide for the version and feature set the extension supports, and confirm how call records and user mapping will be handled in your environment. Ask your Starface administrator whether the server's update cycle fits your change windows.

Binotel service

Binotel is a hosted telephony service, so you rely on its platform and its API availability for call handling and events. Confirm which Binotel features the extension covers and the account settings you need in the Binotel setup guide. Check where call recordings and call data are stored, because that determines your data processing terms.

iexPBX server

iexPBX is a self-hosted PBX server that runs in your infrastructure, which puts the connector, the PBX and EspoCRM under one network boundary you must secure. Confirm the iexPBX version and supported features in its setup guide, and document which network paths and credentials the connector uses. Ask who will monitor the PBX and the connector once the system is live.

What to check before choosing a PBX for EspoCRM

The first decision is where the phone system will be hosted, because that determines whether the connector can reach the PBX at all. A PBX running in your own data center or cloud account must be reachable from the network where EspoCRM runs, while a hosted or carrier-run service has its own endpoints, authentication model and limits. Confirm whether your team already operates a PBX, and if so which product and version, since the choice then becomes whether to connect to the system you have or to replace it. Asterisk, 3CX and Twilio are integrated in different ways, so an existing platform usually decides most of the work.

Next, check the carrier and trunk requirements and the number of users who will place and receive calls from the CRM. Trunks, SIP registration, number porting and emergency calling rules sit outside EspoCRM and should be settled with your telephony provider first. User count affects extension mapping, licensing on the PBX side and the volume of call events written to CRM records. Ask each vendor and your carrier for the call volume and concurrency they support, and confirm that figure against the connector's own guide rather than assuming it carries over.

Finally, establish whether your organization can expose the PBX API or event interface to the CRM network, and who approves that access. Each supported system in the VoIP Integration overview has its own setup guide, and the guide for your chosen system defines the credentials, ports, event types and features it expects, so read it before committing. Confirm the supported features and versions for each connector directly in the VoIP Integration overview and its linked guides, and plan firewall rules, a dedicated API user with the narrowest permissions the connector accepts, and a test environment before production cutover.

Prerequisites for the VoIP connector and its network path

The connector sits between your EspoCRM instance and the phone system, so both sides need to be ready before any PBX-specific setup starts. The cards below cover the CRM server stack, the extension, the account and credentials on the phone side, the network path between them, and the certificate trust that the connection depends on.

EspoCRM server stack

Confirm the instance runs on a supported stack: PHP 8.3 to 8.5, MySQL 8.0 or newer, MariaDB 10.6 or newer, or PostgreSQL 15, served by Apache, Nginx or IIS. Background jobs need cron or a scheduled task, and the VoIP connector depends on those jobs running. Check that the scheduler is active on the instance before you start, because a stalled scheduler looks like a broken phone integration.

VoIP Integration extension installed

The VoIP Integration is an official extension, so it must be installed and enabled on the instance that will host the connector. Confirm the extension version against the EspoCRM version in use, since the per-system guide states the requirements for each PBX or service. Record the version in your change log so that future CRM upgrades can be checked against it.

PBX or service account

Decide which account the connector will use on the phone side and make it dedicated to this integration. For 3CX, Asterisk, Starface, Binotel, iexPBX and Twilio, the required account type, permissions and credentials differ, so confirm them in the setup guide for your system. Avoid reusing a personal extension or an administrator login, because the account's rights define what the CRM can do on the phone system.

API credentials and secret handling

Generate the credentials the connector needs, store them in a secrets vault or restricted configuration, and limit who can read them. Confirm which secret type each PBX expects and whether the credential can be rotated without a service interruption. Plan rotation and record its owner, since expired or leaked credentials are a common cause of silent connector failure.

Network reachability between CRM and phone system

Map which direction each connection must travel: the CRM calling the PBX API, the PBX or service calling back to the CRM, and the users' browsers reaching both. Confirm firewall rules, NAT, and any VPN or private link for each path. Test with the specific ports and protocols your PBX requires rather than assuming that general access is enough.

Certificate trust on both ends

The CRM server must trust the certificate presented by the phone system or service endpoint, and any internal certificate authority must be installed on the CRM host and its runtime. Self-signed or private CA certificates cause failures that look like network faults, so verify the chain from the CRM server itself rather than from a workstation. Check certificate expiry dates and add them to your renewal calendar.

Configuration sequence from extension install to first logged call

This sequence takes a team from a stock EspoCRM instance to a working phone integration in which a call placed or received on the chosen PBX or service creates a log entry on the correct CRM record. Each step ends with a check so problems surface before the next step begins.

  1. Install and enable the VoIP extension

    An administrator installs the official VoIP Integration extension through the EspoCRM Administration area, then confirms it appears in the installed extensions list and is enabled. Because the connector is an official extension, check that its version matches the EspoCRM core version running on your instance before continuing. Done means the extension shows as active and its settings pages open without errors.

  2. Create the PBX or service credentials

    Your telephony administrator creates the account the CRM will use on the chosen system: a PBX user or API account on 3CX, an Asterisk Manager Interface or ARI user, or a Twilio account with its API credentials. Keep these credentials separate from personal logins and record which network path EspoCRM will use to reach the system. Done means you can authenticate to the phone system from the EspoCRM host using the new credentials, and the test is recorded in your change log.

  3. Configure the connector using its per-system guide

    Open the setup guide for your specific system in the VoIP Integration documentation and enter the host, port, credentials and any system-specific options in the matching settings screen. Do not copy settings between systems, because each PBX or service has its own required fields. Done means the connector saves without validation errors and the connection status or test action reports success.

  4. Map extensions to EspoCRM users

    For each agent, assign the internal extension or phone identity from the telephony system to the matching EspoCRM user record. Confirm that every extension has exactly one owner, because duplicate mappings make calls log to the wrong person. Done means a short sample list of agents shows the correct extension on their user record and no extension is assigned twice.

  5. Confirm the background job runs

    Verify that the scheduled job the connector depends on is present and running. EspoCRM needs cron or a scheduled task configured on the host for background jobs, so confirm this on your server before testing, and check the job's status in the Administration area after it has run once. Done means the job shows a recent successful run and no errors appear in the EspoCRM log.

  6. Place a test call and check the log entry

    Have one mapped agent place an outbound test call and a second mapped user (or an external phone) call the agent inbound. Open the related contact or lead and confirm that each call created a call log entry with the correct direction, participant and time. Done means both test calls appear on the right records, and if one does not, check the mapping in step four and the connector status before repeating.

  7. Record the working configuration

    Document the connector settings, extension mappings, credential owner and the scheduled job details in your runbook, excluding secret values which belong in your secrets store. Note which test cases passed so that future changes can be re-tested against the same list. Done means a colleague who was not involved could repeat the test calls from the written steps.

Running the connector in Docker or on a bare server

The installation script docs describe a script for Ubuntu, Debian and Linux Mint that deploys a Docker-based stack with Nginx and MariaDB, with optional Let's Encrypt certificates and a command.sh utility for backups, restores and upgrades. This is the most predictable environment for the VoIP connector because the vendor defines the stack, but the connector must still reach your PBX or provider from inside the EspoCRM container, not only from the host.

  • Container network path: Test outbound connections from the EspoCRM container to the PBX host, the signaling and media ports, and any provider API endpoints. A host that reaches the PBX does not prove the container can.
  • Firewall and NAT: Confirm that host firewall rules allow traffic from the container network and that any NAT on the PBX side shows the source address you expect.
  • Callback reachability: Services that push events back to EspoCRM need a route to the public hostname the stack serves, so test the Nginx and certificate setup from outside your network.
  • Backups before changes: Run the utility's backup function before editing connector settings or upgrading, and record which settings live in the database and which live in files.

Before go-live, place a test call in each direction and confirm the connector logs show the traffic on the expected path.

How PBX extensions, users and call records map in EspoCRM

This table compares each PBX or service identifier with the EspoCRM field, user or record it should link to, who owns the mapping and what to verify before go-live. Read it as a checklist to agree with your telephony and CRM owners before the connector is configured. The main takeaway is that phone number normalization and extension ownership decide whether calls land on the right record, so both need sign-off first.

IdentifierEspoCRM targetOwnerCheck
PBX extension numberUser record, matched to the extension assigned to that user in the connector setupTelephony admin with CRM adminEach extension maps to one active user, and shared or hot-desk extensions are documented
Trunk or account ID (3CX, Asterisk, Starface)Connector configuration for the phone system, not a contact or user fieldTelephony adminTrunk or server identifiers match the values in the vendor's setup guide for your PBX
Twilio account or phone numberConnector configuration for the Twilio service and the numbers it sends and receives onTelephony admin and finance ownerEach purchased number is assigned to the correct business line and is not shared across teams
Caller number (inbound)Contact, account or lead matched on the normalized phone number fieldCRM admin with sales operationsMatching rule covers mobile, office and direct-dial variants stored on records
Called number (outbound)Activity or call record linked to the contact or lead the user dialedCRM adminOutbound dialing from the UI writes a call record linked to the correct parent entity
Phone number formatStored phone fields in one agreed format, such as country code plus digitsData owner with CRM adminFormat and country default are agreed before any matching or import runs
Unmatched callsRecord created or left unlinked, depending on the rule the business choosesSales operationsRule for duplicates, unknown numbers and internal calls is documented and tested

Customizing call handling with layouts and formula logic

The connector's output is only as useful as the place it lands in EspoCRM, so the first decision is which records and fields your teams actually need to see during and after a call. Call-related data lives in EspoCRM entities, and the Entity Manager is where you decide whether to add fields, change field types, or create a custom entity for call outcomes or dispositions. Before designing around any hook, confirm which customization points the VoIP Integration guide documents for each supported system (3CX, Asterisk, Twilio and the others listed in the overview). Some connector behavior may be fixed by the extension, and building on an undocumented hook can break on upgrade.

Once the fields exist, layouts control what agents see on the detail and list views, and dynamic logic controls when fields appear, become required, or go read-only. For example, a disposition field could be required only when a call status indicates a completed conversation. This is an illustrative pattern, not a documented feature of the connector. Keep these rules simple, test them with each role that handles calls, and record which layouts belong to which team so that a later change does not silently hide data from the people who need it.

Formula Script is EspoCRM's built-in scripting language and runs in before-save scripts configured in the Entity Manager. A before-save formula can, for instance, normalize a phone number format or set a follow-up date based on a disposition. Check that the field names and entity types the formula references match what the connector writes, because a formula that assumes a different value will fail quietly on some calls. Test formulas against real call records in a staging instance, and document every script so that the team responsible for upgrades knows which logic depends on connector output.

Securing the PBX link and the CRM API user

The connector joins two systems that each hold sensitive access: the CRM API and the phone system's credentials. Each card below covers one control on one side of that link, so the integration can be reviewed the same way you review any service account.

Dedicated API user with narrow roles

Create a separate API user for the VoIP connector instead of reusing a person's account or an administrator login. Give it a role that reads and writes only the entities the call flow needs, such as calls, contacts, accounts and users, and deny everything else. Confirm the exact permissions the connector requires with the extension's setup guide for your PBX before you grant them, and review the role after each upgrade.

HMAC over basic authentication

The EspoCRM API supports API key, HMAC and basic authentication for API users. The documentation describes HMAC as the most secure method and basic authentication as not recommended, so choose HMAC where the connector supports it. Ask the connector's documentation which method it uses, and avoid any setup that would force basic authentication over an unencrypted path.

Keep administrators out of daily work

Administrator accounts should not place calls, sync records or run the connector. Use a standard user for daily sales and service work and a separate, rarely used admin account for configuration. If the PBX connector needs elevated rights during setup, remove them once the mapping is verified so the everyday integration path runs with minimal access.

Restrict access by IP address

Limit which addresses can reach the EspoCRM instance and its API, and include the PBX or connector host in the allowlist where it calls the CRM. Check whether the connector calls EspoCRM from a fixed address or a changing one, because a dynamic address will break an allowlist that is too strict. Confirm this with your network team before you enable enforcement.

Short token lifetime and password policy

Shorten the lifetime of authentication tokens so a copied token expires quickly, and enforce a password policy for every human user. Require two-factor authentication for people who sign in through the web interface. Note that EspoCRM's own 2FA is not compatible with OIDC sign-in, so plan the second factor for each login path. Confirm which token settings apply to API users in your version.

Protect PBX credentials and the connector's path

Store the PBX and provider credentials in the connector configuration only, restrict who can view them, and rotate them on a schedule your team can support. Limit the network path between the connector, the PBX and EspoCRM to the ports and hosts the integration needs, and place the connector in a segment that administrators control. Confirm where each PBX type expects credentials to be stored and how the connector transmits them.

Common VoIP connector failures and their likely causes

This table lists the failures teams most often meet when connecting EspoCRM to a PBX or telephony service, with the likely cause, a first diagnostic step and the fix for each. Work down the rows in order, because connectivity and credentials problems often hide the symptoms listed below them. The per-system troubleshooting page in the EspoCRM VoIP Integration docs remains the authoritative source for exact settings.

FailureLikely causeDiagnostic stepFix
Connector not reachable from the CRM networkThe connector or PBX address is not routable from the EspoCRM server, a firewall blocks the port, or the connector runs in a Docker network that the CRM container cannot reachFrom the EspoCRM host or container, test a TCP connection to the connector address and port, and check the container network settingsOpen the required port between the CRM host and the connector, correct the host name or address, and attach both containers to a shared network if using Docker
Credentials rejectedWrong username, password or API secret for the PBX or service account, or the account lacks the permissions the connector needsReview the connector log for the authentication response and confirm the account can log in to the PBX or provider consoleRe-enter credentials exactly as the PBX defines them, and grant the service account the rights listed in the per-system setup guide
Calls not matched to recordsPhone numbers are stored in a format that differs from the number the PBX or provider sends, such as missing country codes or extra separatorsCompare a stored contact number with the raw number in a test call log entryNormalize stored numbers to a consistent format and confirm the matching rules in the per-system troubleshooting page
Extension mappings wrongAn internal extension is assigned to the wrong EspoCRM user, or a user has no extension mapped, so calls route to nobody or to the wrong personList each user with their mapped extension and place a test call from each extensionCorrect the user-to-extension mapping and retest each extension in both call directions
Background jobs not runningThe cron job or scheduled task that EspoCRM requires for background processing is not configured on the server, so queued connector work never runsCheck that the scheduled job runs on the server and review the EspoCRM log for entries from the connectorSchedule the EspoCRM cron job as described in the server configuration docs, then confirm queued jobs are processed
Certificate or TLS errorsThe connector uses a certificate that is self-signed, expired, issued for a different host name, or missing its intermediate chainInspect the certificate presented on the connector port and compare its host name and expiry date with the address EspoCRM usesInstall a valid certificate that matches the host name, include the full chain, and point EspoCRM at the same name rather than an IP address
Connector works in testing but drops calls under loadCapacity of the connector host or the PBX trunk is too small for the call volume, or resource limits are set too low in the containerReview host resource use and connector logs during a busy period, and compare concurrent calls with trunk limitsIncrease host resources or container limits, and confirm trunk and licence capacity with the PBX or provider before go-live

Questions buyers ask before setting up EspoCRM telephony

Does the open-source edition of EspoCRM support the VoIP Integration extension?

The open-source edition can be downloaded and self-hosted for free, according to the EspoCRM pricing page, and the VoIP Integration is one of the official extensions EspoCRM documents. Confirm the extension's licensing terms and whether it is included in any cloud plan before you commit, because extension availability and terms can differ between self-hosted and cloud deployments. Ask the EspoCRM vendor to confirm which edition and extension version your use case needs, and check the VoIP Integration overview for the supported systems list that applies to your PBX.

How long does an EspoCRM telephony integration take?

Duration depends on the number of phone systems, the number of users who need click-to-call and call logging, and how many layouts or custom fields you want to adapt. A single PBX with a short extension list and standard call records is a much smaller job than several systems with custom routing and reporting. Scope, timelines and deliverables are agreed in writing before work starts, so ask for the timeline as part of the written scope rather than a generic estimate.

What does the team need to provide before the work starts?

The integration depends on access and data that only your team controls. Plan to provide:

  • Administrator access to the PBX or service account, with the rights needed to create API or provisioning credentials
  • A current extension list with owners, including shared lines and queues
  • A user mapping that links each EspoCRM user to the correct extension or phone number
  • Network routes from the EspoCRM host to the PBX, and any firewall rules involved
  • Test numbers and a window for test calls
Can our internal IT staff set up EspoCRM telephony on their own?

Yes, if your team already runs EspoCRM and the phone system, and has someone comfortable with PHP-based application configuration, Docker and reading vendor setup guides. The hardest parts are usually not the EspoCRM settings themselves but the PBX-side credentials, call routing and the user-to-extension mapping, which often involve the telephony team. Ask yourself who will own the connector after go-live, who receives upgrade notices, and who troubleshoots when call events stop arriving.

How does the choice between 3CX, Asterisk and Twilio change the effort?

The phone platform determines the setup path, the admin access you need and the operational responsibilities. 3CX and Asterisk run on systems you usually host, so you must plan for PBX configuration, network reachability and their own upgrade cycles. Twilio is a hosted service, so the work centers on account credentials, phone number configuration and webhook or API reachability from your EspoCRM host. Asterisk setups often need more custom dial-plan work, while 3CX tends to depend more on the vendor's own administration model. Confirm each vendor's current setup guide before estimating, because the official docs provide a separate guide per system.

What should a quote for EspoCRM telephony include?

A useful quote lists each component as a separate line so you can compare it with an internal plan. Ask for:

  • The phone systems in scope and the EspoCRM users or roles that will use them
  • Setup per system, including credentials, call logging and click-to-call
  • Docker deployment of the connector, if you run it that way
  • Customization such as layouts, fields or call-record handling
  • Testing with real call scenarios, and a troubleshooting handover
  • Assumptions about your access, environment and change windows
  • What is one-time work and what is recurring support or upgrade work

DeployOpen plans and delivers fixed-scope work from a written scope, and ongoing support is available as a retainer.

What drives the ongoing cost after go-live?

Ongoing cost comes from keeping the connector working as EspoCRM, the PBX or the telephony service changes. Costs rise with the number of phone systems, how often each vendor releases updates, how many users rely on call logging, and how quickly you need fixes when calls stop syncing. Your own hosting, phone service charges and any per-minute telephony fees from the provider are separate from DeployOpen work. Ask the partner to separate one-time setup from recurring support in the quote.

How DeployOpen scopes and delivers the telephony connector

DeployOpen plans, builds and hands over the EspoCRM VoIP connector inside your own infrastructure, starting from the phone systems and services your teams actually use. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.

How we scope

  • Confirm which PBX or service you run (3CX, Asterisk, Twilio, or another supported option) and the version in use.
  • Map which teams click to call, which events create call records, and which users need call history.
  • Record the Docker or hosting model, network paths to the phone system, and who owns each side in the written scope.

How we build

  • Configure the official VoIP Integration extension for each phone system in scope, following its per-system setup guide.
  • Run the connector in Docker in the environment you choose, with access limited to the networks the PBX needs.
  • Customize layouts and call-related fields only where the agreed scope requires, and test calls, logging and errors before handover.

How we hand over

  • Deliver written configuration notes for each phone system, including settings, credentials locations and network requirements.
  • Document the customizations, the test cases run, and the troubleshooting steps your administrators will need.
  • Walk your administrators through daily checks and the known failure points, so your team can run the connector without us.

How we support

  • Offer ongoing support, upgrades and testing as a retainer when you want DeployOpen to keep the connector current.
  • Review connector changes when you upgrade EspoCRM or change your phone system, and confirm compatibility first.
  • Ask for a quote from the written scope, which should list one-time build work separately from any recurring support.

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.