Put every conversation to work in your own systems
Thirteen recipes for the developer at a dealership, a service provider or a clinic: find a call and its transcript, follow a customer's alerts and tasks, log calls to your CRM, open tickets, build call-back lists, and feed your warehouse. Each one in curl, Python, PHP and TypeScript.
Before you start
These recipes are for the developer inside a business that uses Intelligence Cloud through its phone provider: Riverbend Auto Group, Harborview Communications, Northgate Dental. You want your call data in front of your own people, in the systems they already use.
| You need | Details |
|---|---|
| A frontline integration user | A dedicated user in your company, named for its purpose, for example crm-sync@example.com. Ask your provider to create it with the access your recipes need (below), and switch MFA off for your company so the integration can sign in. One integration user per purpose. See Credentials and authentication. |
| Username and password today | The integration signs in with that user's email and password and renews its token. API keys are being released in December 2026; the user, its access and these recipes stay the same. |
| Not an admin login | Reseller admin logins see no call data: they get empty lists and 404s. Every recipe here runs as your frontline integration user. Check role with GET /me when a job starts; the SDKs' require_frontline() does it for you. |
| The base URL | https://app.intelligence.cloud/api/v1. HTTPS only, JSON, cursor paging, RFC 3339 timestamps. See Requests and responses. |
| An SDK, or curl | Python, PHP and TypeScript SDKs: download and install. Every recipe also shows the raw requests in curl. |
| The protection rules | Calls carry your customers' names, numbers and words. Read Conversation data protection before you move any of it into another system. |
What the integration user needs for each recipe
| To read | Ask your provider for | Recipes |
|---|---|---|
| Calls, transcripts, tasks | After Call Co-Pilot, with all lines at the locations it covers | 01, 04, 05, 06, 07–10, 12, 13 |
| Alerts | First Alert Co-Pilot, in the group your alert rules notify (for the Base Intelligence Seat, Manager Alerts) | 02, 03, 10 |
| Insights Hub | Insights Hub, in the location's Insights Hub Access group | 12 |
| Webhooks | Your provider saves your receiver's address on each location as its After Call webhook | 05, 06 |
Sign in
Every example assumes a signed-in frontline client called ic. In curl, $IC is the base URL and $TOKEN the access token.
IC=https://app.intelligence.cloud/api/v1
TOKEN=$(curl -s "$IC/auth/login" -H "Content-Type: application/json" \
-d '{"email":"crm-sync@example.com","password":"'"$IC_PASSWORD"'"}' | jq -r .access_token)
import os from intelligence_cloud import Client ic = Client(email="crm-sync@example.com", password=os.environ["IC_PASSWORD"]) ic.intelligence.require_frontline() # raises FrontlineRequiredError for an admin login
use IntelligenceCloud\Client;
$ic = new Client(email: 'crm-sync@example.com', password: getenv('IC_PASSWORD'));
$ic->intelligence->requireFrontline(); // throws FrontlineRequiredError for an admin login
import { Client } from '@intelligence-cloud/sdk';
const ic = new Client({ email: 'crm-sync@example.com', password: process.env.IC_PASSWORD! });
await ic.intelligence.requireFrontline(); // throws FrontlineRequiredError for an admin login
The access token lasts about 15 minutes. The SDKs renew it for you; in curl, renew with POST /auth/refresh and store the new refresh token before you use it.
Two operating rules
Intelligence Cloud tells you when something happens. Your integration never asks over and over.
Webhooks drive anything that must happen as calls and alerts arrive
The After Call webhook fires after every call; the First Alert webhook fires when an alert does. Your receiver answers within seconds, then reads the details from the API. Never poll the API for new data: no timers, no loops that wait for calls to appear.
Everything else is on demand, or once a day over a bounded window
On demand: a person asks, and you read what they asked for. Scheduled: a job runs at most once a day, with an explicit date_from and date_to, such as yesterday's calls for an export or this morning's call-back list.
The same rules are in Webhooks, not polling. If your receiver was down, read the missed window once, as in Catching up after an outage, then go back to the webhooks.
Recipe finder
| Recipe | Trigger | Endpoints |
|---|---|---|
| 01 Get a call's transcript | On demand | GET /calls, GET /calls/{id}/transcript |
| 02 Escalations and alerts for a phone number | On demand | GET /alerts |
| 03 Compare alerts across locations | On demand Daily | GET /locations, GET /alerts/dashboard, GET /alerts |
| 04 Open tasks for a phone number | On demand | GET /calls, GET /tasks |
| 05 Log every call to your CRM | Webhook | After Call webhook, GET /calls/{id}, GET /tasks |
| 06 Turn call follow-ups into helpdesk tickets | Webhook Daily | After Call webhook, GET /tasks |
| 07 Caller history before a call-back | On demand | GET /calls |
| 08 Morning call-back list | Daily | GET /locations, GET /calls |
| 09 Daily overdue follow-ups per location | Daily | GET /locations, GET /tasks |
| 10 Nightly export to a warehouse or BI tool | Daily | GET /calls, GET /alerts, GET /tasks |
| 11 Weekly topic and sentiment trends | Weekly | GET /insights/dashboard, GET /calls, GET /insights/topics/{slug}/calls |
| 12 Find calls that mention a word or phrase | On demand | GET /calls, GET /calls/{id}/transcript |
| 13 Share a recording for coaching or QA | On demand | GET /calls/{id} |
Get a call's transcript
Find the call by the customer's number and the day it happened, then show exactly what was said.
| Recipe | Details |
|---|---|
| Who and when | A support lead settling “what did we tell them on Thursday?”, or a tool that opens a call from a CRM record. |
| Trigger | On demand A person asks. |
| Endpoints | GET /calls (filters), GET /calls/{callId}/transcript |
- Search calls with the number in
searchand the day as a local window:date_fromat midnight,date_toat 23:59:59. - Show the matches (time, direction, summary) and let the person pick one.
- Read that call's transcript and show it line by line.
# 1. the calls with that number on that day (local midnight to midnight) curl -sG "$IC/calls" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "search=5555550142" \ --data-urlencode "date_from=2026-11-12T00:00:00-06:00" \ --data-urlencode "date_to=2026-11-12T23:59:59-06:00" \ --data-urlencode "limit=100" # 2. the transcript of the call the person picked curl -s "$IC/calls/$CALL_ID/transcript" -H "Authorization: Bearer $TOKEN"
from datetime import datetime, timedelta
from zoneinfo import ZoneInfo
day = datetime(2026, 11, 12, tzinfo=ZoneInfo("America/Chicago"))
calls = ic.intelligence.search_calls(phone="+1 (555) 555-0142", date_from=day,
date_to=day + timedelta(days=1, seconds=-1), limit=100)
for call in calls.items: # show these and let the person pick one
print(call["id"], call["call_date"], call["call_type"], call["summary"])
if calls.items:
picked = calls.items[0]["id"]
for line in ic.intelligence.get_transcript(picked):
who = line.get("name") or line["speaker"] # "Speaker 1", "Speaker 2" … when no name is known
print(f'{line["time"]:7.1f}s {who}: {line["text"]}')
$day = new DateTimeImmutable('2026-11-12 00:00:00', new DateTimeZone('America/Chicago'));
$calls = $ic->intelligence->searchCalls(phone: '+1 (555) 555-0142', dateFrom: $day,
dateTo: $day->modify('+1 day -1 second'), limit: 100);
foreach ($calls as $call) { // show these and let the person pick one
echo $call['id'], ' ', $call['call_date'], ' ', $call['call_type'], ' ', $call['summary'], "\n";
}
if (count($calls) > 0) {
$lines = $ic->intelligence->getTranscript($calls->items[0]['id']);
foreach ($lines as $line) {
$who = ($line['name'] ?? '') ?: $line['speaker']; // "Speaker 1", "Speaker 2" … when no name is known
printf("%7.1fs %s: %s\n", $line['time'], $who, $line['text']);
}
}
const calls = await ic.intelligence.searchCalls({
phone: '+1 (555) 555-0142',
dateFrom: '2026-11-12T00:00:00-06:00',
dateTo: '2026-11-12T23:59:59-06:00',
limit: 100,
});
for (const call of calls.items) console.log(call.id, call.call_date, call.call_type, call.summary); // let the person pick
const picked = calls.items[0]?.id;
if (picked) {
for (const line of await ic.intelligence.getTranscript(picked)) {
const who = line.name || line.speaker; // "Speaker 1", "Speaker 2" … when no name is known
console.log(`${(line.time ?? 0).toFixed(1)}s ${who}: ${line.text}`);
}
}
What you get
| Field | Meaning |
|---|---|
id, call_date, call_type, summary | From the call list: enough to pick the right call. |
transcript[].time | Seconds from the start of the call. |
transcript[].speaker | Speaker 1, Speaker 2 … one label per voice on the call. |
transcript[].name, text | The speaker's name when it is known, and what they said. |
Build it right
- Send the day as full timestamps with your offset, for example
2026-11-12T00:00:00-06:00. A date on its own returns 400. - Any number format works in
search:+15555550142,(555) 555-0142, the last four digits, or an extension. At least two characters. - Expect several matches on a busy day: show them and let the person choose.
- Display, don't keep. Show the transcript to the person who asked. Don't write it to logs, tickets or chat.
Escalations and alerts for a phone number
Before a manager calls an unhappy customer back, show every alert on that customer's calls, and which of them were escalations.
| Recipe | Details |
|---|---|
| Who and when | A manager opening a customer record, or an account review before a renewal. |
| Trigger | On demand A person asks. |
| Endpoints | GET /alerts (filters) |
- Read every alert on calls with the number:
numberswith the digits, over an explicit window such as the last 90 days. - For escalations, read again with
keywordset to each rule your company uses for escalation, one rule name per request. Customers on the Base Intelligence Seat have two: Upset Customer and Customer Threat. - Merge by alert
id(one alert can carry several rules) and show them newest first.
# every alert on calls with this number, last 90 days curl -sG "$IC/alerts" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "numbers=5555550142" \ --data-urlencode "date_from=2026-08-18T00:00:00Z" \ --data-urlencode "date_to=2026-11-16T23:59:59Z" \ --data-urlencode "limit=100" # escalations: the same request once per escalation rule, by its exact name curl -sG "$IC/alerts" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "numbers=5555550142" \ --data-urlencode "keyword=Customer Threat" \ --data-urlencode "date_from=2026-08-18T00:00:00Z" \ --data-urlencode "date_to=2026-11-16T23:59:59Z" \ --data-urlencode "limit=100"
from datetime import datetime, timedelta, timezone
ESCALATION_RULES = ["Upset Customer", "Customer Threat"] # your escalation rule names, exactly
now = datetime.now(timezone.utc)
window = dict(numbers=["+1 555-555-0142"], date_from=now - timedelta(days=90), date_to=now)
alerts = list(ic.intelligence.iter_alerts(**window)) # every alert on this customer's calls
escalations = {}
for rule in ESCALATION_RULES: # one rule name per request
for alert in ic.intelligence.iter_alerts(alert_name=rule, **window):
escalations[alert["id"]] = alert # one alert can carry several rules
for alert in sorted(escalations.values(), key=lambda a: a["call_date"], reverse=True):
print(alert["call_date"], " + ".join(alert["keywords"]), alert["call_id"])
$escalationRules = ['Upset Customer', 'Customer Threat']; // your escalation rule names, exactly
$now = new DateTimeImmutable('now', new DateTimeZone('UTC'));
$window = ['numbers' => ['+1 555-555-0142'], 'dateFrom' => $now->modify('-90 days'), 'dateTo' => $now];
$alerts = iterator_to_array($ic->intelligence->iterAlerts(...$window), false); // every alert
$escalations = [];
foreach ($escalationRules as $rule) { // one rule name per request
foreach ($ic->intelligence->iterAlerts(...$window, alertName: $rule) as $alert) {
$escalations[$alert['id']] = $alert; // one alert can carry several rules
}
}
usort($escalations, fn ($a, $b) => strcmp($b['call_date'], $a['call_date']));
foreach ($escalations as $alert) {
echo $alert['call_date'], ' ', implode(' + ', $alert['keywords']), ' ', $alert['call_id'], "\n";
}
import type { Alert } from '@intelligence-cloud/sdk';
const escalationRules = ['Upset Customer', 'Customer Threat']; // your escalation rule names, exactly
const now = new Date();
const range = { numbers: ['+1 555-555-0142'], dateFrom: new Date(now.getTime() - 90 * 86_400_000), dateTo: now };
const alerts: Alert[] = [];
for await (const a of ic.intelligence.iterAlerts(range)) alerts.push(a); // every alert
const escalations = new Map<string, Alert>();
for (const rule of escalationRules) { // one rule name per request
for await (const a of ic.intelligence.iterAlerts({ ...range, alertName: rule })) {
if (a.id) escalations.set(a.id, a); // one alert can carry several rules
}
}
const newestFirst = [...escalations.values()].sort((a, b) => (b.call_date ?? '').localeCompare(a.call_date ?? ''));
for (const a of newestFirst) console.log(a.call_date, (a.keywords ?? []).join(' + '), a.call_id);
What you get
| Field | Meaning |
|---|---|
id, call_id, call_date | The alert, the call it fired on, and when that call happened. |
keywords | The names of the rules that fired. |
caller_name, caller_number, callee_name, callee_number | Who called whom. |
summary, sentiment, sentiment_label | What the call was about and how it went. |
Build it right
keywordis the exact rule name, case-sensitive, one per request.upset customerfinds nothing.numberstakes digits (up to 25 numbers; the SDKs strip+, dashes and spaces). Each matches part of the caller or callee number, so send the full ten digits: four digits match far more calls.searchis the alternative when you have a name or a word rather than a number: it matches names, numbers and summary text.- Send both dates. Without them the window is 00:00 UTC seven days ago until now. With both, the window can be up to 366 days.
- Use the rule names your company configured. Your provider or admin can tell you which rules count as escalations. Rule settings stay in Intelligence Cloud: your integration needs the names only.
Compare alerts across locations
Line up every store, branch or department over the same window: how many alerts, how many calls, the alert rate, and the count for each rule.
| Recipe | Details |
|---|---|
| Who and when | A group operations lead comparing Riverbend Auto Group's North and South stores for last month, or a weekly management pack. |
| Trigger | On demand or Daily at most, for a closed window. |
| Endpoints | GET /locations, GET /alerts/dashboard, GET /alerts (filters) |
- List the locations the integration user can see.
- For each location, read the alert dashboard with
location_idand the samedate_fromanddate_to: new alerts, calls covered, alert rate. - For each rule you compare, read
GET /alertswithkeyword,location_id, the same window andlimit=1, and takesummary.total.
# 1. the locations this user can see curl -sG "$IC/locations" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "is_active=true" --data-urlencode "limit=100" # 2. per location: alerts, calls covered and alert rate for the window curl -sG "$IC/alerts/dashboard" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "location_id=$LOCATION_ID" \ --data-urlencode "date_from=2026-11-01T00:00:00-06:00" \ --data-urlencode "date_to=2026-11-15T23:59:59-06:00" # 3. per location and rule: read data.summary.total curl -sG "$IC/alerts" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "keyword=Upset Customer" \ --data-urlencode "location_id=$LOCATION_ID" \ --data-urlencode "date_from=2026-11-01T00:00:00-06:00" \ --data-urlencode "date_to=2026-11-15T23:59:59-06:00" \ --data-urlencode "limit=1"
from datetime import datetime
from zoneinfo import ZoneInfo
ct = ZoneInfo("America/Chicago")
window = dict(date_from=datetime(2026, 11, 1, tzinfo=ct), date_to=datetime(2026, 11, 15, 23, 59, 59, tzinfo=ct))
RULES = ["Upset Customer", "Customer Threat"]
rows = []
for loc in ic.account.iter_visible_locations(is_active=True):
kpis = ic.intelligence.get_alerts_dashboard(location_ids=[loc["id"]], **window).get("kpis") or {}
row = {"location": loc["location_name"], "alerts": kpis.get("new_alerts", 0),
"calls": kpis.get("monitored", 0), "alert_rate_pct": kpis.get("alert_rate", 0.0)}
for rule in RULES: # the total counts every page
row[rule] = ic.intelligence.search_alerts(alert_name=rule, location_ids=[loc["id"]], limit=1, **window).total
rows.append(row)
for row in sorted(rows, key=lambda r: r["alert_rate_pct"], reverse=True):
print(row)
$tz = new DateTimeZone('America/Chicago');
$window = ['dateFrom' => new DateTimeImmutable('2026-11-01 00:00:00', $tz),
'dateTo' => new DateTimeImmutable('2026-11-15 23:59:59', $tz)];
$rules = ['Upset Customer', 'Customer Threat'];
$rows = [];
foreach ($ic->account->iterVisibleLocations(['is_active' => true]) as $loc) {
$kpis = $ic->intelligence->getAlertsDashboard(...$window, locationIds: [$loc['id']])['kpis'] ?? [];
$row = ['location' => $loc['location_name'], 'alerts' => $kpis['new_alerts'] ?? 0,
'calls' => $kpis['monitored'] ?? 0, 'alert_rate_pct' => $kpis['alert_rate'] ?? 0.0];
foreach ($rules as $rule) { // the total counts every page
$row[$rule] = $ic->intelligence->searchAlerts(...$window, alertName: $rule,
locationIds: [$loc['id']], limit: 1)->total;
}
$rows[] = $row;
}
usort($rows, fn ($a, $b) => $b['alert_rate_pct'] <=> $a['alert_rate_pct']);
print_r($rows);
const range = { dateFrom: '2026-11-01T00:00:00-06:00', dateTo: '2026-11-15T23:59:59-06:00' };
const rules = ['Upset Customer', 'Customer Threat'];
const rows: Record<string, string | number>[] = [];
for await (const loc of ic.account.iterVisibleLocations({ is_active: true })) {
const { kpis } = await ic.intelligence.getAlertsDashboard({ ...range, locationIds: [loc.id!] });
const row: Record<string, string | number> = {
location: loc.location_name ?? '', alerts: kpis?.new_alerts ?? 0,
calls: kpis?.monitored ?? 0, alertRatePct: kpis?.alert_rate ?? 0,
};
for (const rule of rules) { // the total counts every page
const page = await ic.intelligence.searchAlerts({ ...range, alertName: rule, locationIds: [loc.id!], limit: 1 });
row[rule] = page.total ?? 0;
}
rows.push(row);
}
rows.sort((a, b) => Number(b.alertRatePct) - Number(a.alertRatePct));
console.table(rows);
What you get
| Field | Meaning |
|---|---|
kpis.new_alerts | Alerts at the location in the window. |
kpis.monitored | Calls at the location in the window that this user can see. |
kpis.alert_rate | Alerts per 100 calls. |
top_triggered[] | Up to ten rules with their counts, most frequent first. |
summary.total | On GET /alerts: every alert that matches, across all pages. |
Build it right
- Use the same window for every location, as full timestamps in one time zone, and close it in the past for a report that doesn't move.
- Read the total, not the page.
limit=1withsummary.totalgives the count in one small request. - Keep the location list short per request.
location_idtakes a comma-separated list of up to about 50 ids; one location per request is simplest for a comparison. - Compare like with like. A location only shows alerts for rules it has. Compare rule counts between locations that run the same rules.
Open tasks for a phone number
See every follow-up still owed to a customer, from every call with their number.
| Recipe | Details |
|---|---|
| Who and when | A service advisor taking an inbound call, or a CRM panel that shows what's still open. |
| Trigger | On demand A person asks. |
| Endpoints | GET /calls, GET /tasks (filters) |
- Find the calls with the number that still have open tasks:
searchwith the number andhas_open_tasks=true, over an explicit window. - For each call, read its tasks with
call_idandstatus=open. - Show them by due date, with the owner and the call they came from.
# 1. calls with this number that still have open tasks curl -sG "$IC/calls" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "search=5555550142" \ --data-urlencode "has_open_tasks=true" \ --data-urlencode "date_from=2026-08-18T00:00:00Z" \ --data-urlencode "limit=100" # 2. per call: its open tasks curl -sG "$IC/tasks" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "call_id=$CALL_ID" \ --data-urlencode "status=open" \ --data-urlencode "limit=100"
from datetime import datetime, timedelta, timezone
since = datetime.now(timezone.utc) - timedelta(days=90)
open_tasks = []
for call in ic.intelligence.iter_calls(phone="5555550142", has_open_tasks=True, date_from=since):
for task in ic.intelligence.iter_tasks(call_id=call["id"], status="open"):
open_tasks.append((task, call))
for task, call in sorted(open_tasks, key=lambda tc: tc[0]["due_date"] or "9999"):
owner = (task.get("assignee_user") or {}).get("display_name", "unassigned")
print(task["due_date"] or "no due date", task["title"], owner, "from the call on", call["call_date"][:10])
$since = new DateTimeImmutable('-90 days', new DateTimeZone('UTC'));
$openTasks = [];
foreach ($ic->intelligence->iterCalls(phone: '5555550142', hasOpenTasks: true, dateFrom: $since) as $call) {
foreach ($ic->intelligence->iterTasks(callId: $call['id'], status: 'open') as $task) {
$openTasks[] = [$task, $call];
}
}
usort($openTasks, fn ($a, $b) => strcmp($a[0]['due_date'] ?? '9999', $b[0]['due_date'] ?? '9999'));
foreach ($openTasks as [$task, $call]) {
echo $task['due_date'] ?? 'no due date', ' ', $task['title'], ' ',
$task['assignee_user']['display_name'] ?? 'unassigned', ' from the call on ', substr($call['call_date'], 0, 10), "\n";
}
const since = new Date(Date.now() - 90 * 86_400_000);
const openTasks = [];
for await (const call of ic.intelligence.iterCalls({ phone: '5555550142', hasOpenTasks: true, dateFrom: since })) {
for await (const task of ic.intelligence.iterTasks({ callId: call.id!, status: 'open' })) {
openTasks.push({ task, call });
}
}
openTasks.sort((a, b) => (a.task.due_date ?? '9999').localeCompare(b.task.due_date ?? '9999'));
for (const { task, call } of openTasks) {
console.log(task.due_date ?? 'no due date', task.title, task.assignee_user?.display_name ?? 'unassigned',
'from the call on', call.call_date?.slice(0, 10));
}
What you get
| Field | Meaning |
|---|---|
id, call_id, location_id | The task, its call and its location. |
title, description | What has to happen. |
status | The stored status: pending or in_progress for open tasks. |
due_date, assignee_user | When it is due, and who owns it (display_name, email), when set. |
source | ai when After Call Co-Pilot took it from the call, manual when a person added it. |
Build it right
- Find tasks through their calls. The tasks
searchmatches task text, not phone numbers, so start from the calls with the number. has_open_taskstakestrueonly. Any other value is ignored and returns every call.- One
call_idper request onGET /tasks. A customer with many calls means a request per call; thehas_open_tasksfilter keeps that list short. status=opencovers every task not yet done. Useoverduewithtoday_startfor the late ones (recipe 09).
Log every call to your CRM
Moments after each call, the customer's CRM record gets a note: what the call was about, the key points and the follow-ups.
| Recipe | Details |
|---|---|
| Who and when | Every call at the location, as it is processed. Reps see the conversation in the CRM without writing it up. |
| Trigger | Webhook The After Call webhook, plus the once-a-day catch-up. |
| Endpoints | After Call event, GET /calls/{callId}, GET /tasks |
- Run a webhook receiver: check the path token, validate the event, answer 204, skip
is_testevents, de-duplicate oncall.idand queue the id. The receivers in SDKs: Webhook receivers do exactly this. - Your worker reads the call: its direction, the customer's number, the summary and the key points.
- Match the customer's number to a CRM contact: the caller on inbound calls, the callee on outbound calls, compared on the last ten digits.
- Read the call's tasks with
call_idand write one note per call, keyed on the call id. - Once a day, read yesterday's calls and process any
call.idyou haven't logged (Delivery).
# the worker's reads, for each call.id the receiver queued curl -s "$IC/calls/$CALL_ID" -H "Authorization: Bearer $TOKEN" # data.call_type, data.caller_number, data.callee_number # data.analysis.summary.text, data.analysis.summary.key_points curl -sG "$IC/tasks" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "call_id=$CALL_ID" \ --data-urlencode "limit=100"
import re
def last_ten_digits(number):
d = re.sub(r"\D", "", number or "")
return d[-10:] if len(d) >= 10 else d # extensions stay as they are
def log_call_to_crm(call_id: str) -> None: # the worker behind your After Call receiver
call = ic.intelligence.get_call(call_id)
customer = call["callee_number"] if call["call_type"] == "outbound" else call["caller_number"]
contact = crm.find_contact(phone=last_ten_digits(customer))
if contact is None:
return # no match: skip, or open a lead by your own rule
summary = (call.get("analysis") or {}).get("summary") or {}
tasks = ic.intelligence.list_tasks(call_id=call_id, limit=100).items
crm.upsert_note(contact_id=contact["id"], external_id=call_id, # one note per call, even on a repeat
title=f'{call["call_type"].capitalize()} call on {call["call_date"][:10]}',
body=summary.get("text") or call.get("summary") or "",
key_points=summary.get("key_points") or [],
follow_ups=[t["title"] for t in tasks])
use IntelligenceCloud\Client;
function lastTenDigits(?string $number): string
{
$d = preg_replace('/\D/', '', $number ?? '');
return strlen($d) >= 10 ? substr($d, -10) : $d; // extensions stay as they are
}
function logCallToCrm(Client $ic, object $crm, string $callId): void // the worker behind your receiver
{
$call = $ic->intelligence->getCall($callId);
$customer = $call['call_type'] === 'outbound' ? $call['callee_number'] : $call['caller_number'];
$contact = $crm->findContact(lastTenDigits($customer));
if ($contact === null) {
return; // no match: skip, or open a lead by your own rule
}
$summary = $call['analysis']['summary'] ?? [];
$tasks = $ic->intelligence->listTasks(callId: $callId, limit: 100)->items;
$crm->upsertNote(
contactId: $contact['id'],
externalId: $callId, // one note per call, even on a repeat
title: ucfirst($call['call_type']) . ' call on ' . substr($call['call_date'], 0, 10),
body: $summary['text'] ?? $call['summary'] ?? '',
keyPoints: $summary['key_points'] ?? [],
followUps: array_column($tasks, 'title'),
);
}
const lastTenDigits = (n?: string | null) => {
const d = (n ?? '').replace(/\D/g, '');
return d.length >= 10 ? d.slice(-10) : d; // extensions stay as they are
};
export async function logCallToCrm(callId: string): Promise<void> { // the worker behind your receiver
const call = await ic.intelligence.getCall(callId);
const customer = call.call_type === 'outbound' ? call.callee_number : call.caller_number;
const contact = await crm.findContact(lastTenDigits(customer));
if (!contact) return; // no match: skip, or open a lead by your own rule
const summary = call.analysis?.summary ?? {};
const { items: tasks } = await ic.intelligence.listTasks({ callId, limit: 100 });
await crm.upsertNote({
contactId: contact.id,
externalId: callId, // one note per call, even on a repeat
title: `${call.call_type} call on ${call.call_date?.slice(0, 10)}`,
body: summary.text ?? call.summary ?? '',
keyPoints: summary.key_points ?? [],
followUps: tasks.map((t) => t.title ?? ''),
});
}
What you get
| Field | Meaning |
|---|---|
call.id (event) | The id to read and to de-duplicate on. |
call_type | inbound, outbound, internal, missed, forwarded or unknown. |
analysis.summary.text, key_points, action_items | The summary, the key points and the actions the call agreed. |
sentiment_label | How the call went, in words. |
Tasks: title, due_date, assignee_user | The follow-ups taken from the call. |
Build it right
- Answer the webhook first, work second. Respond within 10 seconds, then read the call in your worker.
- Write idempotently. The same
call.idcan arrive more than once (a retry, or a call with several legs). Key the note on the call id so a repeat updates rather than duplicates. - Skip test sends.
is_test: trueevents come from your provider's test button. - Normalise numbers. Records carry E.164 numbers, ten-digit numbers and extensions. Compare on the last ten digits; internal calls between extensions have no customer to match.
- Catch up once a day with yesterday's calls (
date_fromanddate_to), logging any call id you haven't seen. Never read the API on a timer to find new calls.
Send the CRM the minimum it needs: the summary, key points and follow-ups, not the transcript. Don't log event bodies or notes in your receiver or worker; log the call id and your status. Health information in a call follows the agreements you hold with your customers and your CRM vendor. See Conversation data protection.
Turn call follow-ups into helpdesk tickets
Every follow-up a call creates becomes a ticket in your helpdesk, with its due date, its owner and a link back to the call.
| Recipe | Details |
|---|---|
| Who and when | A service desk at Harborview Communications that works from tickets, not from the call list. |
| Trigger | Webhook The After Call webhook, and Daily a catch-up over yesterday's tasks. |
| Endpoints | After Call event, GET /tasks (filters) |
- The same receiver as recipe 05 queues each new
call.id. - Your worker reads the call's open tasks:
call_idandstatus=open. - For each task, look for a ticket that carries the task id. If there is none, create one with the title, description, due date, owner and a link to the call.
- Once a day, read the open tasks created yesterday (
date_fromanddate_toon creation time) and ticket any that have no ticket yet.
# per call.id from the receiver: its open tasks curl -sG "$IC/tasks" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "call_id=$CALL_ID" \ --data-urlencode "status=open" \ --data-urlencode "limit=100" # once a day: open tasks created yesterday curl -sG "$IC/tasks" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "status=open" \ --data-urlencode "date_from=2026-11-15T00:00:00-06:00" \ --data-urlencode "date_to=2026-11-15T23:59:59-06:00" \ --data-urlencode "limit=100"
APP_URL = "https://app.intelligence.cloud" # or the sign-in address your provider gave you
def ticket_for(task):
if helpdesk.find_ticket(external_id=task["id"]):
return # already ticketed: the task id is the key
helpdesk.create_ticket(external_id=task["id"], subject=task["title"],
description=task.get("description") or "",
due=task.get("due_date"),
assignee_email=(task.get("assignee_user") or {}).get("email"),
link=f'{APP_URL}/after-call-copilot/calls/{task["call_id"]}')
def open_tickets_for_call(call_id: str) -> None: # the worker behind your After Call receiver
for task in ic.intelligence.iter_tasks(call_id=call_id, status="open"):
ticket_for(task)
def daily_ticket_catch_up(day_start, day_end) -> None: # once a day, over yesterday
for task in ic.intelligence.iter_tasks(status="open", date_from=day_start, date_to=day_end):
ticket_for(task)
use IntelligenceCloud\Client;
const APP_URL = 'https://app.intelligence.cloud'; // or the sign-in address your provider gave you
function ticketFor(object $helpdesk, array $task): void
{
if ($helpdesk->findTicket($task['id']) !== null) {
return; // already ticketed: the task id is the key
}
$helpdesk->createTicket(
externalId: $task['id'],
subject: $task['title'],
description: $task['description'] ?? '',
due: $task['due_date'] ?? null,
assigneeEmail: $task['assignee_user']['email'] ?? null,
link: APP_URL . '/after-call-copilot/calls/' . $task['call_id'],
);
}
function openTicketsForCall(Client $ic, object $helpdesk, string $callId): void // the receiver's worker
{
foreach ($ic->intelligence->iterTasks(callId: $callId, status: 'open') as $task) {
ticketFor($helpdesk, $task);
}
}
function dailyTicketCatchUp(Client $ic, object $helpdesk, DateTimeInterface $from, DateTimeInterface $to): void
{
foreach ($ic->intelligence->iterTasks(status: 'open', dateFrom: $from, dateTo: $to) as $task) {
ticketFor($helpdesk, $task);
}
}
import type { Task } from '@intelligence-cloud/sdk';
const APP_URL = 'https://app.intelligence.cloud'; // or the sign-in address your provider gave you
async function ticketFor(task: Task): Promise<void> {
if (!task.id || (await helpdesk.findTicket(task.id))) return; // already ticketed: the task id is the key
await helpdesk.createTicket({
externalId: task.id,
subject: task.title ?? '',
description: task.description ?? '',
due: task.due_date ?? null,
assigneeEmail: task.assignee_user?.email ?? null,
link: `${APP_URL}/after-call-copilot/calls/${task.call_id}`,
});
}
export async function openTicketsForCall(callId: string): Promise<void> { // the receiver's worker
for await (const task of ic.intelligence.iterTasks({ callId, status: 'open' })) await ticketFor(task);
}
export async function dailyTicketCatchUp(dayStart: Date, dayEnd: Date): Promise<void> {
for await (const task of ic.intelligence.iterTasks({ status: 'open', dateFrom: dayStart, dateTo: dayEnd })) {
await ticketFor(task);
}
}
What you get
| Field | Use it as |
|---|---|
id | The ticket's external id. It makes every write safe to repeat. |
title, description | Ticket subject and body. |
due_date | The ticket's due date (YYYY-MM-DD), when set. |
assignee_user.email | The ticket's owner, when set. |
call_id, location_id | The link back to the call, and the queue or team to file it under. |
Build it right
- Keep the task id on the ticket. It is how a repeat delivery, the catch-up and a re-run find the ticket that already exists.
- Run the catch-up once a day over a closed window. Task
date_fromanddate_tofilter on when the task was created, as full timestamps. - Link, don't copy. The link opens the call in Intelligence Cloud for anyone allowed to see it. Use the sign-in address your provider gave you if it has its own domain.
- Status flows one way. These recipes read tasks. Close the ticket in your helpdesk and the task in Intelligence Cloud as your process requires.
A ticket needs the task, not the conversation: title, description, due date, owner and the link. Leave summaries and transcripts out of tickets, which many people can read and which live a long time. Health information in a task follows your agreements with your customers and your helpdesk vendor.
Caller history before a call-back
Show a rep every call with this customer before they call back: when, which way, how it went and what was said.
| Recipe | Details |
|---|---|
| Who and when | A rep about to return a call, or a screen-pop when your phone system rings. |
| Trigger | On demand A person opens the customer. |
| Endpoints | GET /calls (filters) |
- Search calls with the customer's number over the last 90 days, with both dates.
- Keep the calls where the number is the caller's or the callee's (a transcript can mention a number too).
- Sort newest first and show the date, direction, outcome, sentiment and the summary's headline.
curl -sG "$IC/calls" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "search=5555550142" \ --data-urlencode "date_from=2026-08-18T00:00:00Z" \ --data-urlencode "date_to=2026-11-16T23:59:59Z" \ --data-urlencode "limit=100" # keep calls whose caller_number or callee_number holds the digits; follow meta.next_cursor while meta.has_more
import re
from datetime import datetime, timedelta, timezone
number = "5555550142"
now = datetime.now(timezone.utc)
def on_call(c): # the number is a party, not just mentioned
return any(number in re.sub(r"\D", "", n or "") for n in (c.get("caller_number"), c.get("callee_number")))
history = [c for c in ic.intelligence.iter_calls(phone=number, date_from=now - timedelta(days=90), date_to=now)
if on_call(c)]
for c in sorted(history, key=lambda c: c["call_date"], reverse=True):
print(c["call_date"][:16], c["call_type"], c["status"], c["sentiment_label"],
c.get("top_highlight") or c.get("summary") or "")
$number = '5555550142';
$now = new DateTimeImmutable('now', new DateTimeZone('UTC'));
$onCall = fn (array $c): bool => // the number is a party, not just mentioned
str_contains(preg_replace('/\D/', '', $c['caller_number'] ?? ''), $number)
|| str_contains(preg_replace('/\D/', '', $c['callee_number'] ?? ''), $number);
$calls = $ic->intelligence->iterCalls(phone: $number, dateFrom: $now->modify('-90 days'), dateTo: $now);
$history = array_values(array_filter(iterator_to_array($calls, false), $onCall));
usort($history, fn ($a, $b) => strcmp($b['call_date'], $a['call_date']));
foreach ($history as $c) {
printf("%s %s %s %s %s\n", substr($c['call_date'], 0, 16), $c['call_type'], $c['status'],
$c['sentiment_label'] ?? '', $c['top_highlight'] ?? $c['summary'] ?? '');
}
import type { CallListItem } from '@intelligence-cloud/sdk';
const number = '5555550142';
const now = new Date();
const digits = (n?: string | null) => (n ?? '').replace(/\D/g, '');
const onCall = (c: CallListItem) => // the number is a party, not just mentioned
digits(c.caller_number).includes(number) || digits(c.callee_number).includes(number);
const history: CallListItem[] = [];
for await (const c of ic.intelligence.iterCalls({ phone: number, dateFrom: new Date(now.getTime() - 90 * 86_400_000), dateTo: now })) {
if (onCall(c)) history.push(c);
}
history.sort((a, b) => (b.call_date ?? '').localeCompare(a.call_date ?? ''));
for (const c of history) {
console.log(c.call_date?.slice(0, 16), c.call_type, c.status, c.sentiment_label, c.top_highlight ?? c.summary ?? '');
}
What you get
| Field | Meaning |
|---|---|
call_date, call_type, duration | When, which way, how long (seconds). |
status | The outcome: completed, missed, voicemail, failed or cancelled. |
sentiment, sentiment_label | How the call went. |
summary, top_highlight, highlights | What was said: the summary, its headline and the key points. |
task_count, completed_task_count | Follow-ups taken and done. The difference is still open (recipe 04). |
Build it right
- Sort it yourself. A number search puts name and number matches first; sort by
call_datefor a timeline. - Check the parties.
searchalso matches transcript text, so a call where someone read the number aloud can appear. Keep calls where the caller or callee number holds the digits. - Page to the end. Follow
next_cursoruntilhas_moreis false; the SDK iterators do it for you. - Read it when the rep asks. Fetch the history when the screen opens rather than keeping a copy that goes stale.
Morning call-back list
Before the doors open, each location gets yesterday's calls that need a call back: the worst-going calls and every voicemail.
| Recipe | Details |
|---|---|
| Who and when | Each Northgate Dental practice manager, by email at 7:00. |
| Trigger | Daily Once each morning, for yesterday. |
| Endpoints | GET /locations, GET /calls (filters) |
- Set yesterday as a local window: midnight to 23:59:59 in the location's time zone.
- Read yesterday's calls three times:
sentiment=crisis,sentiment=very_negativeandstatus=voicemail. One value per request. - Group by
location_id, drop repeats, and send each location its list with the customer's name and number, the reason and the summary.
for f in "sentiment=crisis" "sentiment=very_negative" "status=voicemail"; do
curl -sG "$IC/calls" -H "Authorization: Bearer $TOKEN" \
--data-urlencode "$f" \
--data-urlencode "date_from=2026-11-15T00:00:00-06:00" \
--data-urlencode "date_to=2026-11-15T23:59:59-06:00" \
--data-urlencode "limit=100"
done
# group data.calls[] by location_id; names from GET /locations
from collections import defaultdict
from datetime import datetime, timedelta
from zoneinfo import ZoneInfo
tz = ZoneInfo("America/Chicago")
today = datetime.now(tz).replace(hour=0, minute=0, second=0, microsecond=0)
window = dict(date_from=today - timedelta(days=1), date_to=today - timedelta(seconds=1))
names = {loc["id"]: loc["location_name"] for loc in ic.account.iter_visible_locations()}
by_location = defaultdict(dict)
for reason, f in [("Crisis", {"sentiment": "crisis"}), ("Very negative", {"sentiment": "very_negative"}),
("Voicemail", {"status": "voicemail"})]:
for call in ic.intelligence.iter_calls(**f, **window):
by_location[call["location_id"]].setdefault(call["id"], (reason, call))
for location_id, calls in by_location.items():
lines = []
for reason, c in calls.values():
out = c["call_type"] == "outbound"
name, number = (c["callee_name"], c["callee_number"]) if out else (c["caller_name"], c["caller_number"])
at = datetime.fromisoformat(c["call_date"].replace("Z", "+00:00")).astimezone(tz)
lines.append(f'{at:%H:%M} {name or ""} {number or ""} {reason}: {c.get("summary") or ""}')
mailer.send(location_id=location_id, subject=f"Call-backs for {names.get(location_id, 'your location')}",
lines=lines)
$tz = new DateTimeZone('America/Chicago');
$today = new DateTimeImmutable('today', $tz);
$window = ['dateFrom' => $today->modify('-1 day'), 'dateTo' => $today->modify('-1 second')];
$names = [];
foreach ($ic->account->iterVisibleLocations() as $loc) {
$names[$loc['id']] = $loc['location_name'];
}
$byLocation = [];
$reasons = ['Crisis' => ['sentiment' => 'crisis'], 'Very negative' => ['sentiment' => 'very_negative'],
'Voicemail' => ['status' => 'voicemail']];
foreach ($reasons as $reason => $filter) {
foreach ($ic->intelligence->iterCalls(...$window, ...$filter) as $call) {
$byLocation[$call['location_id']][$call['id']] ??= [$reason, $call];
}
}
foreach ($byLocation as $locationId => $calls) {
$lines = [];
foreach ($calls as [$reason, $c]) {
$out = $c['call_type'] === 'outbound';
$name = $out ? $c['callee_name'] : $c['caller_name'];
$number = $out ? $c['callee_number'] : $c['caller_number'];
$at = (new DateTimeImmutable($c['call_date']))->setTimezone($tz)->format('H:i');
$lines[] = "$at " . ($name ?? '') . ' ' . ($number ?? '') . " $reason: " . ($c['summary'] ?? '');
}
$mailer->send(locationId: $locationId, subject: 'Call-backs for ' . ($names[$locationId] ?? 'your location'),
lines: $lines);
}
import type { CallListItem } from '@intelligence-cloud/sdk';
const day = '2026-11-15'; // yesterday, in the locations' time zone
const range = { dateFrom: `${day}T00:00:00-06:00`, dateTo: `${day}T23:59:59-06:00` };
const names = new Map<string, string>();
for await (const loc of ic.account.iterVisibleLocations()) names.set(loc.id!, loc.location_name ?? '');
const byLocation = new Map<string, Map<string, [string, CallListItem]>>();
const reasons = [['Crisis', { sentiment: 'crisis' }], ['Very negative', { sentiment: 'very_negative' }],
['Voicemail', { status: 'voicemail' }]] as const;
for (const [reason, f] of reasons) {
for await (const c of ic.intelligence.iterCalls({ ...range, ...f })) {
const calls = byLocation.get(c.location_id!) ?? new Map();
if (!calls.has(c.id!)) calls.set(c.id!, [reason, c]);
byLocation.set(c.location_id!, calls);
}
}
for (const [locationId, calls] of byLocation) {
const lines = [...calls.values()].map(([reason, c]) => {
const out = c.call_type === 'outbound';
const at = new Date(c.call_date!).toLocaleTimeString('en-US', { timeZone: 'America/Chicago', hour: '2-digit', minute: '2-digit' });
return `${at} ${(out ? c.callee_name : c.caller_name) ?? ''} ${(out ? c.callee_number : c.caller_number) ?? ''} ${reason}: ${c.summary ?? ''}`;
});
await mailer.send({ locationId, subject: `Call-backs for ${names.get(locationId) ?? 'your location'}`, lines });
}
What you get
| Field | Use it as |
|---|---|
location_id | Which list the call goes on. |
caller_name, caller_number (or callee, on outbound calls) | Who to call back. |
sentiment, status | Why they are on the list. |
summary | What the call was about, so the call back starts informed. |
Build it right
- One value per filter.
sentimentandstatuseach take one value, so read each band and the voicemails separately and merge on the callid. - Yesterday means the location's yesterday. Send both ends with the local offset; a run at 07:00 then always covers the same 24 hours.
- Once a day. The list is a morning job over a closed window. Calls that go badly during the day reach managers through First Alert.
- Add your own rules on top: skip numbers already called back today, or calls under 20 seconds, using
duration.
A call-back list needs identity, so it carries names and numbers: send it only to the location's managers, by a channel your company controls, and don't keep old lists. Leave transcripts out. Health information follows your agreements with your customers.
Daily overdue follow-ups per location
Each location's manager starts the day with the follow-ups that are past due, who owns them, and a link to each call.
| Recipe | Details |
|---|---|
| Who and when | The service manager at each Riverbend store, every weekday morning. |
| Trigger | Daily Once each morning. |
| Endpoints | GET /locations, GET /tasks (filters) |
- Work out today's local midnight for the locations, as a full timestamp with the offset.
- Read every task with
status=overdueandtoday_startset to that midnight. - Group by
location_idand send each location its list, oldest due date first.
curl -sG "$IC/tasks" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "status=overdue" \ --data-urlencode "today_start=2026-11-16T00:00:00-06:00" \ --data-urlencode "limit=100" # group data[] by location_id; follow meta.next_cursor while meta.has_more
from collections import defaultdict
from datetime import datetime
from zoneinfo import ZoneInfo
APP_URL = "https://app.intelligence.cloud" # or the sign-in address your provider gave you
today_start = datetime.now(ZoneInfo("America/Chicago")).replace(hour=0, minute=0, second=0, microsecond=0)
names = {loc["id"]: loc["location_name"] for loc in ic.account.iter_visible_locations()}
digest = defaultdict(list)
for task in ic.intelligence.iter_tasks(status="overdue", today_start=today_start):
digest[task["location_id"]].append(task)
for location_id, tasks in digest.items():
lines = [f'{t["due_date"]} {t["title"]} ({(t.get("assignee_user") or {}).get("display_name", "unassigned")}) '
f'{APP_URL}/after-call-copilot/calls/{t["call_id"]}'
for t in sorted(tasks, key=lambda t: t["due_date"] or "")]
mailer.send(location_id=location_id,
subject=f"{len(tasks)} overdue follow-ups at {names.get(location_id, 'your location')}", lines=lines)
const APP_URL = 'https://app.intelligence.cloud'; // or the sign-in address your provider gave you
$todayStart = new DateTimeImmutable('today', new DateTimeZone('America/Chicago'));
$names = [];
foreach ($ic->account->iterVisibleLocations() as $loc) {
$names[$loc['id']] = $loc['location_name'];
}
$digest = [];
foreach ($ic->intelligence->iterTasks(status: 'overdue', todayStart: $todayStart) as $task) {
$digest[$task['location_id']][] = $task;
}
foreach ($digest as $locationId => $tasks) {
usort($tasks, fn ($a, $b) => strcmp($a['due_date'] ?? '', $b['due_date'] ?? ''));
$lines = array_map(fn ($t) => sprintf('%s %s (%s) %s/after-call-copilot/calls/%s', $t['due_date'],
$t['title'], $t['assignee_user']['display_name'] ?? 'unassigned', APP_URL, $t['call_id']), $tasks);
$mailer->send(locationId: $locationId,
subject: count($tasks) . ' overdue follow-ups at ' . ($names[$locationId] ?? 'your location'), lines: $lines);
}
import type { Task } from '@intelligence-cloud/sdk';
const APP_URL = 'https://app.intelligence.cloud'; // or the sign-in address your provider gave you
const todayStart = '2026-11-16T00:00:00-06:00'; // today's local midnight
const names = new Map<string, string>();
for await (const loc of ic.account.iterVisibleLocations()) names.set(loc.id!, loc.location_name ?? '');
const digest = new Map<string, Task[]>();
for await (const t of ic.intelligence.iterTasks({ status: 'overdue', todayStart })) {
digest.set(t.location_id!, [...(digest.get(t.location_id!) ?? []), t]);
}
for (const [locationId, tasks] of digest) {
tasks.sort((a, b) => (a.due_date ?? '').localeCompare(b.due_date ?? ''));
const lines = tasks.map((t) => `${t.due_date} ${t.title} (${t.assignee_user?.display_name ?? 'unassigned'}) ` +
`${APP_URL}/after-call-copilot/calls/${t.call_id}`);
await mailer.send({ locationId, subject: `${tasks.length} overdue follow-ups at ${names.get(locationId) ?? 'your location'}`, lines });
}
What you get
| Field | Use it as |
|---|---|
title, due_date | What is late, and since when. |
assignee_user.display_name | Who owns it, when set. |
location_id, call_id | Which digest it goes in, and the link to the call. |
summary (response) | Counts by status: total, done, in_progress, pending, overdue. The counts ignore the status filter. |
Build it right
- Always send
today_startas your local midnight, for example2026-11-16T00:00:00-06:00. It decides which tasks count as overdue for your day. - Statuses are display statuses:
overdueis not done and due before today;in_progressis due today or later;pendinghas no due date;doneis completed. - Tasks have no default date window.
status=overduealone reads every overdue task, however old. - One location per digest. Add
location_idto read one location at a time if each runs on its own schedule.
The digest carries task titles, owners and links, not conversations. Task titles can name a customer or a treatment: send the digest only to that location's managers. Health information follows your agreements with your customers.
Nightly export to a data warehouse or BI tool
Every night, yesterday's calls, alerts and tasks land in your warehouse, ready to join with sales, service and staffing data.
| Recipe | Details |
|---|---|
| Who and when | A data team feeding dashboards in your BI tool. |
| Trigger | Daily Once a night, for yesterday. |
| Endpoints | GET /calls, GET /alerts, GET /tasks |
- Set the window: yesterday's local midnight to today's, as full timestamps.
- Read the calls and the alerts for the window, paging with
cursoruntilhas_moreis false. - Read the tasks created in the last 30 days, so status changes on recent tasks land too.
- Upsert each table on
id. Hash phone numbers; keep ids, dates, counts and labels.
FROM=2026-11-15T00:00:00-06:00; TO=2026-11-16T00:00:00-06:00
for path in calls alerts; do
curl -sG "$IC/$path" -H "Authorization: Bearer $TOKEN" \
--data-urlencode "date_from=$FROM" --data-urlencode "date_to=$TO" --data-urlencode "limit=100"
done
curl -sG "$IC/tasks" -H "Authorization: Bearer $TOKEN" \
--data-urlencode "date_from=2026-10-17T00:00:00-05:00" --data-urlencode "date_to=$TO" --data-urlencode "limit=100"
# each: pass meta.next_cursor back as cursor (URL-encoded) until meta.has_more is false
import hashlib, hmac, os, re
from datetime import datetime, timedelta
from zoneinfo import ZoneInfo
KEY = os.environ["NUMBER_HASH_KEY"].encode() # your secret; the same key every night
def hashed(number):
d = re.sub(r"\D", "", number or "")[-10:]
return hmac.new(KEY, d.encode(), hashlib.sha256).hexdigest() if d else None
today = datetime.now(ZoneInfo("America/Chicago")).replace(hour=0, minute=0, second=0, microsecond=0)
start = today - timedelta(days=1)
warehouse.upsert("calls", key="id", rows=[{
"id": c["id"], "location_id": c["location_id"], "call_date": c["call_date"], "call_type": c["call_type"],
"status": c["status"], "duration": c["duration"], "sentiment": c.get("sentiment_label"),
"tasks": c["task_count"], "caller": hashed(c.get("caller_number")), "callee": hashed(c.get("callee_number")),
} for c in ic.intelligence.iter_calls(date_from=start, date_to=today)])
warehouse.upsert("alerts", key="id", rows=[{
"id": a["id"], "call_id": a["call_id"], "call_date": a["call_date"], "rules": a["keywords"],
"sentiment": a.get("sentiment_label"),
} for a in ic.intelligence.iter_alerts(date_from=start, date_to=today)])
warehouse.upsert("tasks", key="id", rows=[{ # 30 days back, so status changes land
"id": t["id"], "call_id": t["call_id"], "location_id": t["location_id"], "status": t["status"],
"source": t["source"], "due_date": t["due_date"], "created_at": t["created_at"], "completed_at": t["completed_at"],
} for t in ic.intelligence.iter_tasks(date_from=today - timedelta(days=30), date_to=today)])
$key = getenv('NUMBER_HASH_KEY'); // your secret; the same key every night
$hashed = function (?string $number) use ($key): ?string {
$d = substr(preg_replace('/\D/', '', $number ?? ''), -10);
return $d === '' ? null : hash_hmac('sha256', $d, $key);
};
$today = new DateTimeImmutable('today', new DateTimeZone('America/Chicago'));
$start = $today->modify('-1 day');
$rows = [];
foreach ($ic->intelligence->iterCalls(dateFrom: $start, dateTo: $today) as $c) {
$rows[] = ['id' => $c['id'], 'location_id' => $c['location_id'], 'call_date' => $c['call_date'],
'call_type' => $c['call_type'], 'status' => $c['status'], 'duration' => $c['duration'],
'sentiment' => $c['sentiment_label'] ?? null, 'tasks' => $c['task_count'],
'caller' => $hashed($c['caller_number'] ?? null), 'callee' => $hashed($c['callee_number'] ?? null)];
}
$warehouse->upsert('calls', key: 'id', rows: $rows);
$rows = [];
foreach ($ic->intelligence->iterAlerts(dateFrom: $start, dateTo: $today) as $a) {
$rows[] = ['id' => $a['id'], 'call_id' => $a['call_id'], 'call_date' => $a['call_date'],
'rules' => $a['keywords'], 'sentiment' => $a['sentiment_label'] ?? null];
}
$warehouse->upsert('alerts', key: 'id', rows: $rows);
$rows = [];
foreach ($ic->intelligence->iterTasks(dateFrom: $today->modify('-30 days'), dateTo: $today) as $t) { // status changes land
$rows[] = ['id' => $t['id'], 'call_id' => $t['call_id'], 'location_id' => $t['location_id'],
'status' => $t['status'], 'source' => $t['source'], 'due_date' => $t['due_date'] ?? null,
'created_at' => $t['created_at'], 'completed_at' => $t['completed_at'] ?? null];
}
$warehouse->upsert('tasks', key: 'id', rows: $rows);
import { createHmac } from 'node:crypto';
const KEY = process.env.NUMBER_HASH_KEY!; // your secret; the same key every night
const hashed = (n?: string | null) => {
const d = (n ?? '').replace(/\D/g, '').slice(-10);
return d ? createHmac('sha256', KEY).update(d).digest('hex') : null;
};
const start = '2026-11-15T00:00:00-06:00', end = '2026-11-16T00:00:00-06:00'; // yesterday, local
const thirtyDaysBack = '2026-10-17T00:00:00-05:00';
const calls = [];
for await (const c of ic.intelligence.iterCalls({ dateFrom: start, dateTo: end })) {
calls.push({ id: c.id, location_id: c.location_id, call_date: c.call_date, call_type: c.call_type, status: c.status,
duration: c.duration, sentiment: c.sentiment_label, tasks: c.task_count,
caller: hashed(c.caller_number), callee: hashed(c.callee_number) });
}
await warehouse.upsert('calls', { key: 'id', rows: calls });
const alerts = [];
for await (const a of ic.intelligence.iterAlerts({ dateFrom: start, dateTo: end })) {
alerts.push({ id: a.id, call_id: a.call_id, call_date: a.call_date, rules: a.keywords, sentiment: a.sentiment_label });
}
await warehouse.upsert('alerts', { key: 'id', rows: alerts });
const tasks = []; // 30 days back, so status changes land
for await (const t of ic.intelligence.iterTasks({ dateFrom: thirtyDaysBack, dateTo: end })) {
tasks.push({ id: t.id, call_id: t.call_id, location_id: t.location_id, status: t.status, source: t.source,
due_date: t.due_date, created_at: t.created_at, completed_at: t.completed_at });
}
await warehouse.upsert('tasks', { key: 'id', rows: tasks });
What you get
| Table | Columns in this recipe |
|---|---|
| calls | id, location_id, call_date, call_type, status, duration, sentiment_label, task_count, hashed caller and callee. |
| alerts | id, call_id, call_date, keywords (rule names), sentiment_label. Join to calls on call_id for the location. |
| tasks | id, call_id, location_id, status (stored: pending, in_progress, completed, cancelled), source, due_date, created_at, completed_at. |
Build it right
- Upsert on
id. A re-run, an overlapping window or a call on the stroke of midnight then writes the same row again rather than a second one. - Always send both dates. Without them calls and alerts default to the last seven days. With both, a window can be up to 366 days: backfill history a month per request.
- Page to the end.
limitis at most 100. Passnext_cursorback ascursor, URL-encoded, untilhas_moreis false; the SDK iterators do this. - Alerts are dated by their call. An alert on a late-evening call lands in that call's day.
- Once a night. For anything sooner, use the After Call webhook.
Analytics needs counts, ids, labels and hashed numbers, not names, numbers, summaries or transcripts. Hash with a keyed hash so a number can't be looked up, keep the key in your secrets manager, set a retention period on every table, and delete a customer's rows when they leave. Health information follows your agreements with your customers.
Weekly topic and sentiment trends
Every Monday: what customers called about last week, what's rising, how the calls went, and the calls behind the fastest-rising topic.
| Recipe | Details |
|---|---|
| Who and when | An owner's weekly email, or a slide in the Monday operations meeting. |
| Trigger | Weekly Once a week, for the last closed week. |
| Endpoints | GET /insights/dashboard, GET /calls, GET /insights/topics/{slug}/calls (filters) |
- Read the Insights Hub dashboard with
startandendfor last week: call totals, trending topics and topic volumes. - Count last week's calls in each
sentimentvalue withlimit=1and the total. - Drill into the top trending topic: its negative calls for the same week.
curl -sG "$IC/insights/dashboard" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "start=2026-11-09T00:00:00-06:00" \ --data-urlencode "end=2026-11-15T23:59:59-06:00" \ --data-urlencode "trending_limit=10" # one count per sentiment value: read data.summary.total_calls curl -sG "$IC/calls" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "sentiment=very_negative" \ --data-urlencode "date_from=2026-11-09T00:00:00-06:00" \ --data-urlencode "date_to=2026-11-15T23:59:59-06:00" \ --data-urlencode "limit=1" # the calls behind a topic, using a slug from trending_topics[].slug curl -sG "$IC/insights/topics/$SLUG/calls" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "date_from=2026-11-09T00:00:00-06:00" \ --data-urlencode "date_to=2026-11-15T23:59:59-06:00" \ --data-urlencode "sentiment=negative" \ --data-urlencode "limit=100"
from datetime import datetime
from zoneinfo import ZoneInfo
ct = ZoneInfo("America/Chicago")
start, end = datetime(2026, 11, 9, tzinfo=ct), datetime(2026, 11, 15, 23, 59, 59, tzinfo=ct)
board = ic.intelligence.get_insights_dashboard(start=start, end=end, trending_limit=10)
for t in board.get("trending_topics") or []:
print(f'{t["name"]}: {t["call_count"]} calls ({t["percentage_change"]:+d}% on the week before)')
BANDS = ["positive", "neutral", "below_neutral", "mildly_negative", "negative", "very_negative", "crisis", "none"]
mix = {band: ic.intelligence.search_calls(sentiment=band, date_from=start, date_to=end, limit=1).total
for band in BANDS} # one value per request; the total covers every page
print(mix)
if board.get("trending_topics"):
top = board["trending_topics"][0]
for call in ic.intelligence.iter_topic_calls(top["slug"], date_from=start, date_to=end, sentiment="negative"):
print(call["date"], call["outcome"], call.get("summary") or "")
$tz = new DateTimeZone('America/Chicago');
$start = new DateTimeImmutable('2026-11-09 00:00:00', $tz);
$end = new DateTimeImmutable('2026-11-15 23:59:59', $tz);
$board = $ic->intelligence->getInsightsDashboard(start: $start, end: $end, trendingLimit: 10);
foreach ($board['trending_topics'] ?? [] as $t) {
printf("%s: %d calls (%+d%% on the week before)\n", $t['name'], $t['call_count'], $t['percentage_change']);
}
$mix = [];
foreach (['positive', 'neutral', 'below_neutral', 'mildly_negative', 'negative', 'very_negative', 'crisis', 'none'] as $band) {
$mix[$band] = $ic->intelligence->searchCalls(sentiment: $band, dateFrom: $start, dateTo: $end, limit: 1)->total;
}
print_r($mix); // one value per request; the total covers every page
$top = $board['trending_topics'][0] ?? null;
if ($top !== null) {
foreach ($ic->intelligence->iterTopicCalls($top['slug'], dateFrom: $start, dateTo: $end, sentiment: 'negative') as $call) {
echo $call['date'], ' ', $call['outcome'], ' ', $call['summary'] ?? '', "\n";
}
}
import type { Sentiment } from '@intelligence-cloud/sdk';
const start = '2026-11-09T00:00:00-06:00', end = '2026-11-15T23:59:59-06:00';
const board = await ic.intelligence.getInsightsDashboard({ start, end, trendingLimit: 10 });
for (const t of board.trending_topics ?? []) {
console.log(`${t.name}: ${t.call_count} calls (${t.percentage_change}% on the week before)`);
}
const bands: Sentiment[] = ['positive', 'neutral', 'below_neutral', 'mildly_negative', 'negative', 'very_negative', 'crisis', 'none'];
const mix: Record<string, number> = {};
for (const band of bands) { // one value per request; the total covers every page
mix[band] = (await ic.intelligence.searchCalls({ sentiment: band, dateFrom: start, dateTo: end, limit: 1 })).summary.total_calls ?? 0;
}
console.log(mix);
const top = board.trending_topics?.[0];
if (top?.slug) {
for await (const call of ic.intelligence.iterTopicCalls(top.slug, { dateFrom: start, dateTo: end, sentiment: 'negative' })) {
console.log(call.date, call.outcome, call.summary ?? '');
}
}
What you get
| Field | Meaning |
|---|---|
stats | total_calls, answered_calls, unanswered_calls for the week. |
trending_topics[] | slug, name, call_count, previous_call_count, percentage_change and a daily trend_data series. |
topic_call_volumes[] | Every topic's slug, name and call_count. |
| Topic calls | id, date, caller_name, phone_number, summary, sentiment, sentiment_label, outcome. |
Build it right
startandendare required on the dashboard, as full timestamps, at most 366 days apart. It doesn't takedate_from.trending_limitis 1 to 10 (default 4).- Topic calls take their own filters.
sentimentthere ispositive,neutralornegative;outcomeiscompleted,missedorpending. Without dates the window is the last seven days, so send both. - The eight
sentimentvalues on/callsdon't overlap, so their totals add up to the week's calls. - Once a week is plenty. Close the window in the past so the numbers don't move after you send them.
Find calls that mention a word or phrase
Which calls last month mentioned a competitor, a recall, or “cancel”? Find them, then show the lines where it was said.
| Recipe | Details |
|---|---|
| Who and when | A sales leader checking how often a competitor comes up, or a manager looking into cancellations. |
| Trigger | On demand A person searches. |
| Endpoints | GET /calls (filters), GET /calls/{callId}/transcript |
- Search calls with the word or phrase in
searchand an explicit window. It covers names, the summary, the key points and the full transcript. - Show the matches with their date, location and headline.
- When the person opens one, read its transcript and highlight the lines that contain the word.
curl -sG "$IC/calls" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "search=cancel" \ --data-urlencode "date_from=2026-10-01T00:00:00-05:00" \ --data-urlencode "date_to=2026-10-31T23:59:59-05:00" \ --data-urlencode "limit=100" # the person opens one: its transcript, then find the lines yourself curl -s "$IC/calls/$CALL_ID/transcript" -H "Authorization: Bearer $TOKEN"
from datetime import datetime
from zoneinfo import ZoneInfo
ct = ZoneInfo("America/Chicago")
term = "cancel"
matches = list(ic.intelligence.iter_calls(text=term, date_from=datetime(2026, 10, 1, tzinfo=ct),
date_to=datetime(2026, 10, 31, 23, 59, 59, tzinfo=ct)))
print(len(matches), "calls")
for c in matches:
print(c["call_date"][:10], c["location_id"], c.get("top_highlight") or c.get("summary") or "")
if matches: # the call the person opens
for line in ic.intelligence.get_transcript(matches[0]["id"]):
if term.lower() in line["text"].lower():
print(f'{line["time"]:7.1f}s {line.get("name") or line["speaker"]}: {line["text"]}')
$tz = new DateTimeZone('America/Chicago');
$term = 'cancel';
$matches = iterator_to_array($ic->intelligence->iterCalls(text: $term,
dateFrom: new DateTimeImmutable('2026-10-01 00:00:00', $tz),
dateTo: new DateTimeImmutable('2026-10-31 23:59:59', $tz)), false);
echo count($matches), " calls\n";
foreach ($matches as $c) {
echo substr($c['call_date'], 0, 10), ' ', $c['location_id'], ' ', $c['top_highlight'] ?? $c['summary'] ?? '', "\n";
}
if ($matches) { // the call the person opens
foreach ($ic->intelligence->getTranscript($matches[0]['id']) as $line) {
if (stripos($line['text'], $term) !== false) {
printf("%7.1fs %s: %s\n", $line['time'], ($line['name'] ?? '') ?: $line['speaker'], $line['text']);
}
}
}
import type { CallListItem } from '@intelligence-cloud/sdk';
const term = 'cancel';
const matches: CallListItem[] = [];
for await (const c of ic.intelligence.iterCalls({ text: term, dateFrom: '2026-10-01T00:00:00-05:00', dateTo: '2026-10-31T23:59:59-05:00' })) {
matches.push(c);
}
console.log(matches.length, 'calls');
for (const c of matches) console.log(c.call_date?.slice(0, 10), c.location_id, c.top_highlight ?? c.summary ?? '');
const opened = matches[0]?.id; // the call the person opens
if (opened) {
for (const line of await ic.intelligence.getTranscript(opened)) {
if (line.text?.toLowerCase().includes(term)) console.log(`${(line.time ?? 0).toFixed(1)}s ${line.name || line.speaker}: ${line.text}`);
}
}
What you get
| Field | Meaning |
|---|---|
summary.total_calls (response) | How many calls match, across all pages. |
id, call_date, location_id | Each matching call. |
top_highlight, summary | Its headline and summary. |
| Transcript lines | time, speaker, name, text: find the mention yourself. |
Build it right
- Search whole words. Use
cancel, a competitor's name, or a short phrase: a phrase matches calls that contain its words. At least two characters. - One search term per request. For several competitors, run one search each and count the totals.
- Add filters to narrow it:
location_id,sentiment,status. All filters combine with AND. - Topic drill-downs search too.
searchon/insights/topics/{slug}/callsfinds the word inside one topic (recipe 11). - Show, don't export. Display the lines to the person who searched; for a recurring count, store the totals, not the text.
Share a recording for coaching or QA
Put a play button in your coaching or QA tool. Each press fetches a fresh, short-lived link to the call's audio; nothing durable ever holds the link.
| Recipe | Details |
|---|---|
| Who and when | A coach reviewing a call with a new hire, or a QA reviewer scoring a sample. |
| Trigger | On demand A reviewer presses play. |
| Endpoints | GET /calls/{callId} (recording link) |
- Your tool stores the call id, never the recording link.
- The play button calls your own endpoint, which checks that the reviewer may hear this call.
- The endpoint reads a fresh link and its expiry, and redirects the reviewer's player to it.
curl -s "$IC/calls/$CALL_ID" -H "Authorization: Bearer $TOKEN" # data.vcon.recording_url the signed link, or null when the call has no recording # data.vcon.recording_url_expires_at 120 minutes after issue # data.vcon.recording_mime_type audio/wav # hand the link straight to the player: no Authorization header; Range requests work
from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import RedirectResponse
app = FastAPI()
@app.get("/coaching/calls/{call_id}/play") # behind your own sign-in
def play(call_id: str, request: Request):
if not reviewer_may_hear(request, call_id): # your own access check
raise HTTPException(status_code=403)
link = ic.intelligence.get_recording_url(call_id) # a fresh link on every press of play
if link is None:
raise HTTPException(status_code=404)
return RedirectResponse(link.url, status_code=303,
headers={"Cache-Control": "no-store", "Referrer-Policy": "no-referrer"})
<?php
// public/coaching-play.php?call=<call id>, behind your own sign-in
require __DIR__ . '/../vendor/autoload.php';
use IntelligenceCloud\Client;
$callId = strtolower((string) ($_GET['call'] ?? ''));
if (!preg_match('/^[0-9a-f-]{36}$/', $callId)) { http_response_code(404); exit; }
if (!reviewerMayHear($callId)) { http_response_code(403); exit; } // your own access check
$ic = new Client(email: getenv('IC_DATA_EMAIL'), password: getenv('IC_DATA_PASSWORD'));
$link = $ic->intelligence->getRecordingUrl($callId); // a fresh link on every press of play
if ($link === null) { http_response_code(404); exit; }
header('Cache-Control: no-store');
header('Referrer-Policy: no-referrer');
header('Location: ' . $link->url, true, 303);
// app/coaching/calls/[callId]/play/route.ts, behind your own sign-in
export async function GET(req: Request, { params }: { params: Promise<{ callId: string }> }) {
const { callId } = await params;
if (!(await reviewerMayHear(req, callId))) return new Response(null, { status: 403 }); // your own access check
const { url } = await ic.intelligence.getRecordingUrl(callId); // a fresh link on every press of play
if (!url) return new Response(null, { status: 404 });
return new Response(null, {
status: 303,
headers: { Location: url, 'Cache-Control': 'no-store', 'Referrer-Policy': 'no-referrer' },
});
}
What you get
| Field | Meaning |
|---|---|
vcon.recording_url | A signed HTTPS link to the call's audio, or null when the call has no recording. The SDKs return it as url. |
vcon.recording_url_expires_at | When the link stops working: 120 minutes after issue. The SDKs return it as expires_at / expiresAt. |
vcon.recording_mime_type | audio/wav. |
Build it right
- Fetch a fresh link on every play. Store the call id; read the link when someone presses play.
- Redirect, don't proxy or copy. The reviewer's player streams straight from the link, with
Rangerequests for seeking. Send noAuthorizationheader to it. - Check access in your tool. Anyone who reaches your play endpoint hears the call, so put it behind your own sign-in and your own rule for who may review which calls.
- Use the call id everywhere else. In a coaching note, a scorecard or a message to a colleague, share the call id or the link to the call in Intelligence Cloud.
The recording link works for anyone who holds it until it expires. Never store it, log it, forward it, or put it in a ticket, chat message, email or scorecard, and never use it after recording_url_expires_at. Telling callers they are recorded, and any consent the law requires where you operate, is yours to handle; health information in a recording follows your agreements with your customers.
Ideas you can build from these
Customer health in your CRM
Each night, roll each contact's last 90 days of call sentiment, alerts and open follow-ups into one score on the CRM record.
A Monday coaching queue
Pick last week's Upset Customer calls per team and hand each coach the call ids, with a play button that fetches a fresh link.
Competitor watch
Once a week, count the calls that name each competitor and chart the totals next to the topics that are rising.
A follow-up board on the shop floor
Open follow-ups per advisor on a screen in the service lane, updated by the After Call webhook rather than a timer.
Voicemail response time
From the nightly export, measure how long each location takes to call back after a voicemail, and put it in the weekly operations pack.
API and Integration Guide
The rules, credentials, filters, webhooks and SDKs behind every recipe.
API reference
Every operation with its parameters, responses and examples.
Reseller Admin Guide
How your provider sets up locations, users, alerts and webhooks.
| You need | Go to |
|---|---|
| An integration user, or a webhook address saved | Your phone provider |
| Help with an integration | Your phone provider, with the request_id, the endpoint and the time. Never send tokens, passwords or conversation content. |
| Report a suspected exposure of conversation data, a credential, a webhook address or a recording link | security@tresic.cloud, straight away, copying your provider. Rotate the affected credentials. |