QVOICE Platform Object in Call Detail Records (CDRs)¶

This document describes the platform queue CDR extension object that appears in Call Detail Records (CDRs) when calls are handled by the QVOICE Platform queue application. The structure is written asynchronously by the queues app after call end and is used for reporting, abandoned-call logic, agent history, and campaign attribution.

Overview¶

The fonoUC object is a top-level key on the CDR document stored in the account database. It is only present when the call was processed by the QVOICE Platform queues application (inbound queue, outbound queue, or campaign). It can contain one or more of the following sub-objects:

Sub-object	Present when	Purpose
`cc`	Inbound queue call (customer leg)	Inbound queue metadata, agent history, timings
`cc_outbound`	Outbound / agent leg of a queue call	Agent-leg metadata, agent history
`cc_campaign`	Campaign (preview/progressive) call	Campaign id, lead, disposition, flags

Important: The fonoUC object may be missing if the CDR is read immediately after call end, because the queues app writes it asynchronously. Consumers should implement retries or a short delay when fetching CDRs by call_id after receiving a call-end event.

1. `cc` — Inbound queue (customer leg)¶

Present on the customer’s CDR for inbound queue calls. Contains queue name, timings, and agent history for that customer interaction.

Field	Type	Description
`account`	string	Account ID.
`queue_name`	string	Queue name.
`queue_id`	string	Queue ID (when available).
`called_time`	number	Unix timestamp when the customer entered the queue.
`answered_time`	number or `null`	Unix timestamp when an agent answered; `null` if no agent answered (abandoned).
`hangup_time`	number	Unix timestamp when the call ended.
`transferred_on_digit`	boolean	`true` if the call was transferred (e.g. by DTMF) instead of answered in queue.
`queue_history`	array	Queue-related history entries (e.g. queue transactions).
`agent_history`	array	List of agent events (see Agent history entries).
`agent_outbound_and_inbound`	boolean	Set when an outbound call was transferred into an inbound queue (caller/callee flip).
`state`	number	Internal queue state.
`csat`	boolean	Whether CSAT was applicable.
`recording_recover`	any	Recording recovery reference.
`recording_file`	any	Recording file reference.
`conf_id`	string	Conference ID for the queue call.
`callid`	string	Call UUID (customer leg).
`agent_callid`	string	Agent leg call UUID (when applicable).
`customer_callid`	string	Customer leg call UUID.

Abandoned call: A call is considered abandoned when no agent ever answered (and it was not transferred on digit). The api/v2/reports/queues_cdrs endpoint sets the response field abandoned to "Yes" or "No" using: abandoned = "Yes" when answered_time is 0 (or missing) and transferred_on_digit is false; otherwise abandoned = "No". In the queues app, answered_time is set when an agent joins the call (at the same time an agent_enter event is appended to agent_history), so “no agent ever answered” corresponds to no agent_enter and to answered_time == 0; the report uses the latter two fields, not a scan of agent_history.

2. `cc_outbound` — Outbound / agent leg¶

Present on the agent’s CDR for queue outbound calls (or when the agent leg is enriched). Mirrors the structure used for reporting and linking to the customer leg.

Field	Type	Description
`account`	string	Account ID.
`account_name`	string	Account display name.
`callid`	string	Call UUID (this leg).
`agent_callid`	string	Agent leg call UUID.
`customer_callid`	string	Customer leg call UUID.
`queue_name`	string	Queue name.
`state`	number	Internal state.
`answered_time`	number	Unix timestamp when the call was answered.
`transferred_on_digit`	boolean	Whether the call was transferred on digit.
`csat`	boolean	Whether CSAT was applicable.
`called_time`	number	Unix timestamp when the call was placed.
`hangup_time`	number	Unix timestamp when the call ended.
`conf_id`	string	Conference ID.
`recording_recover`	any	Recording recovery reference.
`recording_file`	any	Recording file reference.
`queue_history`	array	Queue history.
`agent_history`	array	List of agent events (see Agent history entries).
`history_only`	boolean	If `true`, the payload only appends to existing `agent_history` (e.g. outbound then transferred to queue).

3. `cc_campaign` — Campaign calls¶

Present for campaign (preview or progressive) calls. Contains campaign id, lead, and disposition.

