Build Intelligence Cloud into your own systems
Provision Base Intelligence Seat customers from your portal or billing system, and bring every conversation, alert and insight into the tools your customers already use. The rules, the flows call by call, the webhooks, and SDKs for Python, PHP and TypeScript.
What you can do with the API
One REST API, two halves. Admin credentials configure customers and users. Frontline credentials read the conversation intelligence those customers produce.
Looking for worked examples? Integration Recipes has thirteen ready-to-run integrations, from a call's transcript to a nightly warehouse export.
Configure customers and users
Create the company, single sign-on, products, locations, connectors, user groups, First Alert rules and Insights Hub setup. Add, change and remove frontline users and managers, and keep every manager's lines in step.
Read conversations, alerts, tasks and insights
Search conversations by phone number, text and date. Read alerts by name, number and date. Pull follow-up tasks and Insights Hub topics, and receive an event after every call.
| Half | Credential | Endpoints |
|---|---|---|
| Customer lifecycle | A reseller admin login | Companies, single sign-on, products, locations, user groups, connectors, First Alert, Insights Hub, users, After Call settings, webhook configuration |
| Conversation intelligence | A named frontline integration user in the customer's company | /calls, /alerts, /tasks, /insights, /locations, /me. Your systems also receive the After Call and First Alert webhooks, whose addresses are set with admin credentials. |
Everything the lifecycle API does, except your SMTP relay settings, can also be done in the Admin UI or with the Intelligence Cloud admin skill for Claude Code (partner beta). Your SMTP relay is set through the API or by your Tresic contact. They change the same configuration, so mix them freely. See Three ways to manage configuration in the Reseller Admin Guide.
Basic API rules
Conversations carry your customers' customers: names, numbers and what they said. These rules apply to every integration and to everyone who touches the data it reads.
These rules are part of the API and SDK Terms, which apply to every integration.
Separation of duties
| Level | Rule |
|---|---|
| Must | Protect the admin integration login as your most sensitive credential. Admin logins return no conversation data: a reseller admin login gets empty lists from /calls, /alerts and /tasks, and 404 from call detail, so check role from GET /me when your job starts. But an admin login can create users and redirect webhooks, so it can reach every customer's data. Give it a random password of 32 or more characters, kept in a secrets manager and used only from your provisioning servers. Rotate it every 90 days and whenever someone with access leaves, and review new users and webhook changes every week. Tresic logs the changes each user makes (and, once they are released, each API key). |
| Must | Data access needs a named frontline integration user in the customer's company, with the locations, products, lines and groups that decide what it sees (chapter 03). |
| Must | One integration user per purpose. A CRM sync, a BI export and a portal each get their own user, scoped to what that purpose needs. Each can then be switched off on its own and its access is easy to read. |
| Must | Your portal enforces who sees what. If people read calls through your own portal, the portal decides who sees which location and line, logs who viewed what, and uses a separate integration user for each customer. |
| Never | Share credentials. Not between people, not between integrations, not between environments. A person who needs to read calls gets their own user; a support engineer uses their own reseller admin login. |
Webhooks, not polling
| Level | Rule |
|---|---|
| Never | Poll for new data. Use the After Call webhook and the First Alert webhook for anything that must happen as calls and alerts arrive. Intelligence Cloud pushes each event to you the moment it is ready. |
| Must | Read the API on demand. Call it when a person asks for something, or when a webhook tells you to fetch the details of a call or an alert. |
| Must | Schedule jobs at most once a day. Exports, digests and the nightly catch-up run no more than once a day, each over a bounded date window (date_from and date_to). |
| Should | Check a connector until it settles, then stop. After you create, deactivate or reactivate one, read its status every 10 seconds for up to 10 minutes. The SDKs do this for you. |
Conversation data protection
These are requirements for anyone who accesses conversation data through the API, whether your own staff, your contractors or a system you build for a customer.
Data this API returns
| Data | Where | Treat as |
|---|---|---|
| Caller and callee names and numbers | /calls, /alerts, call detail, After Call webhook | Personal data |
| Summaries, key points and transcripts | Call detail, /calls/{callId}/transcript, /alerts, After Call webhook (summary) | Personal data, and health information when a caller mentions it |
| Recording audio | The signed recording link on call detail | Personal data, voice |
| Tasks, with the assignee's name and email | /tasks, call detail | Personal data |
| Sentiment and topics | /calls, /alerts, call detail, /insights | Personal data when tied to a call |
The After Call webhook carries every call at the location, whatever any user's lines say.
| Level | Requirement | What it means |
|---|---|---|
| Must | Security policies and access control | Written security policies cover every system that stores or processes conversation data. Access is granted per person, on least privilege, reviewed regularly and removed the day someone leaves. Your own sign-ins to those systems use a second factor. |
| Must | Encryption in transit and at rest | TLS 1.2 or later on every hop, including your webhook receiver and your internal services. Databases, files, backups and queues that hold conversation data are encrypted at rest. |
| Must | Anonymise unless it is unavoidable | Remove or pseudonymise names, phone numbers and free text before data leaves the system that needs it. Reports, dashboards, analytics and test data use counts, ids and hashed numbers. Keep identity only where the use depends on it, such as a call-back list. |
| Must | Keep only what you need, then destroy it | Read the fields the purpose needs and no more. Set a retention period for each store, delete data when the purpose is met, and delete everything for a customer when they leave. Re-read from the API rather than keeping long-lived copies. |
| Never | Data in logs | Never write summaries, transcripts, names, phone numbers, request or response bodies, tokens, passwords or webhook URLs to logs, error trackers, analytics or support tickets. Log ids, HTTP status and request_id instead. |
| Must | Treat secrets as secrets | Passwords, access and refresh tokens, invitation links, NetSapiens API keys and webhook URLs live in a secrets manager and travel only by secure transfer. A user-create response can carry a one-time sign-in link: never log or store it. |
| Must | Report incidents | Report any suspected exposure of conversation data or credentials to security@tresic.cloud within 24 hours of discovering it, earlier if you can, copying your Tresic contact, with what was exposed, when and to whom. Rotate the affected credentials straight away. |
| Must | Approved systems only | Before conversation data leaves Intelligence Cloud for another system (CRM, helpdesk, chat, analytics or a data warehouse), the customer has approved that system, and access there is limited to people who could see the same calls in Intelligence Cloud. The After Call webhook delivers every call at the location: send it only to systems the customer approved, and limit who can see it there. |
| Must | Requests from callers | When someone asks the customer to see, correct or delete their data, the customer answers it. Update or delete your copies, and send requests about data held in Intelligence Cloud to your provider or support@tresic.cloud. |
| Must | Recording consent is the customer's | The customer is responsible for telling callers that calls are recorded, transcribed and analysed by its service providers, and for any consent the law requires where the caller and the business are. Some US states and most other countries require every party's consent. Your integration uses data only for the purposes the customer has agreed with you. |
| Must | Use data for its purpose only | Data read for one customer is used for that customer alone, and never combined across customers or used to train models. |
| Must | Chat and paging get ids, not content | To chat and paging tools, send ids and a link behind sign-in, not summaries, names or numbers. Post only to private channels. |
| Must | Call content is untrusted text | Summaries and transcripts come from what callers say. Escape them, don't render markdown or links from them, and strip @-mentions before you post them to chat. |
| Must | A person decides | Summaries, sentiment, topics, tasks and alerts are produced automatically from each call. Use them to find and route work; a person makes any decision with medical, legal, financial or employment consequences. |
Healthcare customers integrate the same way as everyone else, with a business associate agreement (BAA) at every link that carries health information:
- Tresic signs a BAA with every partner that processes health information with Tresic.
- You need a BAA with the healthcare customer, and with every downstream system that receives health information from the integration: CRM, helpdesk, chat, data warehouse.
- Send each system the minimum it needs. Treat every call from a healthcare customer as containing health information.
- Set Call details in emails to Off for healthcare customers.
- Retention is set per customer under the customer's agreement. Ask your provider.
- Access logging: Tresic logs every read of conversation data, in the app and through the API, and every configuration change, by user (and, once they are released, by API key). The logs are kept for the customer's retention period, and a customer's access log is available on request from security@tresic.cloud.
- When a customer leaves, its data is handled as that agreement sets out.
- Requests from callers to see or delete their data go to your provider or support@tresic.cloud.
- Per-company controls: password policy, session timeout, sign-in IP ranges and call details in emails.
- Security documentation, including certifications, the penetration test summary, data location, subprocessors and our BAA, is available on request from security@tresic.cloud.
- Incidents: partners and customers report a suspected incident to security@tresic.cloud within 24 hours of discovering it. Tresic notifies its partner as their agreement sets out, and the partner notifies its customer.
Credentials and authentication
Today an integration signs in with the username and password of a dedicated integration user, with MFA switched off for that user's company. API keys are being released in December 2026.
Your provider sets up your access. Send them this list:
- A frontline integration user named for its purpose, for example
crm-sync@example.com, with sign-in methodpassword. - MFA off for your company.
- The locations it covers, with all lines at those locations mapped to it.
- For alerts and insights: First Alert Co-Pilot and Insights Hub, membership of every group the alert rules notify and of Insights Hub Access, with alert email off.
- The location ids.
- The After Call webhook set to your address, or your company admin login so you can set and test it yourself.
A company admin login (customer_admin) can set, read and test the After Call webhook and manage company branding. The endpoint index marks each operation it can use.
The integration users
| For | Who | Set up |
|---|---|---|
| Customer lifecycle | A reseller admin login used only by your integration, for example provisioning@example.com | Ask your Tresic contact for a dedicated reseller admin integration login with MFA off. Keep it separate from the logins your people use. |
| Conversation data | A frontline user in the customer's company, for example crm-sync@example.com, named for its purpose | Create it like any user (chapter 04), then turn MFA off for its company with PATCH /companies/{companyId} {"mfa_enforced": false} and read it back. Create it with auth_method: "password", even in a company that uses single sign-on. Accept the invitation once to set the password. |
What a frontline integration user sees
| Data | Visible when |
|---|---|
/calls, /tasks | The caller or callee is one of the user's lines. Map all lines at the locations it covers for a full feed, the same way as a manager. |
/alerts, Base Intelligence Seat | The user has First Alert Co-Pilot and is in Manager Alerts. |
/alerts, more locations and rules | The user has First Alert Co-Pilot and is in a group every rule notifies. Create one API Integration group at each location, with the integration user as its only member, and add it to every rule's group_ids. Check it again after any rule change. |
/insights | The user has Insights Hub and is in the location's Insights Hub Access group. |
/calls/{callId} | The call is in the user's call list, or it is linked to an alert the user can see. |
An integration user set up to read alerts and insights has a manager's products and groups. Switch its alert email off (PUT …/first-alert/email-preferences {"masterEnabled": false, "alerts": []}) so it is not emailed every alert, and tag it department: "integration" (PATCH /companies/{companyId}/users/{userId}), which keeps it out of seat counts and manager lists. The SDK's add_integration_user does all of this.
Sign in, renew, sign out
curl -s https://app.intelligence.cloud/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"crm-sync@example.com","password":"'"$IC_PASSWORD"'"}'
# 200
{
"access_token": "eyJ…",
"refresh_token": "rt_…",
"token_type": "Bearer",
"expires_in": 899,
"user": { "id": "…", "role": "frontline_user", "scopes": ["calls:read", "alerts:read", "…"] }
}
import os from intelligence_cloud import Client ic = Client(email="crm-sync@example.com", password=os.environ["IC_PASSWORD"]) ic.intelligence.require_frontline() # signs in on first call; raises FrontlineRequiredError for an admin login
use IntelligenceCloud\Client;
$ic = new Client(email: 'crm-sync@example.com', password: getenv('IC_PASSWORD'));
$ic->intelligence->requireFrontline(); // signs in on first call; 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(); // signs in on first call; throws FrontlineRequiredError for an admin login
| Step | Call | Rule |
|---|---|---|
| Sign in | POST /auth/login | Returns an access token (about 15 minutes) and a refresh token. Send Authorization: Bearer <access_token> on every other call. A body of {"status": "mfa_required"} means MFA is still on for the user's company: fix the configuration, don't prompt for a code. |
| Renew | POST /auth/refresh | Refresh tokens rotate. Each renewal returns a new refresh token and spends the old one. Store the new one before you use it, never send a refresh token twice, and never share one between processes: replaying a spent token ends the session everywhere. Renew before expires_in runs out or after a 401. On refresh_token_invalid, refresh_token_expired, session_revoked or renewal_replayed, sign in again. session_revoked follows any sign-out or password reset for that user. |
| Sign out | POST /auth/logout | Ends all of that user's sessions, including every other job and browser using it. Most integrations never call it. |
| Rate limits | Login 5 per minute per IP Refresh 20 per minute per IP | Sign in once per job and reuse the token. On 429, back off with jitter, honouring Retry-After if it is present. |
Keep an integration user running
| Topic | Rule |
|---|---|
| Sign-in method | password, even in a company that uses single sign-on. |
| Mailbox | A monitored mailbox owned by the customer's security team, not a person's and not an open distribution list. Password-reset links go there. |
| Password policy | The integration user's password follows the company's password policy, which the reseller sets. Read it in the Admin UI security settings or with GET /companies/{companyId}/security-settings, including password_expiry_days. |
| Rotation | Before the password expires, and at least every 90 days, and whenever someone who knows the password leaves. Reset it in the app, then update your secrets manager. |
| Password expiry | A sign-in that returns password_expired: true means the integration must stop and alert an operator. A person sets a new password for the integration user in the app; then update your secrets manager and start the integration again. |
| Retire it | Take it out of its groups, clear its lines, deactivate it and delete the stored secret. With the SDK, use remove_user(customer, user_id): an integration user's lines are never taken off anyone else. |
Running on several workers
Refresh tokens rotate, so every process that signs in as one integration user must share its tokens. Use one shared, locked token store per integration user, or give each worker its own integration user. Never create a client per request: each one signs in again and runs into the login limit.
- Change the user's password.
- Sign in with the new password and call POST /auth/logout. That ends every session for the user. Then sign in again for your own jobs.
- Save new path tokens for every webhook the login could read or change.
- Review users created and webhook changes since the leak.
- Report it to security@tresic.cloud.
API keys are being released in December 2026 and replace the password sign-in for server-to-server calls.
Requests and responses
| Topic | Rule |
|---|---|
| Base URL | https://app.intelligence.cloud/api/v1. Always call the API there, whatever domain your users sign in on. HTTPS only, TLS 1.2 or later, JSON in UTF-8. |
| Headers | Authorization: Bearer … on every call except login and refresh. A descriptive User-Agent such as northgate-crm-sync/1.0. Optionally X-Request-ID, echoed back as error.request_id. |
| Envelopes |
· One record: {"data": {"type": …, "attributes": {…}}}.· /me: {"data": {…}}, with the fields directly under data.· A list: {"data": [ … ], "pagination": {"has_more", "next_cursor"}}.· Calls and alerts: {"data": {"summary": {…}, "calls": [ … ]}, "meta": {"has_more", "next_cursor", …}} ("alerts" for alerts).· The company list: has_more and next_cursor at the top level.· A 401 rejected before it reaches the service: {"statusCode", "message"}.The reference shows each shape. |
| Paging | Cursor paging. Send limit (up to 100), then pass next_cursor back as cursor until has_more is false. URL-encode the cursor. Results are newest first. |
| Dates | Full RFC 3339 timestamps, for example 2026-11-01T00:00:00Z or 2026-11-01T00:00:00-06:00. A date alone returns 400. Calls and alerts: date_from after date_to, or a window over 366 days with both sent, returns 422. Insights Hub dashboard: start to end at most 366 days. Each endpoint's filter table gives its own rules. In responses, the After Call event's call.call_date is a date; an alert's call_date is a full timestamp. |
| Filters | Use only the filters documented for each endpoint. The server ignores any parameter it doesn't know and returns unfiltered data with a 200, so a typo looks like success. The SDKs reject unknown filters before sending. Send one value per parameter; where a list is allowed, use the comma form. |
| Phone numbers | Usually E.164 (+15555550142); staff lines are extensions (2101); some records carry ten digits without +1. Normalise before you join records. |
| Ids | UUID strings. Don't depend on their version or order. |
| URL length | Keep query strings under 2,000 characters: about 50 location ids per request. |
| New fields | Fields, endpoints and enum values are added to v1 without notice. Ignore fields you don't know. See Changes and versions. |
| Load | On every endpoint, back off on 429 and 503 with jitter, honouring Retry-After when it is present. Read one page at a time. See Rate limits. |
Errors
{ "error": { "code": "VALIDATION_ERROR", "message": "Invalid sentiment. Must be one of: …", "request_id": "7b1e2c3d-…" } }
| Status | Meaning | What to do |
|---|---|---|
| 400 | Malformed request: bad UUID, bad cursor, a date without a time, a limit out of range, a missing field | Fix the request. Don't retry unchanged. |
| 401 | Token missing, invalid or expired | Renew, or sign in again, then retry once. |
| 403 | This role can't do this | Use the other credential (endpoint index). |
| 404 | Not found, or outside what this login may see | Treat it as absent. Out-of-scope records return 404, never 403. A 404 whose body isn't JSON is a refusal at the edge, usually an over-long URL, not "not found": shorten the request. |
| 409 | Conflict: a duplicate name or email, already active or inactive, an extension monitored at another location | Read the current state, then decide. |
| 422 | Valid shape, invalid value: an enum, date order, range or unknown reference | Fix the value. |
| 429 | Rate limited | Back off with jitter; honour Retry-After if it is present. |
| 5xx | Temporary | Retry GET, PUT, PATCH, DELETE and user create (with the same Idempotency-Key) with backoff, up to three times. For any other POST, look the object up first: the create may have happened. |
Branch on the HTTP status, then on error.code. /tasks errors carry error.type instead. A 401 rejected before it reaches the service is a flat {"statusCode", "message"}. The SDKs normalise all three into one error hierarchy. Show your own messages to end users.
Rate limits
| Category | Limit | Build for it |
|---|---|---|
| Sign-in | 5 per minute per IP | Sign in once per job and reuse the token. |
| Token refresh | 20 per minute per IP | Renew before expires_in runs out, from one shared token store. |
| Data endpoints | 5 requests a second per user, bursts up to 20, at most 4 at a time. 50,000 requests a day per company. | Read one page at a time; never poll for new data. On 429, wait for Retry-After, then retry. |
| Search-heavy look-ups | 1 request a second per user, within the data-endpoint limits | Phone-number and text searches: send date_from and location_id, and cache the result. |
Tresic may throttle or suspend an integration to protect the service, as the API and SDK Terms set out.
Changes and versions
| Topic | Policy |
|---|---|
| v1 is stable | We add fields, endpoints and enum values without notice: ignore unknown fields and treat unknown enum values as "other". |
| 90 days' notice | We give at least 90 days' notice before removing or changing documented behaviour, except where a security, legal or abuse reason requires a faster change. |
| How notice is given | By email to your partner contacts, and in the changelog below. |
| Undocumented behaviour | Handling of unknown parameters, default windows and search ranking may change. Send only documented parameters and always send both dates. |
| SDKs | The SDKs stay at 0.x until API keys ship. Version 1.0 is then published to the package registries with semantic versioning, and the previous minor version is supported for 12 months. |
Changelog
| Date | Change |
|---|---|
| 2026-11 | First publication of this guide, the API reference, the Integration Recipes and SDK 0.1.0. |
Customer lifecycle: Base Intelligence Seat
When a customer buys the Base Intelligence Seat through your portal, your system builds the whole account through the API: one company, one location, two alerts, Insights Hub, and a seat for every person.
| The Seat includes | At one location |
|---|---|
| After Call Co-Pilot | The full product, for every seat. |
| First Alert Co-Pilot | Two alerts, Upset Customer and Customer Threat, routed to managers. |
| Insights Hub | The basic dashboard and Instant Insights, for managers. |
| API access | Everything in this guide. |
| User type | Gets |
|---|---|
| Frontline user (end user) | After Call Co-Pilot on their own extension. Alert email off. |
| Manager | After Call Co-Pilot on every end user's extension at the location, First Alert Co-Pilot, Insights Hub, and both groups: Manager Alerts and Insights Hub Access. A manager's own line is not captured. |
The flow
Numbers match the tables below. The SDK runs steps 1–9 as provision_seat_customer, U1–U2 as add_frontline_user and U3–U4 as add_manager (which switches the rules on through activate_seat_alerts), and keeps numbers in step with sync_numbers. These are on client.workflows. The SDK names below are the Python forms; PHP and TypeScript use the same names in camelCase ($admin->workflows->provisionSeatCustomer(), admin.workflows.provisionSeatCustomer()). The spec fields differ a little by language: see Seat spec fields.
Configure the customer
| # | What happens | Endpoints | SDK |
|---|---|---|---|
| 1 | Create the customer. Company name, primary contact name, email and phone, and enabled_products with all three products. The primary contact is invited as the company admin automatically; the email must be unique on the platform. If the customer's frontline integration user will live in this company, turn MFA off and read it back. | POST /resellers/{resellerId}/companies PATCH /companies/{companyId} GET /companies/{companyId} | provision_seat_customer (mfa_off=True): turns MFA off and reads it back |
| 2 | Configure SSO, if the customer wants staff to sign in with their company login. Claim the email domain and send the TXT record to the customer's IT; verify once it is published; connect their OpenID Connect provider and give their IT the callback address and steps it returns. Connecting a provider takes an acknowledgement; sending it confirms that anyone who can sign in at that login system can sign in to Intelligence Cloud as a member of this company, and that the login system, not Intelligence Cloud, makes the checks that decide who that is, including any second factor. Test sign-in and invitations on your own sign-in domain before you add users. Users are then created with auth_method: "sso". | POST …/domains POST …/domains/{domainId}/verifications POST …/identity-provider POST …/identity-provider/test | provision_seat_customer (sso_domain): claims the domain and returns the TXT record. Verify and connect the provider with client.sso |
| 3 | Enable After Call, First Alert and Insights Hub. A product is on at three levels and all three must be on: the company (step 1), the location (step 4) and each user (U1 and U3). The company list is a full replacement. | GET /companies/{companyId}/products PATCH /companies/{companyId} | provision_seat_customer |
| 4 | Create the single location, for example Northgate Dental - Main, with its address, an industry from the verticals list and the same three products. Leave the support contact fields out. A new location starts with no alert rules. | GET /verticals POST /companies/{companyId}/locations | provision_seat_customer |
| 5 | Connect the phone system. Read the customer's extensions from NetSapiens with your own key. Dry-run the connector (reachability and authentication), create it, then check its status every 10 seconds until it is active (allow up to 10 minutes): calls flow from then on. error carries a state_reason; invalid_permissions means the key is read-only. The key must be read/write with the settings in the NetSapiens key table. | POST /locations/{locationId}/connectors/test POST /locations/{locationId}/connectors GET …/connectors/{connectorId} | provision_seat_customer (connector): checks every 10 seconds, for up to 10 minutes, until it settles. An error is recorded on the result (connector_status, connector_state_reason), not raised |
| 6 | Create the Manager Alerts group. The managers who act on the Seat's two alerts. | POST /locations/{locationId}/user-groups | provision_seat_customer |
| 7 | Create the Insights Hub Access group. Members with the Insights Hub product open the location's Insights Hub. | POST /locations/{locationId}/user-groups | provision_seat_customer |
| 8 | Configure First Alert. Create the two rules switched off, both routed to Manager Alerts: · Upset Customer: sentiment below −40, priority high. · Customer Threat: the customer-threat phrases and sentiment below −20, priority critical. Save the lines First Alert watches (all lines at the location). The rules stay off until the first manager is in place (U4). | POST /locations/{locationId}/first-alert/rules PUT /locations/{locationId}/first-alert/config PATCH …/first-alert/rules/{ruleId} | provision_seat_customer (threat_phrases): creates both rules switched off. A re-run never switches a rule on or off |
| 9 | Configure Insights Hub. Give the Insights Hub Access group access, add the location's lines, and switch on monitor all numbers so managers see every call at the location. | POST /locations/{locationId}/insights-hub/setup PATCH /locations/{locationId}/insights-hub/config | provision_seat_customer |
provision_seat_customer is safe to re-run. Store the returned company_id and pass it on every re-run: without it, a company with the same name is used only when its primary contact email matches, and any other same-named company raises ConflictError before anything is written. Locations, groups and rules are found by name, users by email and the connector by its domain; a connector in error is updated with the key you pass and restarted.
The two rules
{
"name": "Upset Customer",
"priority": "high",
"match_logic": "any",
"enabled": false,
"triggers": [
{ "trigger_type": "sentiment", "config": { "operator": "lt", "threshold": -40 } }
],
"group_ids": ["<Manager Alerts group id>"]
}
{
"name": "Customer Threat",
"priority": "critical",
"match_logic": "all",
"enabled": false,
"triggers": [
{ "trigger_type": "sentiment", "config": { "operator": "lt", "threshold": -20 } },
{ "trigger_type": "keyword_match",
"config": { "match_logic": "any",
"keywords": ["<customer-threat phrases from your Tresic contact>"] } }
],
"group_ids": ["<Manager Alerts group id>"]
}
Tresic provides and maintains the customer-threat phrase list. Ask your Tresic contact for it and pass it to provision_seat_customer as threat_phrases (PHP threatPhrases:, TypeScript threatPhrases); never commit it to source control or share it outside your team.
The connector
{
"name": "Northgate Dental - NetSapiens",
"type": "netsapiens",
"config": {
"api_url": "https://pbx.example.com/ns-api/v2",
"domain": "northgatedental.example",
"api_key": "<read/write key, from your secrets manager>"
}
}
# 202 Accepted
{ "data": { "type": "connector", "attributes": { "id": "…", "status": "connecting", … } } }
# check GET /locations/{locationId}/connectors/{connectorId} every 10 s (up to 10 min) until
# "status": "active" calls flow
# "status": "error", "state_reason": "invalid_permissions" key is read-only: fix it, then reactivate
Configure users
| # | What happens | Endpoints | SDK |
|---|---|---|---|
| U1 | Add a frontline user: After Call on their own extension only. Create the user as frontline_user on the location with an Idempotency-Key and send_invitation: false, switch on After Call Co-Pilot, switch alert email off, set the end-of-day recap if wanted, and map their own extension. | POST /companies/{companyId}/users POST …/users/{userId}/products/after-call-copilot/enable PUT …/first-alert/email-preferences PATCH …/after-call-settings PUT …/users/{userId}/connector-mappings | add_frontline_user(customer, user, extension) |
| U2 | Add their number to First Alert, Insights Hub and every manager. Read the First Alert lines, add the extension and write the full list back with the webhook address; do the same for the Insights Hub lines; add it to every manager's lines. | GET + PUT /locations/{locationId}/first-alert/config PATCH /locations/{locationId}/insights-hub/setup PUT …/users/{managerId}/connector-mappings | Part of add_frontline_user |
| U3 | Add a manager: After Call on every end user's extension, First Alert, Insights Hub, both groups. Create the user on the location with send_invitation: false, switch on all three products, put them in Manager Alerts and Insights Hub Access, switch alert email on for both rules, and map every end user's line at the location. Never map or capture the manager's own line. | POST /companies/{companyId}/users POST …/products/{productKey}/enable ×3 PUT …/users/{userId}/group-membership PUT …/first-alert/email-preferences PUT …/users/{userId}/connector-mappings | add_manager(customer, user, *, activate_alerts=True) |
| U4 | Switch the rules on, then invite. Once the first manager is set up and mapped, switch both rules on. Then email each user's invitation, last, once their lines are mapped. Invitations last seven days and can be sent again. | PATCH …/first-alert/rules/{ruleId} {"enabled": true}POST …/users/{userId}/resend-invitation | The SDK creates each user without an invitation, maps their lines, and emails the invitation last (send_invitation=False holds it back). Rules are created switched off; add_manager switches both on once the first manager is set up, or call activate_seat_alerts(customer) |
{
"email": "jordan.reyes@example.com",
"first_name": "Jordan",
"last_name": "Reyes",
"role": "frontline_user",
"location_ids": ["<location id>"],
"send_invitation": false,
"auth_method": "password"
}
PUT /companies/{companyId}/users/{userId}/connector-mappings
{ "mappings": [ { "connector_id": "<connector id>", "monitored_numbers": ["2102"] } ] }
Managers use the same mapping call with every end user's line at the location, never their own, for example ["2101", "2102", "2103", "2104"]. Set group membership before per-rule alert email: a manager's email preferences list only the rules their groups receive.
Future frontline changes
Every number a frontline user holds also appears in each manager's lines, in First Alert and in Insights Hub. When it changes, all four change together.
| Change | Calls, in order | SDK |
|---|---|---|
| New extension | 1. Remove the old number from the user's lines. 2. Add the new number to the user's lines. 3. Re-sync every manager's lines, the First Alert lines (resend the webhook address) and the Insights Hub lines, each as a full list. Calls already captured stay with the old mapping. | change_user_extension(customer, user_id, old, new) |
| New frontline user | U1 and U2 above. | add_frontline_user |
| Someone leaves | Take the user out of every group, clear their lines, remove their extension from every manager, First Alert and Insights Hub, then deactivate them. Deactivation alone keeps groups and lines. Products can stay: deactivated users drop out of the dashboard counts. | remove_user(customer, user_id): clears groups, lines and the extension everywhere first, then deactivates |
| Check everything matches | Recompute the union of frontline extensions and push it to every manager, First Alert and Insights Hub. | sync_numbers(customer); dry_run=True returns the diff |
| Customer leaves | 1. Pause every After Call webhook ("enabled": false) and clear each First Alert webhook_url.2. Deactivate each connector; this ends the call-record subscription. 3. Deactivate the integration users. 4. Deactivate the company. 5. Ask your Tresic contact about the customer's data at Tresic, and delete your own copies. Revoke the customer's NetSapiens key once the connectors are inactive. | workflows.offboard_customer(customer) runs steps 1–4 in order. |
Management dashboard
One paged call per location gives the whole seat view: each row carries the user's products and group names.
{
"data": [
{ "type": "location_user", "attributes": {
"email": "avery.lane@example.com", "role": "frontline_user", "status": "active",
"enabled_products": ["after-call-copilot", "first-alert-copilot", "insights-hub"],
"groups": ["Manager Alerts", "Insights Hub Access"], … } },
{ "type": "location_user", "attributes": {
"email": "jordan.reyes@example.com", "role": "frontline_user", "status": "invited",
"enabled_products": ["after-call-copilot"], "groups": [], … } }
],
"pagination": { "has_more": false, "next_cursor": null }
}
| Show as | When the row has | SDK |
|---|---|---|
| Frontline user | Status not deactivated, and enabled_products is After Call Co-Pilot only | list_frontline_users(customer) |
| Manager | Status not deactivated, all three products, and not tagged department: "integration" | list_managers(customer) |
Endpoint: GET /locations/{locationId}/users, filters search and status. For a company-wide list without products, use GET /companies/{companyId}/users. get_seat_customer(company_id) rebuilds the customer object (location, groups, rules, connector) for any of these calls. Integration users are tagged department: "integration"; the SDK leaves them out of both counts.
Gotchas
| Gotcha | Do this |
|---|---|
| One writer per customer | Two writes to the same list at once lose one of them. Serialise writes per customer, with one queue per company, and run sync_numbers(customer, dry_run=True) after each batch. |
| New rule, new group | An integration user reads only the alerts its groups receive. When you add a rule, add the location's API Integration group to its group_ids. |
| Read, merge, write | Company and location products, group membership, user lines, First Alert lines, Insights Hub lines and rule triggers are full replacements. Read the current list, change it, write the whole list back. The First Alert config clears the webhook address if you leave it out. |
| Idempotency-Key on user create | Required on user create (400 without it). Send a new UUID per user and reuse it when you retry the same create: the replay returns the original response. No other create is idempotent: on a lost response, look the object up by name before retrying. |
| Half-created user after a 422 | A 422 from user create can still leave the user behind, and a retry then returns 409. After a 422, find the user with GET /companies/{companyId}/users?search=<email> and fix it with PATCH. |
| Extension discovery | The API doesn't list a domain's extensions. Read them from NetSapiens with your own key, GET <api_url>/domains/{domain}/users, and leave out system entries such as auto attendants and trunks. |
| One extension, one location | Mapping a user to an extension another location already captures returns 409. Show your own message (“Extension is already monitored at another location”), not the response text, and release it there first. First Alert and Insights Hub line lists don't check this, so keep each extension at exactly one location. |
| Connector status | Create, deactivate and reactivate return 202 and finish in the background. Check the status every 10 seconds until it settles (active, inactive or error), for up to 10 minutes, then stop. User lines need an active connector (422 otherwise). The dry run doesn't check write permission. Connectors are never deleted: deactivate instead. |
| Deactivation keeps access settings | A deactivated user keeps products, groups and lines. Clear groups and lines so alert groups and Insights Hub lists stay right. Seat counts skip deactivated users, so products can stay. |
| Company read counts | GET /companies/{companyId} reports 0 locations and users. Count from the lists. |
| Invitation links | The user-create response can carry a one-time sign-in link. Never log it or return it to a browser. |
Conversation intelligence access
Read every conversation, alert, task and insight your integration user can see. Every example below runs as a frontline integration user; the SDK lines assume a frontline client called ic, whose conversation helpers are on ic.intelligence. A search_* or list_* helper returns one page (items, the next cursor, has_more, total); its iter_* twin follows the cursor for you.
The curl examples in this chapter and the next use these variables:
IC=https://app.intelligence.cloud/api/v1
# frontline integration user: conversation data
TOKEN=$(curl -s "$IC/auth/login" -H "Content-Type: application/json" \
-d '{"email":"crm-sync@example.com","password":"'"$IC_PASSWORD"'"}' | jq -r .access_token)
# admin integration login: webhook configuration
ADMIN_TOKEN=$(curl -s "$IC/auth/login" -H "Content-Type: application/json" \
-d '{"email":"provisioning@example.com","password":"'"$IC_ADMIN_PASSWORD"'"}' | jq -r .access_token)
# webhook path token: 32+ random characters, one per location, kept in your secrets manager
PATH_TOKEN=$(openssl rand -hex 32)
Conversations
One search field covers phone numbers and text. It matches caller and callee names (typo-tolerant), numbers in any format including partial digits and extensions, the summary, key points and the transcript. Name and number matches come first. Combine it with a date range and any other filter: all filters combine with AND.
1By phone number
curl -sG "$IC/calls" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "search=5555550142" \ --data-urlencode "limit=100"
calls = ic.intelligence.search_calls(phone="+1 (555) 555-0142")
$calls = $ic->intelligence->searchCalls(phone: '+1 (555) 555-0142');
const calls = await ic.intelligence.searchCalls({ phone: '+1 (555) 555-0142' });
Any format works: +15555550142, 5555550142, the last four digits, or an extension such as 2102. Without dates the window is 00:00 UTC seven days ago until now. For a look-up on every incoming call, such as a CRM screen-pop, send date_from (30 days back at most) and location_id, and cache the result.
2By text
curl -sG "$IC/calls" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "search=crown replacement" \ --data-urlencode "limit=100"
calls = ic.intelligence.search_calls(text="crown replacement")
$calls = $ic->intelligence->searchCalls(text: 'crown replacement');
const calls = await ic.intelligence.searchCalls({ text: 'crown replacement' });
At least two characters. Phone and text share the one search field, so send one or the other: the SDKs refuse both at once.
3By date range
curl -sG "$IC/calls" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "date_from=2026-11-02T00:00:00-06:00" \ --data-urlencode "date_to=2026-11-08T23:59:59-06:00" \ --data-urlencode "limit=100"
from datetime import datetime, timezone
from zoneinfo import ZoneInfo
ct = ZoneInfo("America/Chicago")
calls = ic.intelligence.search_calls(date_from=datetime(2026, 11, 2, tzinfo=ct),
date_to=datetime(2026, 11, 8, 23, 59, 59, tzinfo=ct))
$tz = new DateTimeZone('America/Chicago');
$calls = $ic->intelligence->searchCalls(
dateFrom: new DateTimeImmutable('2026-11-02 00:00:00', $tz),
dateTo: new DateTimeImmutable('2026-11-08 23:59:59', $tz),
);
const calls = await ic.intelligence.searchCalls({
dateFrom: new Date('2026-11-02T00:00:00-06:00'),
dateTo: new Date('2026-11-08T23:59:59-06:00'),
});
4Combined
curl -sG "$IC/calls" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "search=5555550142" \ --data-urlencode "date_from=2026-10-01T00:00:00Z" \ --data-urlencode "date_to=2026-11-15T23:59:59Z" \ --data-urlencode "sentiment=negative" \ --data-urlencode "status=completed" \ --data-urlencode "location_id=0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02" \ --data-urlencode "limit=100"
calls = ic.intelligence.search_calls(phone="5555550142",
date_from=datetime(2026, 10, 1, tzinfo=timezone.utc),
date_to=datetime(2026, 11, 15, 23, 59, 59, tzinfo=timezone.utc),
sentiment="negative", status="completed",
location_ids=[LOCATION_ID])
$calls = $ic->intelligence->searchCalls(
phone: '5555550142',
dateFrom: new DateTimeImmutable('2026-10-01T00:00:00Z'),
dateTo: new DateTimeImmutable('2026-11-15T23:59:59Z'),
sentiment: 'negative', status: 'completed',
locationIds: [$locationId],
);
const calls = await ic.intelligence.searchCalls({
phone: '5555550142',
dateFrom: new Date('2026-10-01T00:00:00Z'),
dateTo: new Date('2026-11-15T23:59:59Z'),
sentiment: 'negative', status: 'completed',
locationIds: [locationId],
});
5One call and its transcript
curl -s "$IC/calls/$CALL_ID" -H "Authorization: Bearer $TOKEN" curl -s "$IC/calls/$CALL_ID/transcript" -H "Authorization: Bearer $TOKEN"
call = ic.intelligence.get_call(call_id) lines = ic.intelligence.get_transcript(call_id)
$call = $ic->intelligence->getCall($callId); $lines = $ic->intelligence->getTranscript($callId);
const call = await ic.intelligence.getCall(callId); const lines = await ic.intelligence.getTranscript(callId);
Call detail adds the analysis (summary, key points, action items, sentiment, topics) and the call's tasks. Transcript speakers are Speaker 1 … Speaker N, with name when the person is known. See GET /calls/{callId} and GET /calls/{callId}/transcript.
6Recording link
The call detail carries a signed link to the call's audio in vcon.recording_url, with vcon.recording_url_expires_at and vcon.recording_mime_type (audio/wav). The SDKs return only the link and its expiry.
# 1. a fresh link, each time you need the audio 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 # 2. the audio: no Authorization header; Range requests work curl -s -o call.wav "$RECORDING_URL" curl -s -H "Range: bytes=0-65535" -o first-64k.wav "$RECORDING_URL"
import httpx
link = ic.intelligence.get_recording_url(call_id) # None when the call has no recording
if link:
audio = httpx.get(link.url).content # no Authorization header; expires at link.expires_at
$link = $ic->intelligence->getRecordingUrl($callId); // null when the call has no recording
if ($link !== null) {
$audio = (string) (new \GuzzleHttp\Client())->get($link->url)->getBody(); // no Authorization header
}
const { url, expiresAt } = await ic.intelligence.getRecordingUrl(callId); // url is null when there is no recording
if (url) {
const audio = Buffer.from(await (await fetch(url)).arrayBuffer()); // no Authorization header
}
| Level | Rule |
|---|---|
| Must | Treat the link as a secret. Anyone who holds it can download the audio until it expires. Never log it, store it, or put it in a ticket, queue or error report. |
| Must | Fetch a fresh link each time you need the audio. It stops working 120 minutes after issue (recording_url_expires_at); read the call again rather than keeping a link. |
| Must | Send no Authorization header to the link. It is signed already. Range requests are supported, so you can stream or resume a download. |
The expiry is a datetime in Python (link.expires_at), a DateTimeImmutable in PHP ($link->expiresAt) and an RFC 3339 string in TypeScript (expiresAt). Read the link with get_recording_url rather than from the call detail: PHP's getCall() helper leaves vcon out. See GET /calls/{callId}.
Filters for GET /calls
| Parameter | Format | What it does |
|---|---|---|
date_from | RFC 3339 timestamp | Start of the window (inclusive), on the call date. Full RFC 3339 timestamp required, e.g. 2026-11-01T00:00:00Z or 2026-11-01T00:00:00-06:00; a date alone returns 400. Default: 00:00 UTC seven days ago. date_from after date_to returns 422; a span over 366 days returns 422 when both are sent. |
date_to | RFC 3339 timestamp | End of the window (inclusive). Full RFC 3339 timestamp required. Default: now. A date_to alone that is older than the default start returns an empty list. |
status | completed | missed | voicemail | failed | cancelled | Call outcome. One value, case-sensitive. Invalid values return 422. |
sentiment | crisis | very_negative | negative | mildly_negative | below_neutral | neutral | positive | none | One sentiment band. Score bands: crisis ≤ −80; very_negative −79 to −60; negative −59 to −40; mildly_negative −39 to −20; below_neutral −19 to −1; neutral 0; positive ≥ 1. negative, neutral and positive also match records with that label and no score. none matches records with no sentiment. Invalid values return 422. |
has_open_tasks | true | Only true is recognised (calls with at least one open task). Any other value is ignored. |
multi_leg | Boolean | true: calls with more than one leg (leg_count > 1). false: single-leg calls. Accepts true/false/1/0/t/f; other values return 400. |
location_id | UUID list, comma-separated, up to 100 | One location id or a comma-separated list. A location you can't see matches nothing. Malformed ids return 400. Keep lists to about 50 ids (URL length). |
company_id | UUID | Narrow to one company. |
search | Text, 2+ characters | Free text, at least 2 characters (shorter is ignored). Matches caller and callee names (typo-tolerant), numbers in any format including partial digits and extensions, the summary, key points and the transcript. Name and number matches come first. Call ids don't match; use GET /calls/{callId}. |
cursor | Text | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
limit | Integer (1–100, default 10) | Page size. Out-of-range values return 400. Use 100 for exports. |
Every query parameter GET /calls accepts. Filters combine with AND.
SDK: ic.intelligence.search_calls(phone, text, date_from, date_to, status, sentiment, has_open_tasks, multi_leg, location_ids, *, company_id, limit, cursor); iter_calls takes the same filters without limit and cursor and follows next_cursor for you. PHP takes the same names as named arguments in camelCase; TypeScript takes one object in camelCase.
Alerts
Each alert is one First Alert hit: the call, the rule names that fired (keywords), the summary and sentiment. Alerts are dated by their call. Open the call itself with its call_id. Alert rows carry no location id: to route alerts by location, query each location_id on its own.
1By alert name
curl -sG "$IC/alerts" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "keyword=Customer Threat" \ --data-urlencode "limit=100"
alerts = ic.intelligence.search_alerts(alert_name="Customer Threat")
$alerts = $ic->intelligence->searchAlerts(alertName: 'Customer Threat');
const alerts = await ic.intelligence.searchAlerts({ alertName: 'Customer Threat' });
The exact rule name, case-sensitive, one per request. For both Seat alerts, make two requests.
2By date range
curl -sG "$IC/alerts" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "date_from=2026-11-01T00:00:00Z" \ --data-urlencode "date_to=2026-11-15T23:59:59Z" \ --data-urlencode "limit=100"
alerts = ic.intelligence.search_alerts(date_from=datetime(2026, 11, 1, tzinfo=timezone.utc),
date_to=datetime(2026, 11, 15, 23, 59, 59, tzinfo=timezone.utc))
$alerts = $ic->intelligence->searchAlerts(
dateFrom: new DateTimeImmutable('2026-11-01T00:00:00Z'),
dateTo: new DateTimeImmutable('2026-11-15T23:59:59Z'),
);
const alerts = await ic.intelligence.searchAlerts({
dateFrom: new Date('2026-11-01T00:00:00Z'),
dateTo: new Date('2026-11-15T23:59:59Z'),
});
3By phone number
curl -sG "$IC/alerts" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "numbers=5555550142,5555550188" \ --data-urlencode "limit=100"
alerts = ic.intelligence.search_alerts(numbers=["5555550142", "5555550188"])
$alerts = $ic->intelligence->searchAlerts(numbers: ['5555550142', '5555550188']);
const alerts = await ic.intelligence.searchAlerts({ numbers: ['5555550142', '5555550188'] });
Up to 25 numbers, digits only on the wire (no +, dashes or spaces: the SDKs strip them). Each matches part of the caller or callee number; several numbers match any of them. Extensions work too. Send the last 10 digits of a North American number (5555550142): a leading 1 misses numbers stored without it. The SDKs send a North American number as its last 10 digits.
4Combined
curl -sG "$IC/alerts" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "keyword=Upset Customer" \ --data-urlencode "numbers=5555550142" \ --data-urlencode "date_from=2026-10-01T00:00:00Z" \ --data-urlencode "date_to=2026-11-15T23:59:59Z" \ --data-urlencode "limit=100"
alerts = ic.intelligence.search_alerts(alert_name="Upset Customer", numbers=["5555550142"],
date_from=datetime(2026, 10, 1, tzinfo=timezone.utc),
date_to=datetime(2026, 11, 15, 23, 59, 59, tzinfo=timezone.utc))
$alerts = $ic->intelligence->searchAlerts(
alertName: 'Upset Customer', numbers: ['5555550142'],
dateFrom: new DateTimeImmutable('2026-10-01T00:00:00Z'),
dateTo: new DateTimeImmutable('2026-11-15T23:59:59Z'),
);
const alerts = await ic.intelligence.searchAlerts({
alertName: 'Upset Customer', numbers: ['5555550142'],
dateFrom: new Date('2026-10-01T00:00:00Z'),
dateTo: new Date('2026-11-15T23:59:59Z'),
});
5One alert, and its call
curl -sG "$IC/alerts" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "search=$ALERT_ID" # lowercase id; no date window needed curl -s "$IC/calls/$CALL_ID" -H "Authorization: Bearer $TOKEN" # call_id from the alert
alert = ic.intelligence.get_alert(alert_id, with_call=True)
$alert = $ic->intelligence->getAlert($alertId, withCall: true);
const alert = await ic.intelligence.getAlert(alertId, { withCall: true });
{
"data": {
"summary": { "total": 1 },
"alerts": [ {
"id": "0193b6e1-…", "call_id": "0193b6d0-…", "call_date": "2026-11-02T16:41:07Z",
"caller_name": "Morgan Diaz", "caller_number": "+15555550142",
"callee_name": "Jordan Reyes", "callee_number": "2102",
"summary": "Caller says the crown was billed twice and wants a refund today.",
"sentiment": "negative", "sentiment_score": -46, "sentiment_label": "negative",
"keywords": ["Upset Customer"], "topics": []
} ]
},
"meta": { "has_more": false, "next_cursor": null, "limit": 10 }
}
Filters for GET /alerts
| Parameter | Format | What it does |
|---|---|---|
date_from | RFC 3339 timestamp | Start of the window (inclusive), on the call date. Full RFC 3339 timestamp required, e.g. 2026-11-01T00:00:00Z or 2026-11-01T00:00:00-06:00; a date alone returns 400. Default: 00:00 UTC seven days ago. date_from after date_to returns 422; a span over 366 days returns 422 when both are sent. |
date_to | RFC 3339 timestamp | End of the window (inclusive). Full RFC 3339 timestamp required. Default: now. A date_to alone that is older than the default start returns an empty list. |
keyword | Text | Exact alert rule name, case-sensitive, one value. This is how you filter by rule. |
topic | Text | Exact topic slug, one value. |
numbers | List, comma-separated, up to 25 | Comma-separated, up to 25 entries. Each entry is letters, digits, @ or # only (no +, - or spaces; strip to digits first). Each entry is a substring match on the caller or callee number; entries are OR'ed together. |
sentiment | crisis | very_negative | negative | mildly_negative | below_neutral | neutral | positive | none | One sentiment band. Score bands: crisis ≤ −80; very_negative −79 to −60; negative −59 to −40; mildly_negative −39 to −20; below_neutral −19 to −1; neutral 0; positive ≥ 1. negative, neutral and positive also match records with that label and no score. none matches records with no sentiment. Invalid values return 422. |
search | Text | Matches caller or callee name or number, summary text, or an exact lowercase alert id. Rule names don't match; use keyword. |
location_id | UUID list, comma-separated, up to 100 | One location id or a comma-separated list. A location you can't see matches nothing. Malformed ids return 400. Keep lists to about 50 ids (URL length). |
company_id | UUID | Narrow to one company. |
cursor | Text | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
limit | Integer (1–100, default 10) | Page size. Out-of-range values return 400. Use 100 for exports. |
Every query parameter GET /alerts accepts. Filters combine with AND.
SDK: ic.intelligence.search_alerts(alert_name, numbers, text, sentiment, date_from, date_to, location_ids, *, topic, company_id, limit, cursor), and iter_alerts; alert_name sends keyword and text sends search. get_alert returns the alert, or nothing when this login can't see it; with with_call the call detail is under call.
Filters for GET /alerts/dashboard
Alert totals for a window: new alerts, calls covered, the alert rate, the most-triggered rules and the five most recent alerts.
| Parameter | Format | What it does |
|---|---|---|
date_from | RFC 3339 timestamp | Start of the window (inclusive), on the call date. Full RFC 3339 timestamp required, e.g. 2026-11-01T00:00:00Z or 2026-11-01T00:00:00-06:00; a date alone returns 400. Default: 00:00 UTC seven days ago. date_from after date_to returns 422; a span over 366 days returns 422 when both are sent. |
date_to | RFC 3339 timestamp | End of the window (inclusive). Full RFC 3339 timestamp required. Default: now. A date_to alone that is older than the default start returns an empty list. |
location_id | UUID list, comma-separated, up to 100 | One location id or a comma-separated list. A location you can't see matches nothing. Malformed ids return 400. Keep lists to about 50 ids (URL length). |
company_id | UUID | Narrow to one company. |
Every query parameter GET /alerts/dashboard accepts. Filters combine with AND.
Tasks and Insights Hub
Tasks are the follow-ups After Call Co-Pilot takes from each call. Pull open and overdue tasks into a ticketing system or a daily list. There is no default window. Pass today_start as your local midnight so “overdue” matches the customer's day.
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"
tasks = ic.intelligence.list_tasks(status="overdue",
today_start=datetime(2026, 11, 16, tzinfo=ZoneInfo("America/Chicago")))
$tasks = $ic->intelligence->listTasks(status: 'overdue',
todayStart: new DateTimeImmutable('2026-11-16 00:00:00', new DateTimeZone('America/Chicago')));
const tasks = await ic.intelligence.listTasks({ status: 'overdue', todayStart: new Date('2026-11-16T00:00:00-06:00') });
Filters for GET /tasks
| Parameter | Format | What it does |
|---|---|---|
status | pending | in_progress | done | overdue | open | Display status: done (completed); pending (not done, no due date); in_progress (not done, due today or later); overdue (not done, due before today); open (not done). summary counts ignore this filter. |
today_start | RFC 3339 timestamp | Your local midnight as a full RFC 3339 timestamp, e.g. 2026-11-02T00:00:00-06:00. Sets the boundary for overdue and in_progress. |
call_id | UUID | Tasks of one call. |
task_id | UUID | One task. Can't be combined with due_on. |
due_on | Date YYYY-MM-DD | Tasks due on this calendar date (YYYY-MM-DD). |
date_from | RFC 3339 timestamp | Created at or after. Full RFC 3339 timestamp required. No default. |
date_to | RFC 3339 timestamp | Created at or before. Full RFC 3339 timestamp required. date_from after date_to returns an empty list. |
search | Text | Substring match on title and description. |
location_id | UUID list, comma-separated, up to 100 | One location id or a comma-separated list. A location you can't see matches nothing. Malformed ids return 400. Keep lists to about 50 ids (URL length). |
company_id | UUID | Narrow to one company. |
cursor | Text | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
limit | Integer (1–100, default 20) | Page size. Send 100 and follow next_cursor. |
Every query parameter GET /tasks accepts. Filters combine with AND.
Insights Hub returns call volume, trending topics and topic volumes for a window, then the calls behind any topic. start and end are required.
curl -sG "$IC/insights/dashboard" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "start=2026-11-01T00:00:00Z" \ --data-urlencode "end=2026-11-15T23:59:59Z" # then the calls behind one topic, using a slug from topic_call_volumes[].slug curl -sG "$IC/insights/topics/$SLUG/calls" -H "Authorization: Bearer $TOKEN" \ --data-urlencode "date_from=2026-11-01T00:00:00Z" \ --data-urlencode "sentiment=negative"
board = ic.intelligence.get_insights_dashboard(start=datetime(2026, 11, 1, tzinfo=timezone.utc),
end=datetime(2026, 11, 15, 23, 59, 59, tzinfo=timezone.utc))
topic_calls = ic.intelligence.list_topic_calls(slug, sentiment="negative")
$board = $ic->intelligence->getInsightsDashboard(
start: new DateTimeImmutable('2026-11-01T00:00:00Z'),
end: new DateTimeImmutable('2026-11-15T23:59:59Z'),
);
$topicCalls = $ic->intelligence->listTopicCalls($slug, sentiment: 'negative');
const board = await ic.intelligence.getInsightsDashboard({
start: new Date('2026-11-01T00:00:00Z'), end: new Date('2026-11-15T23:59:59Z'),
});
const topicCalls = await ic.intelligence.listTopicCalls(slug, { sentiment: 'negative' });
Filters for GET /insights/dashboard
| Parameter | Format | What it does |
|---|---|---|
start required | RFC 3339 timestamp | Window start. Full RFC 3339 timestamp required. |
end required | RFC 3339 timestamp | Window end. Full RFC 3339 timestamp required. At most 366 days after start (422). |
trending_limit | Integer (1–10, default 4) | Number of trending topics, 1 to 10. Values above 10 return 10; values below 1, or not a number, fall back to the default of 4. Neither returns an error. |
location_id | UUID list, comma-separated, up to 100 | One location id or a comma-separated list. A location you can't see matches nothing. Malformed ids return 400. Keep lists to about 50 ids (URL length). |
company_id | UUID | Narrow to one company. |
Every query parameter GET /insights/dashboard accepts. Filters combine with AND.
Filters for GET /insights/topics/{slug}/calls
| Parameter | Format | What it does |
|---|---|---|
date_from | RFC 3339 timestamp | Start of the window, on the call date. Full RFC 3339 timestamp required, e.g. 2026-11-01T00:00:00Z or 2026-11-01T00:00:00-06:00; a date alone returns 400. Default: 00:00 UTC seven days ago. |
date_to | RFC 3339 timestamp | End of the window. Full RFC 3339 timestamp required; a date alone returns 400. Default: now. |
sentiment | positive | neutral | negative | Coarse band only. Other values return 422. |
outcome | completed | missed | pending | Other values return 422. |
search | Text | Same matching as /calls search. |
location_id | UUID list, comma-separated, up to 100 | One location id or a comma-separated list. A location you can't see matches nothing. Malformed ids return 400. Keep lists to about 50 ids (URL length). |
company_id | UUID | Narrow to one company. |
cursor | Text | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
limit | Integer (1–100, default 25) |
Every query parameter GET /insights/topics/{slug}/calls accepts. Filters combine with AND.
Filters for GET /locations
The locations this login can see, for location_id filters. GET /me takes no parameters.
| Parameter | Format | What it does |
|---|---|---|
search | Text | Case-insensitive substring match on location_name. |
is_active | Boolean | true or false. Other values return 422. |
company_id | UUID | |
limit | Integer (1–100, default 20) | Values above 100 are capped. |
cursor | Text | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
offset | Integer | Rows to skip. Prefer cursor. |
Every query parameter GET /locations accepts. Filters combine with AND.
Events and webhooks
Intelligence Cloud pushes an event after every call and when an alert fires, each to an HTTPS address you set per location. A webhook is configured with admin credentials; the data it carries is conversation data and follows the protection rules.
| Channel | Configure | Use it for |
|---|---|---|
| After Call webhook | Per location | Every call at the location, moments after it is processed: CRM notes, tickets, call-back queues. |
| First Alert webhook | Per location, in its First Alert configuration | Each alert as it fires: paging, chat channels, escalation tools. |
Subscribe to both for anything that must happen as calls and alerts arrive. The API is for look-ups and for reading details when an event tells you to; don't poll it for new data (API rules).
After Call webhook
| Step | Call | Notes |
|---|---|---|
| Set the address | PUT /locations/{locationId}/after-call/automation | {"webhook_url": "https://…", "enabled": true}. One HTTPS address per location; private and loopback addresses are refused. Admin credentials. |
| Test it | POST /locations/{locationId}/after-call/automation/test | Sends the test event (is_test: true) to the saved address, even while paused. Returns success, http_status and response_time_ms. The First Alert test names the status status_code. |
| Read it | GET /locations/{locationId}/after-call/automation | {"data": null} when none is set. Admin credentials. Rotate its path token every 90 days and when someone with access to it leaves. |
| Pause it | The same PUT with "enabled": false | There is no delete. Pause, or point it at a new address. |
curl -s -X PUT "$IC/locations/$LOCATION_ID/after-call/automation" \
-H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{"webhook_url":"https://hooks.example.com/ic/after-call/'"$PATH_TOKEN"'","enabled":true}'
curl -s -X POST "$IC/locations/$LOCATION_ID/after-call/automation/test" \
-H "Authorization: Bearer $ADMIN_TOKEN"
admin.intelligence.set_after_call_webhook(location_id, f"https://hooks.example.com/ic/after-call/{path_token}")
result = admin.intelligence.test_after_call_webhook(location_id)
$admin->intelligence->setAfterCallWebhook($locationId, "https://hooks.example.com/ic/after-call/{$pathToken}");
$result = $admin->intelligence->testAfterCallWebhook($locationId);
await admin.intelligence.setAfterCallWebhook(locationId, `https://hooks.example.com/ic/after-call/${pathToken}`);
const result = await admin.intelligence.testAfterCallWebhook(locationId);
The event
{
"version": "1.0",
"type": "end_of_call_summary",
"is_test": false,
"location_id": "0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02",
"timestamp": "2026-11-02T16:46:12Z",
"call": {
"id": "0193b6d0-1e2f-7a3b-8c4d-5e6f7a8b9c01",
"caller_name": "Morgan Diaz",
"caller_number": "+15555550142",
"callee_name": "Jordan Reyes",
"callee_number": "2102",
"call_type": "inbound",
"duration_seconds": 284,
"call_date": "2026-11-02",
"platform": "netsapiens"
},
"summary": {
"text": "The caller's crown was billed twice. Jordan opened a refund and promised a call back by noon.",
"sentiment": "negative"
},
"location": {
"id": "0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02",
"company_id": "0193b6c2-5a11-7c3e-8f20-6d4b9e1c2a77",
"connector_id": "4b7e9d2c-1a3f-4e8b-9c6d-2f5a8e1b3c70"
}
}
| Field | Meaning |
|---|---|
version, type | Always "1.0" and "end_of_call_summary". |
is_test | true only for test sends. Acknowledge and drop them. |
location_id | The location whose address received the event. |
timestamp | When Intelligence Cloud created the conversation record (UTC). Not the call time or the delivery time. |
call.id | The same id as GET /calls/{callId} and an alert's call_id. Upsert on it. |
call.caller_name, caller_number, callee_name, callee_number | Who called whom. Omitted when empty. |
call.call_type | inbound, outbound, internal, missed, forwarded or unknown. |
call.duration_seconds, call.call_date | Length in seconds; the call's date (UTC, date only). |
call.platform | The phone system type. Omitted when empty. |
summary.text, summary.sentiment | The call summary and its sentiment, usually positive, neutral or negative. summary is omitted when the call has none. Test sends also carry key_points and action_items. |
location.id, company_id, connector_id | Where the call was captured. |
Full schema: After Call summary event. For the analysis, key points, action items and tasks, read GET /calls/{call.id}.
Delivery
| Behaviour | Build for it |
|---|---|
| Every call at the location | The address receives every call captured at the location, whatever any user's lines say. It is location-wide data: treat the address as a secret. |
| Answer within 2 seconds | Check the token, queue the event, answer 204, then do the work. Redirects count as failures, so give the final address. |
| Retries are brief | Three attempts in all, a few seconds apart, then the event is dropped. Run a nightly catch-up: read the last 48 hours of calls with GET /calls?date_from=… as a frontline integration user, and process any call.id you haven't handled. Map every line the location captures to that user: calls on unmapped lines return 404 from GET /calls/{callId} and never appear in the catch-up. |
| Repeats happen | A retry after a slow answer, or a call with several legs, can arrive more than once with the same call.id, and a later delivery can carry newer data. Upsert on call.id: when an id repeats, read the call again and update your record. |
| No ordering | Events can arrive in any order. Use timestamp if order matters. |
| Pause | "enabled": false stops deliveries at once; the catch-up fills the gap when you resume. |
First Alert webhook
Each location's First Alert configuration takes an HTTPS address that receives the location's alerts as they fire.
| Step | Call | Notes |
|---|---|---|
| Set the address | PUT /locations/{locationId}/first-alert/config | webhook_url sits beside the monitored lines. The PUT is a full replacement: read the configuration, set webhook_url, and send the lines back with it. Leaving it out clears it. |
| Test it | POST /locations/{locationId}/first-alert/config/test-webhook | {"url": "https://…"}. Returns success and the status_code your endpoint answered. The After Call test names it http_status. |
| Read it | GET /locations/{locationId}/first-alert/config | The address and the monitored lines. |
curl -s "$IC/locations/$LOCATION_ID/first-alert/config" -H "Authorization: Bearer $ADMIN_TOKEN"
# keep connector_mappings exactly as returned, add webhook_url, PUT it back
curl -s -X PUT "$IC/locations/$LOCATION_ID/first-alert/config" \
-H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{"webhook_url":"https://hooks.example.com/ic/alerts/'"$PATH_TOKEN"'",
"connector_mappings":[{"connector_id":"…","monitored_numbers":["2101","2102","2103","2104"]}]}'
curl -s -X POST "$IC/locations/$LOCATION_ID/first-alert/config/test-webhook" \
-H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{"url":"https://hooks.example.com/ic/alerts/'"$PATH_TOKEN"'"}'
admin.intelligence.set_first_alert_webhook(location_id, f"https://hooks.example.com/ic/alerts/{path_token}") # read-merge-write
result = admin.intelligence.test_first_alert_webhook(location_id, f"https://hooks.example.com/ic/alerts/{path_token}")
$admin->intelligence->setFirstAlertWebhook($locationId, "https://hooks.example.com/ic/alerts/{$pathToken}"); // read-merge-write
$result = $admin->intelligence->testFirstAlertWebhook($locationId, "https://hooks.example.com/ic/alerts/{$pathToken}");
await admin.intelligence.setFirstAlertWebhook(locationId, `https://hooks.example.com/ic/alerts/${pathToken}`); // read-merge-write
const result = await admin.intelligence.testFirstAlertWebhook(locationId, `https://hooks.example.com/ic/alerts/${pathToken}`);
The request is a JSON POST describing the alert that fired: the alert id, the rule, the location, the call and the time. Answer 2xx quickly, then read the full alert with GET /alerts?search=<alert id> and the call with GET /calls/{call_id}, as a frontline integration user in Manager Alerts. De-duplicate on the alert id. See First Alert event.
Catching up after an outage
If your receiver was unavailable, read the window you missed once, then go back to the webhooks.
- As a frontline integration user in Manager Alerts, call
GET /alertswithdate_fromset 30 minutes before your receiver went down anddate_towhen it came back. Alerts are dated by their call, so the margin catches calls that were still being processed. - Page through with
cursoruntilhas_moreis false. - Skip any alert
idyou have already handled.
Missed calls work the same way with GET /calls, which the nightly catch-up in Delivery already covers.
came_back = datetime.now(timezone.utc)
went_down = came_back - timedelta(hours=2) # when your receiver stopped answering
handled = set() # your store of handled alert ids
for alert in ic.intelligence.iter_alerts(date_from=went_down - timedelta(minutes=30), date_to=came_back):
if alert["id"] not in handled:
handled.add(alert["id"])
notify_on_call_manager(alert["id"], alert["call_id"]) # ids only: fetch details where needed
$cameBack = new DateTimeImmutable('now', new DateTimeZone('UTC'));
$wentDown = $cameBack->modify('-2 hours'); // when your receiver stopped answering
$handled = []; // your store of handled alert ids
foreach ($ic->intelligence->iterAlerts(dateFrom: $wentDown->modify('-30 minutes'), dateTo: $cameBack) as $alert) {
if (!isset($handled[$alert['id']])) {
$handled[$alert['id']] = true;
notifyOnCallManager($alert['id'], $alert['call_id']); // ids only: fetch details where needed
}
}
const cameBack = new Date();
const wentDown = new Date(cameBack.getTime() - 2 * 3600_000); // when your receiver stopped answering
const handled = new Set<string>(); // your store of handled alert ids
for await (const a of ic.intelligence.iterAlerts({ dateFrom: new Date(wentDown.getTime() - 30 * 60_000), dateTo: cameBack })) {
if (!a.id || !a.call_id || handled.has(a.id)) continue;
handled.add(a.id);
await notifyOnCallManager(a.id, a.call_id); // ids only: fetch details where needed
}
Receiver security
| Level | Rule |
|---|---|
| Must | Put an unguessable token in the path: at least 32 characters from a cryptographic random generator, one per location, for example https://hooks.example.com/ic/after-call/9f3c…e71a. Requests are not signed, so the address is the credential. Compare the token in constant time, answer 404 to anything else, and rotate it by saving a new address. |
| Must | Keep the token out of logs. Switch off or mask access logging for the receiver route in your web server, proxy, load balancer, CDN, WAF and APM, for example nginx access_log off; or uvicorn --no-access-log. Rotate any address that was logged. |
| Must | HTTPS only, with a valid certificate and TLS 1.2 or later. |
| Must | Answer 2xx to every JSON body at a valid address, and ignore event types you don't handle, so new event types never fail your receiver. Answer 400 only to a body that isn't JSON. Cap the body at 256 KB and answer 413 above it. |
| Must | After Call address: act only on version "1.0", type "end_of_call_summary", UUID ids and a location_id you expect at that address. Drop is_test events after acknowledging them.First Alert address: take the alert id, acknowledge, then read the alert. |
| Must | Treat an event as a notification. Before you write anything from it into another system, read GET /calls/{call.id} and use that response. A 404 means drop the event. |
| Never | Log the content. No bodies, names, numbers or summaries in access logs, error trackers or queues' dead-letter dumps. Log the call.id and your status. |
| Should | Answer fast and process asynchronously, and keep the receiver separate from your public site. |
Develop and test
| Step | How |
|---|---|
| A test customer | Use your own company: a test location with two test extensions. Build and test there, never against a customer's calls. |
| No customer data in development | Never copy customer conversation data into development, test or CI systems. |
| The test send | Expose your receiver through an HTTPS tunnel, save the tunnel address on the test location, then call the test endpoint. |
| Locally | Save the event above as after-call-sample.json and post it yourself: curl -X POST "http://localhost:8080/ic/after-call/$PATH_TOKEN" -H 'Content-Type: application/json' -d @after-call-sample.json. The Python download's examples/webhook_receiver.py --self-test posts a sample event to itself. |
SDKs
Three SDKs with the same concepts and the same names, wrapping every rule in this guide: token rotation, retries, read-merge-write, idempotent user create, connector status checks, filter checks and the Seat workflows.
intelligence_cloud
One dependency for HTTP. Sync client with iterators for every list.
Download python-0.1.0.zipWheel: intelligence_cloud-0.1.0-py3-none-any.whl
@intelligence-cloud/sdk
ESM and CommonJS with types, no runtime dependencies. Runs in Next.js server code.
Download typescript-0.1.0.zipPackage: intelligence-cloud-sdk-0.1.0.tgz
Version 0.1.0, distributed from this page. Each download has a README, runnable examples, a sample After Call event and a changelog. Check every download against SHA256SUMS before you install it: shasum -a 256 -c SHA256SUMS.
Install from source
Each zip unpacks to one folder, python/, php/ or typescript/, that holds the package. Unpack it inside your project and install from that folder. Always install from the file path, never by the bare package name: these packages are not on public registries, so a bare-name install could fetch someone else's package.
unzip python-0.1.0.zip -d vendor-src # creates vendor-src/python, which holds pyproject.toml pip install ./vendor-src/python # or, with no build step: pip install ./vendor-src/python/intelligence_cloud-0.1.0-py3-none-any.whl
unzip php-0.1.0.zip -d vendor-src # creates vendor-src/php, which holds composer.json # from the folder that holds your project's composer.json composer config repositories.intelligence-cloud path vendor-src/php composer require intelligence-cloud/sdk:0.1.0
unzip typescript-0.1.0.zip -d vendor-src # creates vendor-src/typescript, which holds the package tarball npm install ./vendor-src/typescript/intelligence-cloud-sdk-0.1.0.tgz
The TypeScript download includes intelligence-cloud-sdk-0.1.0.tgz, the built package with no development tools, so nothing needs compiling. The PHP download has no vendor/: Composer installs Guzzle.
Quick start: customer lifecycle
import os
from intelligence_cloud import Client, ConnectorSpec, LocationSpec, SeatCustomerSpec, UserSpec
# Phrase list from your Tresic contact, one per line, kept outside source control
with open(os.environ["IC_THREAT_PHRASES_FILE"]) as f:
threat_phrases = [line.strip() for line in f if line.strip()]
admin = Client(email=os.environ["IC_ADMIN_EMAIL"], password=os.environ["IC_ADMIN_PASSWORD"])
seat = admin.workflows.provision_seat_customer(SeatCustomerSpec(
company_name="Northgate Dental",
admin_name="Dana Whitfield", admin_email="dana.whitfield@example.com", admin_phone="+15555550110",
location=LocationSpec(name="Northgate Dental - Main", street="100 Harbor Way", city="Springfield",
state="IL", country="US", zipcode="62701", vertical=VERTICAL_ID),
threat_phrases=threat_phrases,
connector=ConnectorSpec(api_url="https://pbx.example.com/ns-api/v2",
domain="northgatedental.example", api_key=os.environ["NS_API_KEY"]),
))
admin.workflows.add_manager(seat, UserSpec("avery.lane@example.com", "Avery", "Lane"))
admin.workflows.add_frontline_user(seat, UserSpec("jordan.reyes@example.com", "Jordan", "Reyes"), "2102")
print([u["email"] for u in admin.workflows.list_managers(seat)])
use IntelligenceCloud\Client;
use IntelligenceCloud\Lifecycle\{ConnectorSpec, LocationSpec, SeatCustomerSpec, UserSpec};
// Phrase list from your Tresic contact, one per line, kept outside source control
$threatPhrases = file(getenv('IC_THREAT_PHRASES_FILE'), FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
$admin = new Client(email: getenv('IC_ADMIN_EMAIL'), password: getenv('IC_ADMIN_PASSWORD'));
$seat = $admin->workflows->provisionSeatCustomer(new SeatCustomerSpec(
companyName: 'Northgate Dental',
adminName: 'Dana Whitfield', adminEmail: 'dana.whitfield@example.com', adminPhone: '+15555550110',
location: new LocationSpec(name: 'Northgate Dental - Main', street: '100 Harbor Way', city: 'Springfield',
state: 'IL', country: 'US', zipcode: '62701', vertical: $verticalId),
threatPhrases: $threatPhrases,
connector: new ConnectorSpec(apiUrl: 'https://pbx.example.com/ns-api/v2',
domain: 'northgatedental.example', apiKey: getenv('NS_API_KEY')),
));
$admin->workflows->addManager($seat, new UserSpec('avery.lane@example.com', 'Avery', 'Lane'));
$admin->workflows->addFrontlineUser($seat, new UserSpec('jordan.reyes@example.com', 'Jordan', 'Reyes'), '2102');
import { readFileSync } from 'node:fs';
import { Client } from '@intelligence-cloud/sdk';
// Phrase list from your Tresic contact, one per line, kept outside source control
const threatPhrases = readFileSync(process.env.IC_THREAT_PHRASES_FILE!, 'utf8')
.split('\n').map((l) => l.trim()).filter(Boolean);
const admin = new Client({ email: process.env.IC_ADMIN_EMAIL!, password: process.env.IC_ADMIN_PASSWORD! });
const seat = await admin.workflows.provisionSeatCustomer({
companyName: 'Northgate Dental',
primaryAdmin: { name: 'Dana Whitfield', email: 'dana.whitfield@example.com', phone: '+15555550110' },
location: { name: 'Northgate Dental - Main', street: '100 Harbor Way', city: 'Springfield',
state: 'IL', country: 'US', zipcode: '62701', verticalId },
threatPhrases,
connector: { apiUrl: 'https://pbx.example.com/ns-api/v2',
domain: 'northgatedental.example', apiKey: process.env.NS_API_KEY! },
});
await admin.workflows.addManager(seat, { email: 'avery.lane@example.com', firstName: 'Avery', lastName: 'Lane' });
await admin.workflows.addFrontlineUser(seat, { email: 'jordan.reyes@example.com', firstName: 'Jordan', lastName: 'Reyes' }, '2102');
The result holds every id, and the connector's final status and state_reason: a read-only key ends in error / invalid_permissions without stopping the rest of the build. Re-run it after fixing the key.
Quick start: conversation intelligence
import os
from datetime import datetime, timedelta, timezone
from intelligence_cloud import Client
ic = Client(email=os.environ["IC_DATA_EMAIL"], password=os.environ["IC_DATA_PASSWORD"])
ic.intelligence.require_frontline()
since = datetime.now(timezone.utc) - timedelta(days=1)
calls = ic.intelligence.search_calls(phone="5555550142", date_from=since)
threats = ic.intelligence.search_alerts(alert_name="Customer Threat", date_from=since)
for alert in threats.items:
print(alert["id"], alert["call_id"])
use IntelligenceCloud\Client;
$ic = new Client(email: getenv('IC_DATA_EMAIL'), password: getenv('IC_DATA_PASSWORD'));
$ic->intelligence->requireFrontline();
$since = new DateTimeImmutable('-1 day', new DateTimeZone('UTC'));
$calls = $ic->intelligence->searchCalls(phone: '5555550142', dateFrom: $since);
$threats = $ic->intelligence->searchAlerts(alertName: 'Customer Threat', dateFrom: $since);
foreach ($threats as $alert) {
echo $alert['id'], ' ', $alert['call_id'], "\n";
}
import { Client } from '@intelligence-cloud/sdk';
const ic = new Client({ email: process.env.IC_DATA_EMAIL!, password: process.env.IC_DATA_PASSWORD! });
await ic.intelligence.requireFrontline();
const since = new Date(Date.now() - 24 * 3600_000);
const calls = await ic.intelligence.searchCalls({ phone: '5555550142', dateFrom: since });
const threats = await ic.intelligence.searchAlerts({ alertName: 'Customer Threat', dateFrom: since });
for (const alert of threats.items) console.log(alert.id, alert.call_id);
Workflow methods
Admin credentials, on client.workflows. Python names shown; PHP and TypeScript use the same names in camelCase ($admin->workflows->provisionSeatCustomer(), admin.workflows.provisionSeatCustomer()). customer is the object provision_seat_customer or get_seat_customer returns; TypeScript also takes a company id.
| Method | Does |
|---|---|
provision_seat_customer(spec) | Creates the company, turns MFA off when mfa_off is set, switches on After Call, First Alert and Insights Hub, creates the single location, the Manager Alerts and Insights Hub Access groups, the Upset Customer and Customer Threat rules routed to Manager Alerts, and the Insights Hub setup. Optional connector (checked every 10 seconds, for up to 10 minutes, until it settles; an error is recorded on the result, not raised) and SSO domain claim (returns the TXT record). Rules are created switched off; the first add_manager switches them on. Safe to re-run: pass company_id from the first run (a company is never adopted by name alone); it finds the rest by name, the connector by domain, and creates only what is missing. A company or location found deactivated is an error unless reactivate is set. Returns every id. |
add_frontline_user(customer, user, extension) | Creates a frontline user without an invitation, with After Call Co-Pilot only and alert email off, maps their extension, and adds it to every manager, First Alert and Insights Hub. Emails the invitation last. Needs a connector. |
add_manager(customer, user, *, activate_alerts=True) | Creates a manager without an invitation, with all three products, both groups, alert email on, and every end user's line. The manager's own line is never captured. Then switches the two rules on (activate_seat_alerts) and emails the invitation last. activate_alerts=False leaves the rules as they are. TypeScript: addManager(customer, user, { activateAlerts }). |
activate_seat_alerts(customer) | Switches Upset Customer and Customer Threat on when they are off, and returns the ids it switched on. |
change_user_extension(customer, user_id, old, new) | Moves a number and re-syncs the user, every manager, First Alert and Insights Hub. |
remove_user(customer, user_id, keep_extensions=False) | Takes the user out of every group, clears their lines and deactivates them. Only an end user's line is released, and only when no other end user holds it: it comes off managers, integration users, First Alert and Insights Hub (unless kept). Removing a manager, an integration user or anyone holding several lines takes no line off anyone else. Returns kind: frontline, manager or integration. Products are left as they are. |
list_frontline_users(customer)list_managers(customer)list_integration_users(customer) | The management dashboard view, classified: end users have After Call only, managers all three products, integration users are tagged department: "integration". |
sync_numbers(customer, dry_run=False) | Pushes the location's lines (each end user's single extension) to managers, integration users, First Alert and Insights Hub. dry_run=True returns the diff only. |
add_integration_user(customer, user) | Password sign-in, tagged department: "integration", all three products, both groups, alert email off, every line. Never counted as a seat or a manager; later lines are added to it. Emails the invitation last. |
offboard_customer(customer, deactivate_company=True) | Pauses the After Call webhook, clears the First Alert webhook, stops the connector, deactivates the integration users, then the company. Safe to re-run. |
get_seat_customer(company_id) | Rebuilds the customer object (location, groups, rules, connector) by name. |
The user workflows email an invitation only when the user spec's send_invitation is true (the default) and the user has not yet accepted one; pass send_invitation=False to hold it back and send it later with users.resend_invitation. When the API refuses a user's lines (the connector is not active yet, or another location already monitors the extension), the workflow stops before it touches managers, First Alert and Insights Hub, sends no invitation, leaves the rules as they are, and raises ExtensionMappingError with the user's id. Fix the cause and run it again: it finds the user by email, carries on, and sends the invitation at the end. To keep particular users out of the workflows' line handling, set customer.exclude_user_ids or customer.exclude_emails.
Seat spec fields
Python and PHP use spec classes (PHP: IntelligenceCloud\Lifecycle\…, with named arguments in camelCase). TypeScript takes a plain object.
| Part | Python and PHP | TypeScript |
|---|---|---|
| Customer | SeatCustomerSpec(company_name, admin_name, admin_email, admin_phone, location, threat_phrases, mfa_off, connector, sso_domain, reactivate) | { companyName, primaryAdmin: { name, email, phone }, location, threatPhrases, mfaOff, connector, sso: { domain }, reactivate } |
| Location | LocationSpec(name, street, city, state, country, zipcode, vertical): vertical is an id or key from GET /verticals | { name, street, city, state, country, zipcode, verticalId }, or verticalKey instead of verticalId |
| Connector | ConnectorSpec(api_url, domain, api_key, name=None, timeout=120) | { apiUrl, domain, apiKey, name, timeout, monitoredNumbers } |
| User | UserSpec(email, first_name, last_name, phone_number=None, send_invitation=True, auth_method="password") | { email, firstName, lastName, phoneNumber, sendInvitation, authMethod, idempotencyKey } |
| Result | SeatCustomer: company_id, location_id, the group and rule ids, connector_id, connector_status, connector_state_reason, sso_txt_record | { companyId, locationId, groups, rules, connectorId, connectorStatus, connectorStateReason, ssoTxtRecord, created } |
Intelligence and webhook methods
On client.intelligence. The conversation helpers need a frontline login; the webhook configuration needs admin credentials. TypeScript also exposes each of these on the client itself (ic.searchCalls()).
| Method | Does |
|---|---|
whoami(), require_frontline() | The signed-in user; raises FrontlineRequiredError when the login is an admin, which would read empty lists. |
search_calls(…), iter_calls(…) | GET /calls with typed filters: one page, or every match. phone and text both send search. |
get_call(call_id), get_transcript(call_id) | Call detail and transcript lines. |
get_recording_url(call_id) | The recording link and its expiry, nothing else. |
search_alerts(…), iter_alerts(…) | GET /alerts; alert_name sends keyword. |
get_alert(alert_id, with_call=False) | One alert by id, optionally with its call under call. |
get_alerts_dashboard(…), list_tasks(…), iter_tasks(…), get_insights_dashboard(start, end), list_topic_calls(slug, …), iter_topic_calls(slug, …) | Thin wrappers with the filters in Alerts and Tasks and Insights Hub. |
get_after_call_webhook, set_after_call_webhook, test_after_call_webhook | After Call webhook configuration (admin). |
get_first_alert_webhook, set_first_alert_webhook, test_first_alert_webhook | First Alert webhook configuration (admin), read-merge-write. Both tests return only success and the HTTP status. |
Every API operation is also a method named after its operationId, grouped by reference section: client.companies, client.locations, client.users, client.first_alert (firstAlert in PHP and TypeScript), client.calls and the rest. The full-replacement calls have add_* / remove_* helpers that read, merge and write. Each download's README lists them.
Client options
| Option | Does |
|---|---|
| Base URL | Must be https://; plain http:// is accepted only for localhost. |
login_rate_limit_wait / loginRateLimitWait | Seconds to wait when sign-in is rate limited (default 60; 0 raises at once). |
keep_unknown_fields / keepUnknownFields | Python and TypeScript: keep fields the SDK doesn't list on customer-lifecycle reads. Conversation data is always returned with the documented fields only. |
| Token store | Pass a shared store to every process that signs in as one integration user. Stores lock around sign-in and renewal (lock() in Python, withLock in PHP and TypeScript); FileTokenStore (Python, TypeScript) does this for processes on one machine. |
| Dates | Python accepts time-zone-aware datetime objects; a datetime without a time zone is refused. PHP takes DateTimeInterface, TypeScript Date. |
Errors
One hierarchy in every language, under IntelligenceCloudError: ApiError with the HTTP status, the error code, the message and the request id, and its subclasses AuthError (401), NotFoundError (404, also returned for records outside your scope), ConflictError (409; an extension conflict lists the extensions), ValidationError (400 and 422) and RateLimitError (429 after retries). Alongside them: MfaRequiredError (MFA is on for the integration user's company), FrontlineRequiredError (conversation data asked for with an admin login), ConnectorError (carries the connector's state_reason), ExtensionMappingError (a workflow could not map a user's lines), PasswordExpiredError (the integration user's password has expired: stop and alert an operator), WebhookPayloadError (not JSON, or a malformed After Call event; other event types return UnknownEvent) and its subclass PayloadTooLargeError (a body over 256 KB: answer 413). Exception text carries only the status, code and request id plus SDK-written text; the server's text is on message (Python), serverMessage (TypeScript) or $serverMessage (PHP). Log status, code and request_id. 429 is retried everywhere, but a Retry-After above 60 seconds is not waited out: the error is raised at once with retry_after set; 5xx is retried on reads, updates, deletes and user create, never on other creates; both up to three times with backoff.
Where the SDKs differ
| Topic | Python | PHP | TypeScript |
|---|---|---|---|
| Refused before sending | InvalidRequestError (an unknown keyword is a TypeError) | FilterError | FilterError |
| Error code | e.code | $e->errorCode | err.code |
| A workflow fails part-way | The original error is raised | The original error is thrown | WorkflowError with step, partial (the ids created so far) and cause |
| Parse an After Call event | parse_after_call_event(body) | Webhooks::parseAfterCallEvent($body) | parseAfterCallEvent(body) |
| De-duplicate | Deduplicator().is_duplicate(event): true on a repeat | (new Deduplicator($store))->isDuplicate($event): true on a repeat | await new Deduplicator().isDuplicate(id): true on a repeat |
| No recording | None | null | url: null |
ExtensionMappingError passes through the TypeScript WorkflowError unwrapped, as do FilterError and WorkflowError itself. In PHP, ConnectorTimeoutError and MfaRequiredError are subclasses of ConnectorError and AuthError.
Webhook receivers
// app/api/ic-webhook/[token]/route.ts
import { timingSafeEqual } from 'node:crypto';
import { Deduplicator, isUnknownEvent, parseAfterCallEvent, PayloadTooLargeError, WebhookPayloadError, type AfterCallSummaryEvent, type UnknownEvent } from '@intelligence-cloud/sdk';
const TOKEN = process.env.IC_WEBHOOK_TOKEN!; // 32+ random characters
const dedup = new Deduplicator(); // per process; pass { store } to share one across instances
function tokenOk(t: string) {
const a = Buffer.from(t), b = Buffer.from(TOKEN);
return a.length === b.length && timingSafeEqual(a, b);
}
export async function POST(req: Request, { params }: { params: Promise<{ token: string }> }) {
const { token } = await params;
if (!tokenOk(token)) return new Response(null, { status: 404 });
let event: AfterCallSummaryEvent | UnknownEvent;
try {
event = parseAfterCallEvent(await req.text()); // validates the shape; 256 KB at most
} catch (err) {
if (err instanceof PayloadTooLargeError) return new Response(null, { status: 413 });
if (err instanceof WebhookPayloadError) return new Response(null, { status: 400 });
throw err;
}
if (isUnknownEvent(event)) return new Response(null, { status: 204 }); // a type you don't handle
if (!event.is_test && !(await dedup.isDuplicate(event.call.id))) {
await enqueue(event.call.id); // your queue; never log the body
}
return new Response(null, { status: 204 }); // well inside 2 seconds
}
<?php
// public/ic-webhook.php, routed from /ic/after-call/{token}
require __DIR__ . '/../vendor/autoload.php';
use IntelligenceCloud\Exception\{PayloadTooLargeError, WebhookPayloadError};
use IntelligenceCloud\Webhook\{Deduplicator, UnknownEvent, Webhooks};
$token = basename(parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH));
if (!hash_equals((string) getenv('IC_WEBHOOK_TOKEN'), $token)) { http_response_code(404); exit; }
try {
$event = Webhooks::parseAfterCallEvent(file_get_contents('php://input')); // 256 KB at most
} catch (PayloadTooLargeError) {
http_response_code(413); exit;
} catch (WebhookPayloadError) {
http_response_code(400); exit; // validates the shape
}
if ($event instanceof UnknownEvent) { http_response_code(204); exit; } // a type you don't handle
$dedup = new Deduplicator($sharedStore); // your DedupStore over a database or cache
if (!$event->isTest && !$dedup->isDuplicate($event)) {
enqueue($event->callId); // your queue; never log the body
}
http_response_code(204);
import hmac, os
from fastapi import BackgroundTasks, FastAPI, Request, Response
from intelligence_cloud import (AfterCallEvent, Deduplicator, PayloadTooLargeError, WebhookPayloadError,
parse_after_call_event)
app = FastAPI()
TOKEN = os.environ["IC_WEBHOOK_TOKEN"] # 32+ random characters
dedup = Deduplicator() # per process; pass store= to share one across workers
@app.post("/ic/after-call/{token}")
async def after_call(token: str, request: Request, tasks: BackgroundTasks):
if not hmac.compare_digest(token.encode(), TOKEN.encode()):
return Response(status_code=404)
try:
event = parse_after_call_event(await request.body()) # validates the shape; 256 KB at most
except PayloadTooLargeError:
return Response(status_code=413)
except WebhookPayloadError:
return Response(status_code=400)
if not isinstance(event, AfterCallEvent): # a type you don't handle
return Response(status_code=204)
if not event.is_test and not dedup.is_duplicate(event):
tasks.add_task(handle_call, event.call.id) # never log the body
return Response(status_code=204)
handle_call reads the call with ic.intelligence.get_call(call_id) on the frontline client when it needs the detail. Pair every receiver with the nightly catch-up from Delivery.
The TypeScript download's Next.js example takes the token as a path segment: /api/ic-webhook/<IC_WEBHOOK_TOKEN> and /api/ic-alert-webhook/<IC_ALERT_WEBHOOK_TOKEN>. Its calls page and action call requireSignedIn() from lib/auth.ts, which refuses everyone until you wire it to your own sign-in, and limit each viewer to their own locations.
Each download also carries a First Alert receiver in examples/: the same path-token check, then it reads only the alert id from the request, answers 204, and fetches the alert and its call with get_alert(alert_id, with_call=True) (getAlert in PHP and TypeScript) on the frontline client.
Other languages
Generate a client from openapi.yaml (OpenAPI 3.1) with your usual generator, for example:
npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g java -o ./ic-client-java
Then build in the rules a generated client won't know: store each new refresh token before use, send an Idempotency-Key on user create, read-merge-write the full-replacement calls, check connectors every 10 seconds until they settle (for up to 10 minutes), send only documented filters, and never log bodies.
API reference
Every operation, parameter, field and error is in the API reference, generated from openapi.yaml. The index below lists each operation by the credential it needs.
Any credential
Sign in, renew, sign out, and check who is signed in.
| Area | Operations |
|---|---|
| Authentication | POST /auth/login Sign inPOST /auth/refresh Renew the access tokenPOST /auth/logout Sign out |
| Account | GET /me Who is signed inGET /locations Locations this login can see |
Admin credentials
Customer lifecycle. A reseller admin login. Operations marked “company admin too” also accept the customer's own company admin login (customer_admin).
Frontline credentials
Conversation data. A named frontline integration user.
| Area | Operations |
|---|---|
| Calls | GET /calls List callsGET /calls/{callId} Read a callGET /calls/{callId}/transcript Read a call's transcript |
| Alerts | GET /alerts List alertsGET /alerts/dashboard Alert totals |
| Tasks | GET /tasks List tasks |
| Insights | GET /insights/dashboard Insights Hub dashboardGET /insights/topics/{slug}/calls Calls for one topic |
Webhooks
Requests Intelligence Cloud sends to your HTTPS endpoint. Configured with admin credentials.
| Area | Events |
|---|---|
| Events and webhooks | POST After Call summary (end_of_call_summary)POST First Alert (location webhook) |
API reference
Every operation with its parameters, bodies, responses and examples.
Integration Recipes
Thirteen ready-to-run integrations in curl, Python, PHP and TypeScript.
Reseller Admin Guide
The same configuration in the Admin UI, with worked customer examples.
Partner Launch Guide
What each team owns for launch, from naming to support.
| You need | Go to |
|---|---|
| An admin integration login | Your Tresic partner contact |
| Help with an integration | support@tresic.cloud or your Tresic contact, 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 or a webhook address | security@tresic.cloud, straight away, copying your Tresic contact. Rotate the affected credentials. |
| Report a vulnerability in Intelligence Cloud or the SDKs | security@tresic.cloud, with the steps to reproduce it. See the vulnerability disclosure policy. |
| Security documentation: certifications, penetration test summary, data location, subprocessors, BAA | security@tresic.cloud |