# Caller Intelligence — administrator installation

This is the technical source-installation guide for the specialist performing deployment. Customers seeking assisted setup can start at https://salesforce.dealmachine.com/#admin; they do not need to run these commands themselves.

Release version: see `CallerAppVersion` in the included Salesforce labels and the public release manifest. Updated September 10, 2026.

This ZIP contains Salesforce source metadata for an administrator-assisted installation. It is not an AppExchange package or a one-click package installation link. You do not need to download the private GitHub repository. No customer credentials, personal data, or live connection URLs are included.

## Before you start

- Use an eligible Salesforce org with Apex, API access, and custom platform events. Validate in a sandbox first. Developer Edition is suitable for evaluation.
- Have a Salesforce administrator, a DealMachine account with API access and data credits, and an administrator for your phone provider available. smrtPhone supports answered calls/texts; 360 SMS Open API supports incoming texts in this integration.
- Install the Salesforce CLI: https://developer.salesforce.com/tools/salesforcecli
- Ask the DealMachine installation team to provision your hosted phone connection and number/user routing. Each organization needs its own private endpoint and Salesforce integration authorization. Downloading the app does not provision this connection automatically.
- Left Main is not required to evaluate the app. Left Main compatibility and live 360 SMS delivery still need account testing.

## 1. Connect and validate

Extract the ZIP, open a terminal inside its `caller-intelligence` folder, then run:

```sh
sf org login web --alias caller-intelligence --instance-url https://test.salesforce.com
sf project deploy validate --source-dir force-app --target-org caller-intelligence --test-level RunLocalTests --wait 20
```

Use your Salesforce My Domain login URL instead of `https://test.salesforce.com` when connecting to a Developer Edition or production org. Check the displayed organization carefully before deployment. The namespace-free metadata uses `Caller*` and `DealMachine*` API names; check for existing components with those names before installing into an established org.

## 2. Deploy and grant access

```sh
sf project deploy start --source-dir force-app --target-org caller-intelligence --test-level RunLocalTests --wait 20
sf org assign permset --name DealMachineCaller --target-org caller-intelligence
sf org assign permset --name CallerIntelligenceSetup --target-org caller-intelligence
```

The commands assign access to the signed-in administrator. Assign **DealMachine Caller Panel** to each app user in Salesforce Permission Sets. Assign **Caller Intelligence Setup** only to administrators managing connections. Setup administrators also require permission to manage Named Credentials.

Assign **DealMachine Ingress** only to the dedicated integration user used by the hosted connector. The connector must use that user's Salesforce authorization. For a single-user evaluation, the signed-in administrator can fill both roles. Do not give all app users ingress permission.

For a customer production org, provision a dedicated integration user and an approved OAuth client. Client-credentials flow is supported by the hosted connector; assign the integration user as the run-as user. The initial pilot uses its previously authorized CLI refresh token. Production customer credentials are configured separately and must never reuse the pilot's authorization.

## 3. Connect DealMachine

Open **Caller Intelligence** from the App Launcher. Select the gear (**Connect accounts**), confirm your Salesforce org, and enter your own DealMachine API key. Select **Connect DealMachine**, then **Test DealMachine connection**.

The key is validated before it is saved, encrypted in Salesforce, and cleared from the input after saving. It is used for one DealMachine account per Salesforce org. The public download page and hosted call connector do not receive this key.

## 4. Connect smrtPhone

Have your installation administrator provision an organization-specific HTTPS endpoint and explicitly map each receiving business number and smrtPhone user name to a Salesforce user. The saved phone settings in Salesforce must match this server-side routing.

In Caller Intelligence → Connect accounts:

1. Select **smrtPhone**.
2. Enter the business number receiving calls and texts.
3. Enter the private connection URL supplied for your organization and save.
4. Copy the URL into smrtPhone Admin → Webhooks: https://phone.smrt.studio/webhooks
5. Enable **Incoming SMS** and **Incoming Call Answered** and save the webhook.

