> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firetone.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipes

> The common integrations, end to end.

## CRM click-to-call with a status callback

1. **Make a key** with the *Click-to-call* preset, allowed from your CRM's
   servers.
2. **When an agent clicks a number**, call `POST /calls`:
   * `from.user_email`: the agent's login;
   * `to`: the number they clicked;
   * `reference`: the CRM's activity id;
   * `callback_url`: your endpoint;
   * an `Idempotency-Key`, in case the CRM retries.
3. **Your endpoint receives** `call.started`, `call.answered` and `call.ended`
   (duration, outcome, recording), each carrying your `reference`. Log the
   call against the activity.
4. **When `recording.ready` arrives**, fetch the recording with
   `GET /cdrs/{call_uuid}/recording/audio`.

## Screen-pop when a customer calls

1. **Subscribe a webhook** to `call.ringing`, or open the
   [live event stream](/api/events) in the agent's browser.
2. **On each event**, look up the caller with
   `GET /contacts/lookup?number={caller}`. It returns the contact, their open
   tickets and what was said on their last calls.
3. **Open the matching CRM record**, using the contact's `external_ref`.

## Have the AI agent call a lead

1. **When a lead comes in**, call `POST /calls/ai` with:
   * `profile_id`: your sales agent's profile;
   * `to`: the lead's number;
   * `variables`: what the form captured (`{"name": "Sam", "interest": "whitening"}`);
   * `reference`: the lead id;
   * `callback_url`: your endpoint.
2. **The agent calls them**, knowing what's in `variables` and following its
   role and SOP.
3. **`conversation.completed` brings the summary.** If the agent booked a
   callback, `callback.requested` names the person assigned. If nobody
   answered, `call.failed` says why, and you can try again later.

## Run a campaign from your system and get each result

1. `POST /campaigns` with a `reference` and a `result_callback_url`.
2. `POST /campaigns/{id}/contacts` with `items`, each with the lead's
   `reference` and `variables`. Send batches of up to 10,000, each with an
   `Idempotency-Key`.
3. `POST /campaigns/{id}/start`.
4. Each `campaign.contact.completed` brings one lead's outcome under its
   reference. `campaign.completed` brings the totals.
5. Anything your endpoint missed can be read back from
   `GET /campaigns/{id}/results?since=…`.

## Sync calls to a data warehouse

1. **Nightly**, call `GET /cdrs/export?from=<yesterday>&to=<today>&format=ndjson`
   with a *Read calls & CDRs* key.
2. **Load the file.** Each row carries `reference`, `contact_id` and
   `campaign_id`, so you can join calls to your own tables.
3. **Allow the job's address** on the key. An export from an address the key
   doesn't allow is refused and shows in **Developer → Request log**.

## Keep contacts in step with your CRM

1. **When a CRM contact is created or changed**, call
   `PUT /contacts/by-reference/{crm id}` with the number, name and any
   attributes. Attributes merge into the existing ones.
2. **When FireTone meets a new caller**, `contact.created` arrives with
   `source: "call"`. Create them in the CRM, then write your id back with the
   same `PUT`.