# Talkdesk for Salesloft — Admin Setup Guide

This guide walks through configuring the integration end to end. Setup happens
on a single page inside Salesloft, organized into four numbered sections. Work
through them in order — later sections depend on values produced by earlier ones.

**Who can do this:** a Salesloft admin who also has admin access in Talkdesk.
**Time required:** roughly 30–45 minutes, plus time to build the Studio Flow if
one does not already exist.

Before starting, confirm your environments meet the **Prerequisites &
Compatibility Checklist**.

---

## Opening the setup page

1. In Salesloft, go to your installed applications.
2. Open **Talkdesk** and choose the option to configure or manage the app.
3. The setup page loads with four sections. Only Salesloft admins can open it.

Your progress is saved per section, so you can leave and return.

---

## Section 1 — Talkdesk API credentials

This gives the integration permission to talk to Talkdesk on your behalf.

**In Talkdesk:** create an OAuth client using the **client-credentials** grant
type, authorized to read users, read call recordings, and start Studio Flow
interactions. Copy its client ID and client secret.

**On the setup page:**

1. **Account Name** — your Talkdesk account subdomain (for example, if you sign
   in at `acme.talkdeskapp.com`, enter `acme`). This forms the base of every API
   request.
2. **Client ID** — from the OAuth client you just created.
3. **Client Secret** — paste it in. Once saved it is masked and cannot be read back.
4. Click **Test** to validate the credentials live against Talkdesk, then save.

> **If the test fails,** the usual causes are a mistyped account subdomain, a
> secret copied with trailing whitespace, or an OAuth client created with the
> wrong grant type. Re-check the grant type first — it's the least visible of
> the three.

---

## Section 2 — Send Talkdesk events to Salesloft

This section is **read-only**. It displays three values you copy *into*
Talkdesk so that completed calls flow back to Salesloft.

The page shows:

- **Base URL** — the endpoint Talkdesk will post to.
- **Tenant ID** — identifies your Salesloft instance, sent as the
  `salesloft-tenant` header.
- **API key** — sent as the `td-integration-api-key` header. Generate it here;
  it is shown once at generation time, so copy it before leaving the page. You
  can regenerate it later, which invalidates the previous key.

**In Talkdesk**, create a **Connections** automation that fires when a call is
dispositioned and posts to the call-logging endpoint shown on the setup page.
Configure it to:

- Send both headers above on every request.
- Include the call disposition, call outcome, and duration.
- Echo back the context values the integration passed into the Studio Flow.
  These are what associate the call with the right Salesloft person, user, and
  cadence step — if they are dropped, calls will log without being linked.

The setup page shows the exact endpoint path and header names to use.

> **Treat the API key like a password.** Anyone holding it can post call
> records into your Salesloft instance. Regenerate it if it may have been exposed.

---

## Section 3 — Send Salesloft events to Talkdesk

This section wires up click-to-call.

1. **Click-to-call URL** — displayed on the page, read-only. Copy it.
2. **In Salesloft**, create a **Webhook Dialer** and paste that URL in as its
   endpoint. Salesloft generates a **callback token** when you save.
3. **Callback token** — paste the token from Salesloft back into the setup page.
   This is how the integration verifies that dial requests genuinely came from
   your Salesloft instance. Requests that fail verification are rejected.
4. **Talkdesk Studio Flow URL** — the invocation URL of the flow that places the
   outbound callback.
5. **Outbound Phone Number** — the default caller ID shown to customers when a
   user has no per-user override. Use E.164 format (for example `+15551234567`).

Save the section.

> **The default outbound number matters.** If it is left unset or wrong, calls
> may display an unexpected number to customers. Verify it before your first
> live call.

---

## Section 4 — Outbound caller-ID mapping

Talkdesk assigns phone numbers to *queues* rather than to individual agents, so
this integration holds the per-user mapping. Each dialing user needs a row here
that links their Salesloft identity to their Talkdesk identity.

**Add or update one user:**

- **Salesloft email** — the user's Salesloft login email.
- **Talkdesk email** — their Talkdesk agent email. Calls are assigned by this
  address, so it must match Talkdesk exactly.
- **Outbound caller ID** *(optional)* — overrides the default from Section 3 for
  this user only.

**Bulk upload** a CSV with these columns, in this order:

```
salesloft_email,talkdesk_email,outbound_caller_id
```

Choose a mode before uploading:

- **Merge** — adds new rows and updates existing ones. Leaves other rows untouched.
- **Replace** — clears the entire mapping and loads only what is in the file.
  Use with care; anyone omitted from the file loses their mapping.

Emails are resolved to Salesloft user IDs when you save, so a typo in a
Salesloft email is reported as an error rather than silently stored. The
**Current mapping** table below shows every saved row.

### How caller ID and agent assignment resolve

**Caller ID** shown to the customer, in priority order:
1. The user's per-user outbound caller ID, if set
2. Otherwise, the default outbound phone number from Section 3

**Agent** the call is assigned to, in priority order:
1. The Talkdesk email on the user's mapping row
2. Otherwise, the user's Salesloft email

If neither resolves to a valid Talkdesk agent, the dial attempt is **rejected**
rather than placed. This is deliberate — a fallback would dial on behalf of the
wrong person.

---

## Verifying your setup

Place one test call and confirm each step:

1. Click **Call** on a person record in Salesloft. Your Talkdesk agent should ring.
2. Answer, then verify the customer sees the expected caller ID.
3. Hang up and disposition the call in Talkdesk.
4. Within moments, a call appears on the person's activity feed in Salesloft, and
   the cadence step advances if the call was placed from a cadence.
5. Shortly afterward, the recording becomes playable on the logged call.

Step 5 is **eventually consistent** — recordings attach after Talkdesk finishes
processing, typically within a couple of minutes. A recording that is not yet
playable immediately after a call is expected behavior, not a failure. See
**How Call Logging Works** for detail.

---

## Common setup issues

| Symptom | Most likely cause |
|---|---|
| Talkdesk credential test fails | Wrong account subdomain, or the OAuth client isn't using the client-credentials grant. |
| Clicking **Call** does nothing | Webhook Dialer not selected as the dialer, or the callback token was not pasted back into Section 3. |
| Dial is rejected | The dialing user has no mapping row, and their Salesloft email doesn't match a Talkdesk agent. |
| Call connects but nothing logs in Salesloft | The Talkdesk Connections automation isn't firing, or is missing the tenant and API-key headers. |
| Call logs, but isn't linked to the person or cadence step | The Connections automation isn't echoing back the context values from the Studio Flow. |
| Wrong number shown to the customer | Per-user caller ID unset and the Section 3 default is wrong or missing. |
| Recording never appears | Confirm the OAuth client can read call recordings, and that call recording is enabled in Talkdesk. |