Keep the connection URL private; it authorizes inbound events. Never paste it in shared screenshots or support tickets. If exposed, have the installation administrator rotate it. Do not copy another customer's endpoint.

For a different provider, an administrator must implement the supported custom event contract and enable the adapter. Selecting “Another service” alone does not integrate an arbitrary phone system.

### 360 SMS incoming texts

For 360 SMS, choose **360 SMS · incoming texts** and have the installation specialist enable the adapter and map each receiving number to one Salesforce user. Use the private `/hooks/360sms/…` URL supplied for your org. Ask 360 SMS support to configure Open API incoming-message forwarding while preserving the existing 360 SMS inbox and logging. Then send a real incoming text. Voice calls are not connected by this adapter.

Full instructions and limitations are in the included **360-SMS.md**, also available at https://salesforce.dealmachine.com/downloads/360-SMS.md. The guide covers activation, fixed line ownership, routing, native-inbox verification and troubleshooting. The setup screen checks a text for this provider; it does not require an unsupported call test.

## 5. Add the popup to the team's CRM workspace

The included **Caller Intelligence** app has an auto-starting utility. Installing it does not add that utility to other Salesforce apps. To show the popup while reps work in their usual CRM:

1. In **Setup → App Manager**, find the team's **Lightning** CRM app and choose **Edit**.
2. Open **Utility Items (Desktop Only)**, select **Add Utility Item**, and choose **Caller Intelligence**. Keep existing utilities, including the phone provider's softphone.
3. Enable **Start automatically**. Set the label to **Caller Intelligence**, icon to **call**, panel width to **720**, and height to **650**.
4. Save, open that CRM app from the App Launcher, and refresh. Confirm the **Caller Intelligence** button appears in the bottom utility bar. Reps do not need to leave their CRM page or keep the separate Caller Intelligence app open.
5. Repeat for each Lightning app the team uses. Grant the existing CRM app access and **DealMachine Caller Panel** permission set to the intended users.

A Classic-type app, even when displayed inside Lightning Experience, does not have a Lightning utility bar. Create or upgrade to a Lightning workspace first and verify its navigation, custom pages and permissions. The demo uses **Marketing CRM**, a Lightning workspace with the same standard CRM tabs and records as **Marketing CRM Classic**. Customer setups should preserve their existing workflows and utilities.

## 6. Test as the receiving user

Stay on **Home**, **Leads**, or a record inside the configured CRM app with the utility minimized. If a previous caller is selected, choose **Finish viewing** before minimizing to make it idle. Call the configured business number from another phone and answer in smrtPhone. Send a text to that business number. The utility should open over the CRM for the first interaction and show the provider, matched person, and any accessible Salesforce Lead/Contact matches. Further arrivals wait while a caller is selected. Opening the CRM restores recent history quietly; old interactions do not replay as new arrivals.

In Connect accounts, select **Check test events** and check the call and text timestamps. A saved URL is not proof that delivery works. Test routing with every intended receiving user, including a number not already in the CRM. Check the no-match state as well.

smrtPhone currently triggers the panel when the call is answered. Pre-answer ringing is not supported by this integration.

## Personalize the workspace

Use **Customize sections** to drag sections or use Move up/Move down buttons. Show or hide sections, or choose **Reset layout**. The layout is saved for the current Salesforce user in that browser. It does not change other team members' layouts.

## Troubleshooting and operating limits

- **No popup:** confirm the current CRM app is a Lightning app with Caller Intelligence in its utility bar and **Start automatically** enabled. Installing the separate Caller Intelligence app does not attach the popup everywhere. Then verify the webhook, receiver number, routing and user permissions. A selected caller keeps later arrivals in the waiting list; **Finish viewing** returns to idle. Review provider delivery logs if no new interaction reaches Salesforce.
- **Connection error:** use Test DealMachine connection; confirm the customer's key, API entitlement, credits, and Salesforce credential permissions.
- **No person match:** confirm the inbound phone number. The contact may not exist in DealMachine's data. Manual lookup and confirmed lead creation are available.
- **Hosted delivery failure:** the endpoint returns 503 with a retry hint. Salesforce deduplicates retries. Provider retry policy is not guaranteed; monitor provider delivery logs and replay failures. A persistent retry queue is not included in this release.
- **Credits:** phone enrichment and additional data calls can use the customer's DealMachine data credits. The first three associated properties are loaded automatically; further properties load on request. Phone profiles cache for 24 hours per user/number.
- **Data:** phone matches do not verify identity; property associations do not establish current occupancy. Mortgage values can be estimates. Consumer credit reports are not included.
- **Retention:** administrators must define retention for private CallerInteraction records, which contain cached profiles and incoming message content.
- **Rollout:** this is an assisted pilot release. Validate install and workflow in each customer's sandbox before production deployment. A managed package with upgrade automation is not included.

