# Outreach

Send the calls your reps record in Outreach (Kaia meetings and dialer calls)
to Chambr to be scored, with `POST /v1/calls`. A native Outreach connection is
planned; this recipe works today.

> [!NOTE]
> This is an API recipe: your developer runs it. A native connection, and
> syncing Outreach sequences into practice, are planned.

| | |
|---|---|
| Status | **Planned** (native) · **API recipe** today |
| Direction | Outreach → Chambr |
| Set up by | Your developer, with a Chambr API key from a manager |
| Time | About a day to build and test |
| Data freshness | As often as your job runs |
| Plan | Real Call Scoring |

## What you need

- A Chambr [API key](https://developers.chambr.ai/authentication.md), created by a Chambr manager.
- Access to your call transcripts in Outreach: the Outreach API with Kaia
  recordings (`kaiaRecordings.read`), or Outreach's Kaia daily export.
- For the API route, an app registered in the Outreach Developer Portal.
  Development credentials work for at most 10 users in your Outreach org;
  beyond that, publish the app (org-internal publishing needs no Outreach
  review).
- Reps whose Outreach email is their Chambr login email.

## What gets sent

| Outreach (Kaia recording) | Chambr field | Required | Notes |
|---|---|---|---|
| — | `provider` | Yes | Always `outreach` |
| Recording `id` | `external_id` | Yes | Makes retries safe ([Idempotency](https://developers.chambr.ai/idempotency.md)) |
| `startTime` | `occurred_at` | Yes | RFC 3339, for example `2026-09-28T15:02:14Z` |
| Owner's email and name | `rep.email`, `rep.name` | No | Must be the rep's Chambr login email |
| Participants | `participants` | No | The first `customer` becomes the call's title |
| Transcript lines | `transcript.segments` | Yes | Speaker name, text and start time of each line |
| The owner's speaker name | `transcript.rep_speaker` | No | Skips Chambr's guess at which speaker is the rep |
| Recording and account ids | `metadata` | No | For your reference; never used for scoring |

## Set it up

### 1. Create a Chambr API key

A Chambr manager creates a key under **Real Call Scoring > settings > API
access**. See [Authentication](https://developers.chambr.ai/authentication.md#get-an-api-key).

### 2. Get finished calls from Outreach

List recordings with `GET https://api.outreach.io/api/v2/kaiaRecordings`,
newest first, and keep those whose transcript is ready. Each recording has a
short-lived `transcriptUrl`; fetch it to get the transcript lines. Outreach
limits Kaia requests to 3 a second.

If you use Outreach's Kaia daily export instead, read each line's timestamp,
speaker name and text from the export file.

### 3. Send each call to Chambr

Map the recording to a request and send it:

```json
{
  "provider": "outreach",
  "external_id": "kaia-48213377",
  "occurred_at": "2026-09-28T15:02:14Z",
  "call_type": "discovery",
  "rep": { "email": "sarah.reid@yourcompany.com", "name": "Sarah Reid" },
  "participants": [
    { "role": "rep", "name": "Sarah Reid", "email": "sarah.reid@yourcompany.com" },
    { "role": "customer", "name": "Dana Whitfield", "company": "Acme Freight" }
  ],
  "transcript": {
    "segments": [
      { "speaker": "Dana Whitfield", "text": "Morning. I have about twenty minutes.", "start_ms": 0 },
      { "speaker": "Sarah Reid", "text": "Understood, I will keep it tight.", "start_ms": 4100 }
    ],
    "rep_speaker": "Sarah Reid"
  },
  "metadata": { "outreach": { "kaia_recording_id": "48213377", "account_id": "9921" } }
}
```

`POST` it to `https://api.chambr.ai/v1/calls` with
`Authorization: Bearer <your key>` and a client timeout of at least 60
seconds. A `202` means the call was created; `200` means it already existed.

### 4. Store the link (optional)

Save the response's `app_url` where your team will see it, so they can open
the scored call in Chambr.

## Verify it works

1. Send one call by hand and check the response is `202`.
2. Open the `app_url`. The call is in Chambr, and its score appears within a
   few minutes.
3. Send the same call again. The response is `200` with the same `id`: no
   duplicate.

## Backfill

Send past calls oldest first, one or two a second. Retrying is always safe,
so re-run the backfill after a failure; calls already sent are not
duplicated. See [Rate limits and retries](https://developers.chambr.ai/rate-limits.md#backfills).

## Limitations

- Calls are scored only if the transcript has speaker labels.
- Recordings are optional. To attach one, see
  [Attach a recording](https://developers.chambr.ai/guides/recordings.md).
- Sequences and cadence steps are not read.

## Troubleshooting

| Symptom or error | Cause | Fix |
|---|---|---|
| `rep_not_found` | The owner's email isn't a Chambr login | Invite the rep, or [send without a rep](https://developers.chambr.ai/guides/send-calls.md#send-a-call-without-a-rep) |
| `transcript_unlabeled` | The transcript has no speaker names | Skip the call, or use the export, which names speakers |
| `external_id_conflict` | Same id, different transcript | Keep `external_id` tied to one recording ([Idempotency](https://developers.chambr.ai/idempotency.md)) |
| `429 rate_limited` | Too many requests | Wait `Retry-After` seconds, then retry |

More codes: [Errors](https://developers.chambr.ai/errors.md).

## Disconnect

Stop your job and [revoke the API key](https://developers.chambr.ai/authentication.md#rotate-a-key)
in Chambr. Calls already sent stay in Chambr.