Field	Type	Description
`account`	string	Account ID.
`account_name`	string	Account display name.
`callid`	string	Call UUID (lead/customer leg).
`queue_name`	string	Queue name.
`campaign_id`	string	Campaign ID.
`mask_lead_caller_id`	boolean	Whether lead caller ID was masked.
`callback_lead`	boolean	Whether this was a callback lead.
`agent_marked_as_voicemail`	boolean	Agent marked as voicemail.
`campaign`	object	Campaign configuration snapshot.
`lead`	object	Lead document (id, status, number, etc.).
`disposition`	string	Disposition or hangup cause.
`skip_media_check`	boolean	If `true`, skip recording/media checks.
`agent`	boolean	Whether an agent was involved.
`agent_outbound_and_inbound`	boolean	Outbound call transferred into inbound queue.

4. Agent history entries¶

agent_history is an array of objects. Each entry represents one event (agent answered, left, hung up, or transfer). The queues app appends these in real time during the call.

Common fields (all event types)¶

Field	Type	Description
`type`	string	Usually `"agent"`.
`last_attempt`	number	Unix timestamp of the event.
`ext`	string	Agent extension.
`queue_name`	string	Queue name.
`event`	string	Event type (see below).
`email`	string	Agent email.
`first_name`	string	Agent first name.
`last_name`	string	Agent last name.
`queue_id`	string	Queue ID (when available).
`uuid`	string	Call UUID of the agent leg.

Event types (`event`)¶

Value	When it is written	Meaning
`agent_enter`	When an agent joins the conference and is connected to the customer	Agent answered the call.
`agent_left`	When an agent leaves the conference (e.g. transfer)	Agent left before the customer hung up.
`agent_hangup`	When the agent’s leg is the one that leaves (del-member)	The agent ended the call.
`transfer_enter`	When the joining agent is in an attended transfer	New agent entered via transfer.
`answer`	Outbound: when the customer answers	Outbound call answered.
`dial`	Outbound/campaign dial attempt	Dial attempt.

Semantics:

Abandoned: No agent ever answered. In the queues app there is no agent_enter in agent_history (and answered_time stays 0). The report API api/v2/reports/queues_cdrs does not use agent_history; it sets abandoned to "Yes" when answered_time == 0 and transferred_on_digit == false, and to "No" otherwise. Outcome is equivalent because the queues app sets answered_time when an agent answers (same moment as agent_enter).
Agent hung up: There is an agent_hangup entry → the agent’s leg ended the call.
Customer hung up: Call ended and there is no agent_hangup → the customer (or other party) ended the call.

Optional fields (event-specific)¶

Field	Type	Description
`connected`	string	e.g. `"True"` when the agent is connected.
`hangup`	string	e.g. `"True"` for hangup events.
`agent_hungup_on_customer`	string	`"True"` when the agent hung up (agent_hangup event).
`to_did`	string	Destination number (e.g. outbound).
`customer_uuid`	string	Customer leg UUID.
`answered_time`	number	When the leg was answered.

5. Other top-level keys under `fonoUC`¶

These can be set by the queues app or by consumers:

Key	Type	Description
`cdr_push`	boolean	Whether the CDR was pushed to the configured URL.
`cdr_push_url`	string	URL used for CDR push.
`Quality`	object	Quality metrics (when available).

6. Call scenarios and which sub-objects appear¶

Scenario	`cc`	`cc_outbound`	`cc_campaign`
Inbound queue, customer leg	✓	—	—
Inbound queue, agent leg	—	✓ (optional)	—
Outbound queue (agent-originated)	—	✓	—
Outbound then transferred to queue	✓ (customer leg)	✓ (agent leg, possibly `history_only`)	—
Campaign (preview/progressive)	—	—	✓
Campaign + queue	✓ / cc_outbound	✓	✓

7. API and storage¶

Fetching by call_id: Use the per-leg CDR API (e.g. GET /v2/accounts/{account_id}/cdrs/legs/{call_id}) and read the fonoUC field from the leg document(s). The customer leg usually has cc; the agent leg may have cc_outbound.
Timing: Because enrichment is asynchronous, fonoUC may be missing if the CDR is read right after hangup. Implement a short delay or retries when using call-end events to fetch CDRs.