Salesforce Phone Integration with Athena: Setup Guide
Set up a Salesforce phone integration with Athena: create an External Client App, sync Contacts, log calls as Tasks, and query Cases and Opportunities live.
A Salesforce phone integration with Athena is a native connection built on a Salesforce External Client App: Athena authenticates with the OAuth 2.0 client credentials flow, acts as a dedicated Run As user, and then syncs Contacts, logs every call as a Salesforce Task, and gives your agents live tools for Contacts, Leads, Accounts, Opportunities, Cases and custom objects. You set it up once in Salesforce Setup and once on the Athena Integrations page.
This guide covers the Salesforce-side setup an admin needs, the connection itself, and the choices that decide what call data lands where.
What you need before connecting Salesforce
Check three things first, because each one blocks the connection if it is missing:
- A Salesforce edition with API access: Enterprise, Unlimited, Developer or Performance
- Professional needs Salesforce's paid API add-on; Essentials has no API access
- System Administrator permissions, or a role that can create External Client Apps
- A dedicated integration user for Athena to run as, not a person's account
- An Admin or Developer role in your Athena workspace
A dedicated integration user matters more than it looks. Every read and write Athena makes is checked against that user's profile and permission sets, so a personal account that changes role or leaves the company quietly breaks syncing.
Create an External Client App with the client credentials flow
In Salesforce, click the gear icon, select Setup, and go to Apps → External Client Apps → External Client App Manager. Click New External Client App and fill in:
- External Client App Name: for example "Athena". Leave the auto-filled API Name as is.
- Contact Email: your admin address.
- Distribution State: leave it on Local, since the app only runs inside your org.
Expand API (Enable OAuth Settings) and turn OAuth on. Enter your Athena Salesforce callback URL as the Callback URL (the client credentials flow never uses it, but Salesforce requires the field). Move Manage user data via APIs (api) into Selected OAuth Scopes; it is the only scope Athena needs. Do not select Full access (full) on its own, because the client credentials flow filters it out and the token request fails. Under Flow Enablement, check Enable Client Credentials Flow, then click Create.
Open the app's Settings tab, expand OAuth Settings and click Consumer Key and Secret. The Consumer Key becomes Athena's Client ID and the Consumer Secret becomes the Client Secret. Treat the secret like a password.
Set the Run As user and its permissions
The client credentials flow has no logged-in person, so Salesforce needs to know whose permissions apply. On the app's Policies tab, click Edit, expand OAuth Policies, check Enable Client Credentials Flow again, and enter the integration user's username in Run As (Username). Use the exact value from Setup → Users → Users, not the email address; in a sandbox the two usually differ.
Check Enable Client Credentials Flow in two places. The checkbox at creation turns the flow on for the app. The one on the Policies tab binds it to the Run As user. Without both, token requests fail even though the flow looks enabled.
Then grant the Run As user only what you will use: API Enabled; Read on Contact and every field you import; Edit on Contact and every field you write back; Create on Task if you log activities. Each agent tool needs its own object permission on top, for example Read on Opportunity for the opportunity tools. A missing field permission does not break the connection. That field just stops syncing, which is harder to spot.
Connect Salesforce in the Athena dashboard
In Athena, open Integrations, select Available, find Salesforce and click Connect. Fill in four fields: Connection name, Instance URL, Client ID and Client Secret.
The Instance URL must be your My Domain URL in the form https://yourdomain.my.salesforce.com, lowercase and with no path. A Lightning URL ending in lightning.force.com is rejected; sandbox domains ending in sandbox.my.salesforce.com are accepted. Find the right value under Setup → Company Settings → My Domain.
Athena tests the credentials against the Salesforce API on connect. A brand-new External Client App can take up to 30 minutes to become available, so if the first attempt fails right after you created it, wait and retry before assuming the credentials are wrong. The Salesforce connection guide in the Athena docs has screenshots of every screen.
Sync Contacts and log every call as a Salesforce Task
After the connection test passes, click Set up contact sync. Athena maps Salesforce Phone to Athena phone_number and locks it, since phone number is the matching key. Map first and last name next, then any custom fields, including __c fields. The first sync scans every Contact with a phone number; after that Athena polls every 5 minutes (as of August 2026) for changed records.
- Contact fields: Direction: Salesforce to Athena, every 5 minutes. Lands in Salesforce as: Read from Contact.
- Post-call analysis fields: Direction: Athena to Salesforce, after each call. Lands in Salesforce as: Updated Contact fields.
- Each call: Direction: Athena to Salesforce. Lands in Salesforce as: Completed Task, Call subtype.
- Each chat: Direction: Athena to Salesforce. Lands in Salesforce as: Completed Task, Task subtype.
- Agent tool writes: Direction: During or after the call. Lands in Salesforce as: Contact, Lead, Account, Task, Note or custom object.
Turn on Log activities automatically on the Sync to Salesforce tab, and each call becomes a Task on the matched Contact: Status Completed, the Call task subtype, a subject of "Call" plus the call ID, and CallDurationInSeconds set. The description carries the call ID, the from and to numbers, the disconnection reason and the summary, so a rep can read the outcome without opening Athena.
Structured outcomes come from post-call analysis. Define a field such as lead_status, map it to a Athena contact field, and map that field to a Salesforce field such as a custom Lead_Status__c on the outbound tab. After each call the new value is pushed to the Contact. Outbound sync updates existing Contacts only, unless you turn on Create new contacts in CRM.
Look up Opportunities, Cases and custom objects during the call
Contact sync only reads the Contact object. For everything else, the agent uses live tools, which appear in the function menu as soon as Salesforce is connected: Search Contact, Get, Create and Update Contact, Get, Create and Update Lead, Get and Update Account, List Account Opportunities, Get Opportunity, Get Case, Get User, Get and Update Custom Object, Query Records, Create Task and Create Note.
Query Records runs a SOQL query you write, with dynamic variables filled in at run time. For example, a support line can pull the caller's open Cases with a query filtered on {{contact_id}}, where that variable came from an earlier Search Contact call. Use Search Contact, not SOQL, to identify the caller, because Search Contact matches across phone formats and a SOQL filter needs an exact string match. Add a LIMIT to every query: Salesforce returns at most 2,000 rows per call, and integration tool responses are capped at 30,000 characters.
Each tool times out after 3 to 8 seconds depending on the tool (as of September 2026). On a timeout the call continues, so tell the agent in its prompt what to say when a lookup does not come back. To run a lookup before the agent speaks, add Search Contact as a pre-call function on the agent's Workflow page, as described in the agent workflow docs.
Fix the common Salesforce connection errors
- The connection fails right after you created the app: wait up to 30 minutes, then confirm Enable Client Credentials Flow is checked in both places and Run As is set.
- Requests are blocked by IP restrictions: Athena calls from cloud IPs, so on the app's Policies tab set IP Relaxation to Relax IP restrictions, or exempt the integration user's profile from login IP ranges.
- The connection worked, then errored: Salesforce rejected the credentials, usually because the secret was rotated or the Run As user was deactivated. Paste current credentials and click Reconnect; mappings and synced contacts are kept.
- Calls are not appearing as Tasks: the caller's number must match a Contact imported by this connection, and the Run As user needs Create on Task.
If you run HubSpot alongside Salesforce, see how to connect Athena to HubSpot; only one CRM connection can drive contact sync at a time, but both can supply tools. Teams in regulated outbound work, such as insurance renewals, often pair this with a SIP connection that keeps their existing numbers. Before rollout, run it through the checks in how to evaluate a voice agent platform before going live.
A common first use for a Salesforce-connected agent is lead qualification on new leads.
Start in a sandbox org if you have one, since sandbox My Domain URLs are accepted. Open the Athena dashboard to connect your org and test a call against real Contact data.

