# Build your own integration

Connect any tool to Chambr, whether or not it's in the
[integrations list](https://developers.chambr.ai/integrations.md). Pick the pattern by what you want to
move.

| You want to… | Use | Page |
|---|---|---|
| Send calls to be scored | `POST /v1/calls` | [Send calls](https://developers.chambr.ai/guides/send-calls.md) |
| Add a recording for playback | Recording upload | [Attach a recording](https://developers.chambr.ai/guides/recordings.md) |
| Sign users in with your identity provider | SAML 2.0 | [SAML single sign-on](https://developers.chambr.ai/integrations/hris/saml-sso.md) |
| Provision and remove users | SCIM 2.0 | Planned: [contact us](https://developers.chambr.ai/integrations/hris.md#user-provisioning-scim) |
| Get scores back into your tool | Not available | [Roadmap](https://developers.chambr.ai/versioning.md#roadmap) |

## The shape of every call integration

1. **Trigger.** A call ends, a transcript is ready, or a nightly job runs.
2. **Map.** Build the request body. The minimum is `provider`, `external_id`,
   `occurred_at` and `transcript`. Add `rep`, `call_type` and
   `transcript.rep_speaker` when you know them.
3. **Send.** `POST /v1/calls` with your [API key](https://developers.chambr.ai/authentication.md).
4. **Retry safely.** The same `(provider, external_id)` never creates a second
   call. See [Idempotency](https://developers.chambr.ai/idempotency.md).
5. **Store the link.** Save the returned `app_url` on your record, so people
   can open the call in Chambr.

## Choosing `provider` and `external_id`

- `provider` is a short, stable name for the tool the call came from:
  `outreach`, `aircall`, `zoom`. Use the same value for every call from that
  tool, forever.
- `external_id` is that tool's own id for the call. Never reuse it across
  tools, and never generate a new one on retry.
- One call sent from two tools is two calls in Chambr. Pick one source per
  call.

## Where to run it

| Runtime | Good for | Watch out for |
|---|---|---|
| Inside the source tool (Apex, a HubSpot workflow) | Real time, no extra servers | Callout and memory limits; no recording upload from Apex |
| An iPaaS (Zapier, Workato, Make) | Teams without developers | Transcript size limits in the iPaaS |
| Your own service or scheduled job | Backfills and full control | Pace requests to the [rate limit](https://developers.chambr.ai/rate-limits.md) |

## By category

### CRM

Send the calls logged on your CRM activities. The
[Salesforce recipe](https://developers.chambr.ai/guides/salesforce.md) is a complete, tested example.

### Call recording and revenue systems

Pull finished calls from the recorder's API, then send the transcript and,
optionally, the recording. The [Outreach recipe](https://developers.chambr.ai/integrations/revenue-systems/outreach.md)
is a worked example of this pattern.

### HRIS and identity

Use SAML for sign-in. Provision users from your identity provider, not your
HRIS; see [HRIS and identity](https://developers.chambr.ai/integrations/hris.md).

### LMS and collaboration

There is nothing to push into Chambr from these tools today. Link to Chambr
practice from your content instead; see [LMS and enablement](https://developers.chambr.ai/integrations/lms.md). For
Slack and Microsoft Teams, Chambr posts a weekly digest itself; see
[Collaboration](https://developers.chambr.ai/integrations/collaboration.md).

## Checklist before you go live

- [ ] Sending the same call twice creates one call in Chambr.
- [ ] A call whose rep isn't a Chambr user is skipped on purpose, or sent
      [without a rep](https://developers.chambr.ai/guides/send-calls.md#send-a-call-without-a-rep).
- [ ] `429` and `5xx` responses are retried with backoff; other `4xx` are not.
- [ ] Backfills are paced to one or two calls a second.
- [ ] The API key lives in a secret store, not in code.
- [ ] You have consent from call participants to share the calls with Chambr.

## Tell us what you built

Email `support@chambr.ai`. Integrations your team builds often become the next
native one.
