NUACOM API

Calls

Call AI

Call AI is what NUACOM extracts from a call recording once it has been transcribed: a summary, the conversation split by channel, the topics discussed, the action items and the overall sentiment. This group holds two read-only endpoints, one for a single call and one for every call of a period. The full transcript with timings, talk time and search lives in Speech To Text, the audio in Call Recording, and the call ids you need come from Call Logs.

Workflow (what the portal does)

  1. Find the call: take call_id from a GET /v2/call-log row that has recording: true. call_id is the telephony id shared by every leg of a call; call_unique_id is not accepted here.
  2. One call: GET /v2/calls/{callId}/ai-data answers the object described below. It is JSON unless you ask for XML with an Accept header containing application/xml or text/xml, or with ?format=xml. format accepts only json and xml; anything else answers 422.
  3. A period: GET /v2/calls/ai-data with date_from and date_to, both required, as Y-m-d or Y-m-d H:i:s (a bare date spans the whole day), at most 31 days apart and date_to not before date_from; page (default 1) and per_page (1–100, default 25). It answers {"data": [...], "meta": {"page", "per_page", "total"}}; each item is the object below plus callId and callDate. This endpoint is JSON only.
curl 'https://api.api-nuacom.com/v2/calls/svr13-core2-1753839825.12345/ai-data' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "summary": "Megan from NUACOM asked for Brian about a telecommunications offer; he was unavailable, so she left a message asking to be called back.",
  "transcription": [
    {"channel": 1, "text": "Good morning, Mullen and Sons."},
    {"channel": 0, "text": "Hi, is Brian available?"},
    {"channel": 1, "text": "He is not, can I take a message?"}
  ],
  "topics": ["Callback request", "Telecommunications"],
  "actionItems": ["Brian to call Megan back"],
  "averageSentiment": "neutral"
}

Reading the response

Field Content
summary A few sentences describing the call.
transcription The utterances in order, each {"channel": <int>, "text": "..."}; the channel separates the two parties of the recording.
topics Short labels for what was discussed.
actionItems Follow-ups extracted from the conversation.
averageSentiment The tone of the whole call: positive, neutral or negative; Unknown when none was computed.

In XML the root element is <aiData>; transcription entries are <item> elements with <channel> and <text>, topics entries are <topic> and actionItems entries are <actionItem>.

Enabling AI data

A call gets AI data when it was recorded and the account had an active AI Analysis add-on at the time:

  • Unlimited AI Call Analysis: every recorded call is analysed.
  • Free AI Call Analysis: an allowance of minutes, reset monthly. The duration of each analysed call is deducted from it, and new calls are no longer analysed once it is used up.

GET /v2/speech-to-text/active tells you which one is active; an admin switches them with the subscription endpoints described in Speech To Text. Analysis runs in the background after the recording is stored, so the data for a call that has just ended arrives later.

Roles and access

  • Any authenticated user can call both endpoints.
  • The single-call endpoint applies the recording rules: account admins may read any call; other users need the Call Recording Access setting on their user, and the call must be visible to them (on their own extension, or on the numbers, extensions and queues granted to them; a user whose call-log permission is "all" sees every call). A call outside that scope, including an id that does not exist, answers 403.
  • The period endpoint has no per-user filter: it returns the AI data of every call of the account.
  • Accounts that opted out of recording with the No Recordings add-on get 403 from both endpoints.

Pitfalls

  • 404 with {"message": "No AI data available for this callId"} covers every "nothing to show" case: an unknown id (for an admin), a call that was not recorded, not analysed yet, recorded before the add-on was active, or whose analysis failed. There is no "pending" state to tell them apart.
  • A recording too short to summarise still answers 200: summary is then the placeholder Unable to summarize. Recording is too short or lacks conversational content.. Check for it before showing the summary.
  • date_from and date_to are compared with the stored call date, which is Irish time (Europe/Dublin); X-Timezone is not read. callDate in the response is UTC ISO 8601 (2026-06-01T09:00:00.000000Z).
  • meta.total counts the account's call-log rows in the period, not the items returned. Rows without AI data are skipped, so a page can carry fewer than per_page items, even none, while later pages still do. Walk every page up to total / per_page instead of stopping at an empty one.
  • A call with several legs (transfers, queue legs) has several call-log rows sharing one call_id, and each row yields an item: the same analysis can appear more than once in a page. De-duplicate on callId.
  • format=xml on the period endpoint does nothing; only the single-call endpoint speaks XML.