More information and the interactive walkthrough: https://salesforce.dealmachine.com

## Handling back-to-back calls and texts

The first arrival opens automatically when the utility is idle. While a rep is viewing a caller, later arrivals update the waiting count and utility badge without changing that caller, moving the scroll position, opening the utility over other work, or fetching DealMachine details for queued callers.

- **View next waiting** opens the oldest new interaction at the rep's request.
- **Recent activity** shows the caller name when loaded, number, time, call/text type, source and receiving line. Selecting an item restores it. Each rep sees only their own routed interactions.
- **Finish viewing** keeps the current view in session history and returns the utility to idle. The next future arrival can open automatically. Existing waiting interactions remain selectable.
- Loaded details, expanded sections, scroll position, selected match and unfinished lead forms are kept in memory while this panel stays open. Refreshing Salesforce restores recent Salesforce interaction history, but does not restore unsaved lead drafts or expanded sections.

Salesforce restores up to 50 calls/texts from the past seven days. The panel reconciles these summaries every five seconds, including when streaming is available, so multiple arrivals between checks are included. This is a recent-activity window, not a complete audit-log browser; extremely large bursts exceeding the window during a disconnect require reviewing the stored Salesforce interaction records. Manual lookups are included in the current panel session only.

Validate with two calls or texts in quick succession: confirm the first caller remains selected, the second appears as waiting, switching is explicit, a partly completed lead form survives switching back, and each rep sees only their own events. Opening recent activity does not create a Lead. **Create a Salesforce lead** opens a form; **Save lead** performs the creation after the rep confirms the name.


## App update checks and upgrades

Starting with 0.4.0, users assigned **Caller Intelligence Setup** see **Connect accounts → App updates**. The app checks the public release on opening when its last successful check is over 24 hours old, and periodically while open. It caches successful results for 24 hours in that administrator's browser; **Check now** bypasses the cache. Failed automatic checks back off for an hour. Manual retries remain available.

The screen shows the installed version, latest published version and last successful check. A newer version adds a quiet notice to the caller panel. It does not switch callers, open the utility, install components, or affect incoming events. The callout sends only a request for the public release manifest, with no org identifiers, caller records, DealMachine key, or Salesforce authorization. Errors appear only in the detailed update settings.

For a source-installed customer, the installation specialist applies the update:

1. Download the current kit and verify its checksum. Review release notes and any local Salesforce customizations. Back up the org's current metadata before replacing overlapping components.
2. Validate and deploy the full kit in the customer's test environment using the commands above. Include the updated **Caller Intelligence Setup** permission set, **CallerReleaseUpdates** Remote Site Setting and **CallerAppVersion** custom label; deploying the label alone would misreport the installed version.
3. Test the caller workflow and routing. Then arrange the production update with the customer and deploy the same validated kit. Do not replace customer credentials or routing with pilot values.
4. Reload Salesforce, open **Connect accounts → App updates**, and select **Check now**. Confirm the installed version, then test an incoming call and text as each intended receiving user.

Earlier installations need one assisted update to receive the checker. Downloading a kit or opening the release page does not install it. Website and phone-connection improvements are applied automatically; installed Lightning components, Apex, fields and permissions require a Salesforce deployment. This source kit does not provide silent or push installation.

Release notes and nontechnical update help: https://salesforce.dealmachine.com/updates.html