How the ERPNext Exotel integration logs calls and shows caller pop-ups
A sales or support team that takes calls through Exotel and wants call history and caller context inside ERPNext needs the ERPNext Exotel integration. It tracks incoming calls and shows employees a pop-up with existing lead or customer information, and it is configured by pointing an Exotel App Bazaar flow at an ERPNext API URL. In practice this is a configuration of Exotel plus an ERPNext API endpoint, not a generic connector that maps arbitrary telephony events to any DocType. Start by confirming which Exotel account, phone numbers and call flows your team actually uses, because the flow is what sends each call to ERPNext.
Version matters before you configure anything. The ERPNext version 15 migration guide lists the Exotel integration among features moved to separate apps, so on version 15 and later the integration is installed and maintained as its own app rather than as part of core ERPNext. Confirm the app name, its compatibility with your ERPNext and Frappe version, and the supported installation steps in the ERPNext Exotel integration documentation before you plan the build. Ask your implementation partner and Exotel contact to verify that the App Bazaar flow fields and the API endpoint path in the current documentation match your environment.
Plan the lookup behavior with the people who take the calls. The pop-up depends on matching the caller's number against existing Lead and Customer records, so decide how numbers are stored and formatted, including country codes, and who cleans up duplicates first. Also decide who may see caller details, since call logs expose personal data, and check that the ERPNext roles and permissions assigned to those users allow it. A short test with a few known numbers, run on a non-production site, will show whether the lookup and call log behave as your team expects.
What you need before connecting Exotel to ERPNext
Most delays in this integration come from prerequisites that were never checked: an unsupported ERPNext version, an Exotel account without App Bazaar access, or a site that Exotel cannot reach. The cards below cover the version, account, network, app and user decisions that need to be settled before anyone configures a call flow.
Confirm your ERPNext version is supported
Start by checking which ERPNext and Frappe major version your site runs. Version 14 reached end of life on January 31, 2026, so a site still on it needs an upgrade decision before the telephony work begins. Version 15 is planned to be supported until the end of 2027 and version 16 until the end of 2029. Because the Exotel app is split out from the core in version 15, the app you install must match the major version exactly.
Hold an active Exotel account with App Bazaar access
The integration is configured inside Exotel, so the team needs an Exotel account with access to App Bazaar, where the call flow that calls ERPNext is built. Confirm with Exotel which account holder can create flows and which numbers are attached to the flow. Ask who pays for the Exotel account and its number rentals, because those costs recur separately from any ERPNext hosting or services work.
Provide a public ERPNext site over HTTPS
Exotel must reach the ERPNext API URL from the internet, so the site needs a public hostname with a valid TLS certificate. A site that runs only on an internal network or behind a VPN will not receive call events unless you deliberately publish the endpoint. Decide where TLS terminates, which firewall rules allow Exotel traffic, and how you will test the endpoint before pointing a live number at it.
Install the Exotel integration app
The Exotel integration ships as a separate app in version 15 and later, so it does not appear by default on every bench. Install it on the same version as your ERPNext core and confirm the exact app name and install command in the ERPNext Exotel documentation before running anything in production. Plan the install in a staging site first, then repeat it on production during a maintenance window.
Assign ERPNext permissions for leads and customers
The pop-up shows existing Lead and Customer details, and call logs attach to those records, so the users who receive calls need read access to both DocTypes. Create named users rather than a shared login, and check that role permissions let them see the records they should see. Decide who can view call logs and whether any users must be restricted from customer data they do not handle.
Document the telephony and data owners
Name one owner for the Exotel flow, one for the ERPNext site and one for the data that call logs create. Call recordings and phone numbers are personal data in many jurisdictions, so the team should agree how long call logs are kept and who may export them before go-live. Write these owners and decisions into the project plan so changes to numbers, flows or permissions have a clear approver.
Configuration sequence from install to first pop-up
This sequence takes you from a working ERPNext site to a tested inbound call that is logged in ERPNext and shows a caller pop-up with a known lead or customer. Each step ends with a check so you know whether to move on or troubleshoot. Confirm the exact app version and settings against the Exotel integration documentation for your ERPNext release before you begin.
Confirm the ERPNext version and Exotel app availability
Before installing anything, confirm which ERPNext major version your site runs. The version 15 migration guide lists the Exotel integration among features moved to separate apps, so the install path differs between versions. Your ERPNext administrator or implementation lead should check the Exotel Integration documentation for the app and version pairing that matches your site. Done when you have written down the ERPNext version, the Exotel app name and the supported version pairing, and the site owner has signed off on them.
Install the Exotel app on the site
Install the Exotel app for your ERPNext version using the bench command line on a non-production site first, or through the method your deployment uses (bench, Docker or Frappe Cloud). Run the install against the site that will receive calls, then confirm the app appears in the installed apps list. Done when the app shows as installed on the target site and the site restarts without errors in the bench logs.
Enter Exotel account settings in ERPNext
Open the Exotel Settings document in ERPNext and enter the account identifiers and API credentials from your Exotel dashboard. Keep the API key and token out of shared screenshots and tickets, and store them only in the settings record. Enable the integration only after you have verified the credentials. Done when the settings record saves without a validation error and the enabled flag reflects the state you intend.
Copy the ERPNext API URL for the Exotel flow
Copy the ERPNext API endpoint that the integration exposes for incoming call events from the Exotel settings page. The URL must use the public hostname and HTTPS endpoint that Exotel can reach from the internet, not an internal address or localhost. Record the exact URL in your change ticket so the Exotel configuration uses the same value. Done when the URL resolves from outside your network and matches the value shown in ERPNext.
Create the App Bazaar flow in Exotel
In the Exotel dashboard, create an App Bazaar flow for incoming calls and add the ERPNext API URL as the endpoint the flow calls when a call arrives. Keep the flow limited to the test number at this stage. Your Exotel administrator owns this step, and your ERPNext administrator should review the endpoint and parameters before saving. Done when the flow saves and shows the ERPNext endpoint as its target.
Assign a test number and run the flow test
Assign a test virtual number to the flow in Exotel and use the flow test function if your Exotel plan provides it. Check that the test returns a call record in the Exotel log and that ERPNext receives the request at the endpoint. If the request fails, check the endpoint reachability, the credentials and the flow target before retrying. Done when the flow test returns a call record and no error from the endpoint.
Place a test inbound call and check the Call Log
From a mobile phone that is not an existing contact, call the test number. Then open the Call Log list in ERPNext and confirm a new record appears with the caller number, direction and time. Repeat the call from a number that already exists as a lead or customer in your test data. Done when a Call Log record appears for the test call.
Verify the caller pop-up shows a known contact
Call the test number from a phone number that matches a known lead or customer record, and have a logged-in user on the desk with the relevant role open. Confirm the pop-up shows the matching record. Then call from an unknown number to confirm the pop-up behaves as your team expects for new callers. Done when the pop-up displays the known lead or customer, and you have recorded any mismatches in phone number formatting for correction before rollout.
How Exotel call fields map to ERPNext records
This table shows how each part of an Exotel call event is expected to land in ERPNext, from caller lookup to user assignment and deduplication. Read it as a checklist to confirm against your installed app version, since field names in the Exotel integration can change between releases. The main takeaway is that the caller number lookup and the call identifier are the two decisions that most affect data quality.
| Exotel or ERPNext element | Mapping to confirm | Decision for your team |
|---|---|---|
| Caller number | Matched against Lead and Customer phone fields to show the pop-up and link the call | Confirm which phone fields the app searches and how number formats (country code, leading zero) are normalized |
| Unknown caller number | No Lead or Customer found, so the call is logged without a party link | Decide whether to create a Lead, route to a queue or leave the call unlinked for review |
| Call direction | Incoming or outgoing value stored on the call log record | Confirm the direction values the installed version writes and how reports filter on them |
| Call status | Answered, missed or failed state from the Exotel call result | Agree which statuses count as missed for follow-up tasks and reporting |
| Exotel call identifier | Unique call SID stored on the log so repeated callbacks do not create duplicate records | Confirm the field is indexed and unique, and test retries from Exotel during the pilot |
| Employee or extension | Extension or agent number linked to an ERPNext user for ownership of the call log | Maintain a documented mapping of extensions to users and define the fallback when no match exists |
| Call recording link | Recording URL, where Exotel provides one, stored on the log | Confirm retention and access rules for recordings before enabling storage |
Choosing where ERPNext and the Exotel callback run
Frappe Cloud shared benches are the fastest route to a running ERPNext site, and they carry the most limits for telephony work. Server Scripts are disabled by default from version 15, and Frappe Cloud public shared benches do not allow them at all. If your Exotel callback needs custom Python that runs on document events or as an API endpoint, a shared bench will not run it.
- Server Scripts: Public shared benches do not allow them, so custom callback logic cannot live there.
- Standard integration: The Exotel connector itself depends on the app and the API URL you configure, so confirm with your Frappe Cloud plan that the app and endpoint are permitted.
- Support scope: Confirm which parts of the configuration the hosting provider supports and which are your responsibility.
- Upgrades: Platform-managed upgrades reduce operating work but limit when you can test changes.
- Cost: Shared hosting is priced per site, so ask for current plan terms in writing.
Before committing, check whether the callback needs only the standard connector or also custom server-side code, because that answer decides whether this tab is viable.",
A self-hosted deployment built with the bench command line tool gives you full control of the Frappe app server, the scheduler and the custom apps that hold any callback logic. You manage the operating system, database, Redis, workers and TLS yourself. This model is the one to choose when Server Scripts or a custom app must run inside your own infrastructure.
- Server Scripts: Enable them deliberately with the
server_script_enabledsetting, since they are disabled by default from version 15. - Custom apps: Place callback logic in a version-controlled custom app so it survives upgrades.
- Operations: Your team owns backups, patching, restarts and the scheduler.
- Network reach: The callback URL must be reachable from Exotel, so plan the public endpoint, TLS and firewall rules in your own network.
- Verification: Test the callback on a staging site before pointing live Exotel flows at production.
Confirm which ERPNext version your team will run, because server-side behavior and app splits differ between major versions.
Docker Compose is a self-hosted option that packages ERPNext with its supporting services, which makes the environment easier to repeat across staging and production. The frappe_docker repository provides production images and Compose files with services for MariaDB, Redis, background workers, the scheduler, Socket.io and Nginx. It keeps the same Server Script rules as the bench model, so custom callback logic still needs the setting enabled.
- Production files: Use the production Compose configuration as the base, not the single-file demo.
- Services: Confirm that workers and the scheduler are running, because call logging depends on background processing.
- Custom images: Build an image that includes your custom app so the callback code deploys with the platform.
- Secrets: Keep Exotel API credentials out of images and manage them through your standard secret store.
- Updates: Pin image versions and test each upgrade against the callback before rollout.
Review the frappe_docker repository for the current Compose files and the Frappe version each one targets, and confirm the setup with your platform team before production use.",
The single-file demo setup in the frappe_docker repository is marked for short-lived evaluation only. It is useful for a proof of concept that shows the Exotel pop-up and call log in a sandbox, and for a developer confirming that the App Bazaar flow reaches the ERPNext endpoint. It is not a foundation for live telephony.
- Evaluation only: The repository marks this setup for short-lived use, so do not store customer data in it.
- Persistence: Confirm how data volumes, backups and restarts are handled before using any test data you want to keep.
- Public exposure: An evaluation endpoint reachable from the internet needs TLS and access control, which the demo may not provide.
- Migration path: Plan to move the validated configuration into a production Compose or bench environment, with its own database and secrets.
- Scope of test: Limit testing to call logging and pop-up behavior with test numbers.
If the proof of concept succeeds, treat the build as a starting point for production, not as the production system.
The right environment depends on three questions: whether the callback needs Server Scripts or a custom app, who will operate the site, and whether the endpoint must be reachable from Exotel on infrastructure you control. Answer these before selecting a hosting model, because changing environments later means re-testing the Exotel flow and moving data.
- Custom logic: If the callback needs Server Scripts or custom Python, a shared Frappe Cloud bench is not suitable.
- Ownership: Self-hosted models give control but make your team responsible for patching and backups.
- Network: Confirm the callback URL, TLS certificate and firewall path from Exotel to your endpoint.
- Environments: Plan separate staging and production sites with their own Exotel flows.
- Versions: Record the ERPNext version and app versions you tested against.
Before you sign off, ask your implementation partner to confirm the chosen environment supports the exact callback design in writing.
Securing the callback endpoint and Exotel credentials
The Exotel integration exposes an ERPNext API URL to the internet and stores credentials that can read customer data. The cards below cover the transport, secrets, integration user, request validation, logging and pop-up visibility decisions that connect those two exposures.
Serve the API URL over TLS only
The URL you give Exotel is the entry point that receives call events and returns lead or customer details. Serve it only over HTTPS with a valid certificate, redirect plain HTTP, and confirm that the reverse proxy in front of ERPNext does not terminate TLS in a way that exposes the internal hop. Test the endpoint from outside your network after every certificate renewal, because a lapsed certificate silently stops pop-ups.
Restrict who reads Exotel credentials
The Exotel API key and token sit in the ERPNext Exotel settings and can place or read calls on your Exotel account. Limit read access to those settings to a small administrator group, keep them out of reports, exports and shared print formats, and rotate the keys in Exotel if an administrator leaves or a backup is shared. Ask your partner to confirm which DocTypes and fields expose the stored values in your version.
Limit the integration user
Callbacks run as a user account, so that account defines what the integration can touch. Give it only the roles needed to read Lead, Customer and Contact records and to create call log entries, and exclude delete rights and access to accounting or payroll DocTypes. Review its role assignments after each upgrade, since new DocTypes can inherit broad default permissions.
Validate the source of callbacks
An open callback URL lets anyone post fake call events and probe for customer names. Ask Exotel which request signing, IP allowlisting or shared secret options your account and App Bazaar flow support, and confirm them in writing before go-live. Where Exotel offers no verifiable signature, restrict the URL at the proxy, add rate limits and document the residual risk for your security team.
Log failures without sensitive payloads
Failed callbacks need to be traceable, but raw request bodies contain phone numbers and caller names. Record the timestamp, HTTP status, failing step and a masked caller identifier, and keep full payloads out of application logs and error reports. Confirm the retention period for web and error logs in your deployment and align it with your data protection obligations.
Review who sees caller pop-ups
A pop-up shows the name, company and history of whoever is calling, so it exposes customer data to every agent whose session receives it. Map which roles should see which lead and customer records, then check whether the pop-up respects those permissions for each user. Re-run this review when sales territories change or when new employees join the phone queue.
Why calls are missing or pop-ups stay empty
This table lists the most common reasons Exotel calls do not appear in ERPNext or the caller pop-up shows nothing, with the cause and fix for each. Check the rows in order, since a wrong URL or an unreachable site blocks every other step. Items that depend on the ERPNext version or hosting plan should be confirmed in your own environment before you assume the fault lies in the integration.
| Symptom | Likely cause | Fix |
|---|---|---|
| No calls logged at all | The App Bazaar flow points at the wrong ERPNext API URL, often a test site or an old domain | Compare the URL in the Exotel flow with the exact site address in ERPNext and correct it in the flow |
| Calls fail to post | The site is not reachable from Exotel over HTTPS, for example behind a firewall, a private network or with an expired certificate | Confirm the site answers on a public HTTPS address with a valid certificate, then retest a call |
| Integration missing after upgrade | On version 15 the Exotel integration moved to a separate app, so it is not present until installed | Check the ERPNext version migration guide, install the separate Exotel app for your running version, then reconfigure it |
| Pop-up never appears on shared hosting | Server Scripts are disabled by default from version 15 and public shared benches do not allow them | Confirm whether your hosting plan permits Server Scripts, or move the site to a plan or self-hosted setup that does |
| Call logged but no lead or customer linked | No Lead or Customer record stores that phone number, so there is nothing to match | Confirm the contact exists with the number stored in the mobile or phone field, then create the record or import the missing contacts |
| Number not matched despite a record | Format mismatch, such as a leading zero, country code, spaces or a plus sign differing from the number Exotel sends | Standardize how numbers are stored and agree one format with Exotel and your telephony team before testing |
| Call logged but pop-up is empty for a user | The user lacks permission to view the matched Lead, Customer or related record | Review the user's roles and permissions for those DocTypes, then test with the same account |
Questions buyers ask about the Exotel integration
What does the Exotel integration cost, and who pays for each part?
The cost comes from three separate budgets: your Exotel plan, your ERPNext hosting, and the implementation work. ERPNext itself is free and open source, according to the frappe/erpnext repository, and self-hosting it carries no licence fee, so your spend is infrastructure and labour. Exotel charges for its telephony service under your own account, and those fees are set by Exotel, so confirm the plan, number rental and call charges directly with them. Implementation is the variable part. Ask any partner for a written quote that lists the Exotel flow configuration, the ERPNext endpoint setup, testing with real numbers, and what is one-time versus recurring, such as hosting and support.
How long does setup take, and what makes it longer?
The duration depends less on the Exotel configuration itself and more on your data and your environment. Pointing an App Bazaar flow at the ERPNext API URL is a small change, but the pop-up is only useful when phone numbers on leads and customers match the format Exotel sends. Duration grows with the number of customer records that need cleaning, the number of call flows and agents, whether you run a shared or dedicated ERPNext site, and how long your security review of the endpoint takes. Ask for the timeline to be written as phases with the client tasks listed, so you can see which steps depend on your team.
Can our internal team set this up without a partner?
Yes, if you have an engineer who can administer your ERPNext site and an Exotel account owner who can create App Bazaar flows. The work is mostly configuration: creating the flow, pointing it at the ERPNext API URL, and checking that call records appear. The harder parts are phone number normalization, testing across agents and call directions, and keeping the integration working through ERPNext upgrades. Teams without recent Frappe experience usually find the upgrade and debugging steps take longer than the first setup. Confirm with Exotel which App Bazaar features your plan includes before you start.
What do we need to provide before the work starts?
Plan to provide four things. First, administrator access to your Exotel account so the flow can be created and the API details can be retrieved. Second, administrator access to the ERPNext site, or to the bench or container host if you run it yourself. Third, a set of test numbers, ideally including internal extensions and a mobile number for each tester, so that pop-ups can be checked without calling customers. Fourth, a clean-up of phone numbers on leads and customers, since matching depends on consistent formatting. Ask any partner to list these inputs in the quote and state who owns each one.
How do we keep caller data and credentials secure?
Treat the Exotel credentials and the ERPNext endpoint as production secrets. Store API keys in your own secret management, restrict who can view the flow, and limit the ERPNext user that the endpoint acts as to the permissions it needs. Call logs can include personal data, so check how long your organization keeps call records and who can read them through role permissions. Ask the implementation team to document where each credential is stored, how it is rotated, and which ERPNext role the integration runs under.
What changes when we move to ERPNext version 15 or 16?
The ERPNext version 15 migration guide lists the Exotel integration among features moved into separate apps, so you should not assume it works after an upgrade without checking. Install the app that carries the integration on the target version, confirm its compatibility with your ERPNext release, and retest the pop-up and call logging before go-live. Frappe's supported versions page lists version 15 as planned for support until the end of 2027 and version 16 until the end of 2029, so plan the upgrade path against those dates. Ask for the upgrade steps to be part of the written scope.
Who supports the integration after go-live?
Support depends on the platform and on the contract you sign. Frappe's supported versions policy says customers must be on a listed version and subscribed to a matching Frappe Cloud support plan to receive warranty coverage from Frappe, so check that policy if you run on Frappe Cloud. For a self-hosted site, DeployOpen offers ongoing support and upgrades as retainers, which can cover monitoring the flow after Exotel or ERPNext releases. Ask any provider to state in writing who fixes a broken pop-up, the response expectations, and how an Exotel-side change is handled.
What changes for Exotel when you move to ERPNext version 15
The Exotel integration is no longer part of the core ERPNext install in version 15. The ERPNext version 15 migration guide lists the Exotel integration among features moved to separate apps. An upgrade from an earlier version will therefore not carry your call logging and caller pop-ups across on its own. Before you start, read the migration guide at the ERPNext version 15 migration guide and confirm which app name, install command and order of steps apply to your current release. Record the app version you plan to install so the test environment and production match.
Plan the upgrade as a sequence, not a single step. Take a full backup of the site, upgrade ERPNext, install the Exotel app explicitly on the same site, then migrate. After the upgrade, open the Exotel settings and check that the API credentials, account details and the ERPNext API URL that your Exotel App Bazaar flow calls are still present and correct. Confirm that the flow still points at the same site address, since a changed domain, TLS certificate or reverse proxy rule will silently break pop-ups. Check that the call log documents are still being created and that users still have the roles needed to see them.
Before go-live, run a planned test call on a non-production copy of the site. Dial in from a real Exotel number, confirm that a call record appears, and confirm that the pop-up shows the correct lead or customer for a known contact. Repeat the test with an unknown number and with a user who has a limited role. Ask your implementation partner or Exotel account contact to confirm any changes to the flow or API behavior between your old and new versions, and record the results so you can repeat the same checks after each future upgrade.
How DeployOpen works on this
DeployOpen plans, implements, integrates, documents and supports self-hosted open-source platforms inside your own infrastructure, including ERPNext. For the Exotel integration, we start from your call flows, your Exotel account structure and the lead and customer data your teams need on screen, then agree the work in writing before build starts.
How we scope
- Confirm your ERPNext version and whether it runs on Frappe Cloud or your own servers, since that shapes the Exotel setup.
- Map which Exotel numbers, call flows and App Bazaar entries will reach ERPNext, and which teams receive the pop-up.
- Agree the written scope, deliverables and timeline before work starts, as most engagements are fixed-scope.
How we build
- Configure the Exotel integration in a non-production ERPNext site first, and confirm the App Bazaar flow points at the correct ERPNext API URL.
- Test incoming call logging and caller pop-ups against sample leads and customers, including calls from numbers with no matching record.
- Confirm with Exotel that the integration is available in your ERPNext version, since the version 15 migration guide lists it among features moved to separate apps.
How we hand over
- Document the callback URL, App Bazaar configuration, user roles and the steps to repeat the setup on another site.
- Record the ERPNext and Exotel versions tested, the test cases run and the known limits of the caller matching logic.
- Walk your administrators through call log review, troubleshooting and the process for changing Exotel flows later.
How we support
- Offer ongoing support, upgrades and testing as a retainer, covering ERPNext minor releases and any separate Exotel app changes.
- Plan a retest of call logging and pop-ups before each ERPNext major version upgrade or Exotel flow change.
- Ask any support provider to confirm response scope, ownership of credentials and who manages the Exotel account.
