Calls

Keyword Tracker

A keyword tracker watches the transcripts of your recorded calls for words or phrases. When a call matches, the tracker tags the call and emails the people you chose, with the summary and the matching lines of the transcript. Trackers run on the transcript and analysis NUACOM produces for a recorded call, so they need the AI Analysis add-on described in Speech To Text; the summary, topics and action items they search are the ones Call AI returns. This group holds the list, create, show, update and delete of a tracker and a switch to enable or disable one.

Workflow (what the portal does)

List: GET /v2/keyword-trackers answers every tracker of the account as a plain array; there is no paging and no filter. Each item is id, tracker_name, account_id, keywords, is_active, filters, email_alerts and tag_ids (the tag ids as a list of strings).
Create: POST /v2/keyword-trackers with:
- tracker_name (required, at most 255 characters);
- keywords (required, at most 1024 characters): the rule, see Writing the rule;
- is_active (required boolean);
- filters: whose calls are watched, a list of {"id": …, "group": …} entries, see Who is watched, who is told;
- email_alerts: who receives the alert, the same shape;
- tags: ids from the call tag catalogue (GET /v3/call-tags), as strings; they are attached to every call the tracker matches. The answer is the tracker as the list shows it.
Show: GET /v2/keyword-trackers/{trackerId}. An id that is not one of your account's trackers answers 404.
Update: PUT /v2/keyword-trackers/{trackerId} takes the same body as create and replaces the whole tracker: a list you leave out becomes empty.
Enable or disable: PATCH /v2/keyword-trackers/{trackerId}/status/{status} with 1 to enable or 0 to disable (any number other than 1 disables). It answers the tracker; a disabled tracker is kept but never matches.
Delete: DELETE /v2/keyword-trackers/{trackerId} answers 204, also for an id that does not exist.

curl -X POST 'https://api.api-nuacom.com/v2/keyword-trackers' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "tracker_name": "Cancellation risk",
    "keywords": "\"cancel\" | \"switch provider\"",
    "is_active": true,
    "filters": [{"id": "d12", "group": "User groups"}],
    "email_alerts": [{"id": "4821", "group": "Users"}],
    "tags": ["1001"]
  }'

{
  "id": 7,
  "tracker_name": "Cancellation risk",
  "account_id": "IE-00123",
  "keywords": "\"cancel\" | \"switch provider\"",
  "is_active": true,
  "filters": [{"id": "d12", "group": "User groups"}],
  "email_alerts": [{"id": "4821", "group": "Users"}],
  "tag_ids": ["1001"]
}

How a tracker runs

A tracker is evaluated once per call, when the transcript and analysis of the recording have been stored, some time after the call ends (Speech To Text explains when a call is transcribed). A call that has no transcript, no extension, or an extension that is not linked to a user is never checked.

For each active tracker:

The rule is tested against the summary followed by the full transcript, and separately against each topic and action item. The tracker matches when either test passes.
filters decides whether the call is one you watch. With an Everyone entry every call of the account is watched; otherwise the extension on the call, the caller's or the called party's, must belong to one of the listed users or to a member of one of the listed teams. An empty list watches nobody.
On a match, the tracker's tags are attached to the call (a tag already on it is not duplicated); they then show on the call row and in GET /v2/call-tags. Then one email goes to each user in email_alerts and to each member of the teams listed there; suspended users are skipped. The email names the tracker, the user on the call and the other party, gives the date and time and a link to the call, and shows the summary with the matched terms highlighted plus up to 12 lines of the transcript from the first highlighted line.

Who is watched, who is told

filters and email_alerts hold the same kind of entries, each with a required id and group, both strings of at most 50 characters:

`group`	`id`	Meaning
`Users`	the user's `user_id`, as a string (`"4821"`)	that user's calls are watched, or that user is emailed
`User groups`	`d` followed by the team id (`"d12"`)	every member of the team
`Everyone`	required but not read; send `"0"`	every call of the account. Only meaningful in `filters`

The d prefix on id is what makes an entry a team; group is a label the API stores for you and acts on only when it is Everyone. User ids come from GET /v3/users, team ids from GET /v3/teams; see Users.

Writing the rule

keywords is one rule in the syntax below. Terms are matched as whole words, so "cancel" does not match "cancellation".

Rule	Matches when
`invoice`	the word appears. A bare term must be written in lower case; the text is compared in lower case
`"late payment"`	the phrase appears, in any case
`"invoice" + "refund"`	both appear
`"invoice" \| "refund"`	either appears
`-"refund"`	the term is absent
`"invoice" + (-"refund")`	the first appears and the second is absent

| is applied last: "a" + "b" | "c" means (a and b) or c. Parentheses only wrap a single term, as in (-"b"); they cannot regroup an |. The characters + and | always split the rule, even inside quotes. A rule that starts with - has to pass both tests, the text and the topics, so combine a negation with a positive term rather than using it alone.

Roles and access

Every endpoint of this group works on the account your API key belongs to, and any user of that account may call it: there is no account-admin check. A tracker belongs to the account, not to the user who created it.
Alerts and tags only happen for calls that are transcribed: the account needs an active AI Analysis add-on (GET /v2/speech-to-text/active) and, with the Free add-on, an allowance that is not used up. Without it the trackers are stored but never match.
The recipients are not checked against call-log or recording permissions: everyone you list receives the transcript excerpt.

Pitfalls

Ids are strings: "tags": [1001] or {"id": 12, …} answers 422; send "1001" and "12".
PUT replaces everything. Leave tags out and the tracker ends with no tags, answered as tag_ids: [""] rather than []; a tracker created without tags answers the same.
An empty filters list matches no calls. To watch every call add {"id": "0", "group": "Everyone"}.
Everyone in email_alerts emails nobody; list the users or teams.
A tracker with no recipients still tags the matching calls.
Commas are not separators: invoice,refund is matched as that literal text. Use "invoice" | "refund".
A bare term with a capital letter never matches; quote it or write it in lower case.
Trackers are evaluated once, when the analysis is stored. Editing or enabling a tracker does not re-check earlier calls.
DELETE answers 204 for an id that does not exist, so a mistyped id looks like success.

Workflow (what the portal does)#

How a tracker runs#

Who is watched, who is told#

Writing the rule#