Recipes

​

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 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.