DEV Community

Cover image for Put a Small Endpoint Between Your Voice Agent and Salesforce
Pritesh Kumar for Dograh AI

Posted on Edited on

Put a Small Endpoint Between Your Voice Agent and Salesforce

There's exactly one signal we trust that a call made it into the CRM, and that's the CRM saying so. A success reply from Salesforce means the record exists. Any other reply means it doesn't, and something has to try again.

That rule ends up shaping the whole Salesforce setup for a voice agent. If Salesforce's reply is the receipt, you want something in the middle that can read that reply and act on it, and that also holds the credentials Salesforce cares about. In practice that's a small HTTPS endpoint you own, and every request from the agent goes through it.

The agent can't renew its own token

The two auth models don't line up. Salesforce's server-to-server option, the client credentials flow, hands out short-lived access tokens and no refresh token. When a token stops working, you ask again with the client ID and secret. Voice platforms tend to store a credential as a fixed value. In Dograh, the open-source AI voice agent platform, a credential is an API Key, Bearer Token, Basic Auth or Custom Header, a fixed value you set once.

So the endpoint keeps the Salesforce secret and handles tokens, and the agent only ever sends it a fixed key of yours, say in an X-Bridge-Key header. The endpoint checks that header before it does anything else.

The agent's requests go to your own endpoint, which holds a Salesforce token. It gets the token once with the client ID and secret, sends it with every request, and swaps it for a fresh one when Salesforce stops accepting it.

The renewal logic is short. Fetch a token, reuse it, and when Salesforce answers 401, fetch a fresh one and try once more:

async def sf_request(method: str, path: str, **kwargs) -> httpx.Response:
    for attempt in (0, 1):
        token = await sf_token(force=attempt == 1)
        async with httpx.AsyncClient(timeout=5) as client:
            reply = await client.request(
                method, f"{SF}/services/data/v68.0{path}",
                headers={"Authorization": f"Bearer {token}"}, **kwargs)
        if reply.status_code != 401:
            break
    return reply
Enter fullscreen mode Exit fullscreen mode

sf_token caches the access token and only posts to /services/oauth2/token with grant_type=client_credentials when it has nothing cached or gets forced. After that, nothing downstream has to think about expiry.

Setting up the Salesforce side

New integrations start as an External Client App. Creating new connected apps has been restricted since Spring '26, and Salesforce recommends External Client Apps instead, though connected apps you already have keep working. Enable OAuth and switch on the client credentials flow in the app's OAuth policies. Then pick the run-as user.

That run-as user matters more than it looks. Every action through this flow runs as that user, so give it to a dedicated integration user and keep people's own logins out of it. Enterprise, Unlimited and Performance Edition orgs include five Salesforce Integration user licenses, and the integration user takes the "Minimum Access - API Only Integrations" profile. Add a permission set that can read Contacts and Leads and create Tasks, and stop there. The consumer key and secret go into the endpoint's environment variables, where only your server can read them.

Finding the caller before hello

For inbound calls, the endpoint can look the caller up before the agent speaks. Pre-Call Data Fetch, at the bottom of the Start Call node, POSTs the caller's number in call_inbound.from_number, waits up to 10 seconds, and turns whatever you return under initial_context into variables the prompt can use, like {{first_name}}.

Salesforce stores phone numbers however people typed them, so matching one exact string misses plenty. A parameterizedSearch call with in=PHONE across Contact and Lead, using the last 10 digits of a US number, gets past the formatting mess in a single request. Return the first match's ID and first name, or known_caller: no when there's nothing.

Two cautions here. The caller is listening to ringing while this runs, so keep it quick. And a matching number only gets you a record, so the agent should confirm identity with an approved check, such as date of birth, before it mentions anything it learned from Salesforce.

Outbound calls can skip the search entirely by carrying the Salesforce ID in the campaign CSV or the API Trigger's initial_context.

Writing the call back, receipt in hand

This is where the opening rule pays off. When the call ends, a Webhook node posts the result to the endpoint, which files a Task on the matched Contact or Lead. One field catches people out: TaskSubtype has to be Call on the create request, because Salesforce won't let you change it afterwards. Leave it off and that call sits in the record as a plain task for good.

{
  "Subject": "Voice agent call",
  "Status": "Completed",
  "TaskSubtype": "Call",
  "CallType": "Outbound",
  "CallDurationInSeconds": 184,
  "CallDisposition": "callback_requested",
  "WhoId": "003XXXXXXXXXXXXXXX",
  "Description": "Transcript: <transcript_url from the webhook>"
}
Enter fullscreen mode Exit fullscreen mode

WhoId takes the Contact or Lead ID you found before the greeting, and the call length goes into CallDurationInSeconds as it arrives.

Then hand Salesforce's answer straight back. If Salesforce returns an error, the endpoint returns an error too, and the Webhook node retries temporary failures up to 5 attempts. If Salesforce returns success, the Task exists and you're done. Retries bring their own risk, which is filing the same call twice, so keep the run_id of every Task you've filed and skip any you've already seen.

Self-hosting the platform keeps the client secret and every Salesforce request inside your own network, with caller data moving only between your servers and Salesforce.

Before trusting any of it, place a test call from a real phone and open its View Trace, which shows what the pre-call request and the webhook sent and what your endpoint answered. Then call once from an unknown number and make sure the agent still greets well when there's no match.

How are you handling CRM writes from your voice agents? Do you treat the CRM's reply as the record of truth, or reconcile the logs on a schedule?

The per-step checks and the full phone lookup handler are in our Salesforce voice agent integration walkthrough.

Top comments (0)