Evalgent
Back to Blog
Voice AI Testing

Voice Call Event Schema: A Field-by-Field Reference

Deepesh Jayal
14 min read
Voice Call Event Schema: A Field-by-Field Reference
On this page

A support lead asks why one call went wrong. The engineer finds a transcript, a start time and nothing else. No model version, no end reason, no clock source. The record was never designed.

This post is the reference for that design. It gives a voice call event schema you can adopt: one call record and one turn event. Each field has a type, an example, a reason and a raw-storage verdict. These voice agent call record fields are a vendor-neutral design for your own pipeline. Every name is suggested. A standard OpenTelemetry name is mapped only where one exists. As of November 21, 2026, the GenAI conventions are in Development status.

For the reasoning about what to log, read what to log on every voice agent call. For span-level fields, read voice agent span attributes. This post is the flat table you hand to the team that writes the voice agent event schema.

Evalgent Observe, which is launching, ingests OpenTelemetry-format data from any stack, plus an upload path for call details. These names are not an Evalgent schema, and you do not need to match them.

Reading the tables

Each row has five columns. The name is suggested. The type is the type in a JSON record. The example is invented. The last column is the raw-storage verdict.

VerdictMeaning
yesSafe to store raw. It is a number, an enum, a flag or a random ID you generated.
keyedStore raw only with access control, because it links to another system.
hashStore a keyed hash, so you can count repeats without keeping the value.
maskStore a partial value, such as the last four digits.
noDo not store raw. Keep it out of the record, or redact it first.

The prefix is voice. throughout. It is yours to change. The semantic conventions naming guide asks for a prefix of your own, not an OpenTelemetry namespace.

Two record levels keep the schema small. The call record is written once per call. The turn event is written once per exchange. Put each field at the lowest level where it is true.

Two levels of the schema: one call record holding identity, outcome, version and consent groups, and many turn events holding timing, tool, token and error groups.

Identifiers and clocks

Identifiers join systems. Clocks decide whether the join can be trusted. The call ID correlation post covers how to build the join.

Field (suggested)TypeExampleWhy it existsRaw?
voice.call.idstringc_7f3a91One key every system can join on. Generate it yourself.yes
voice.trace.idstring, 32 hex4bf92f35...4736Opens the trace from the record.keyed
voice.provider.call_idstringCA0123...cdefJoins to the carrier or telephony record.keyed
voice.leg.parent_idstring or nullnullLinks a transfer or dialed leg to its first leg.keyed
voice.tenant.idstringclinic-042Slices every metric by customer.yes
voice.caller.refstringh_2c9e...Keyed hash of the caller number. Finds repeat callers.hash
voice.caller.number_maskedstring***0100Lets a reviewer recognise a call without the number.mask
voice.call.started_atstring, RFC 33392026-11-21T09:14:03.120ZStart of the call, in UTC.yes
voice.call.ended_atstring, RFC 33392026-11-21T09:15:41.870ZEnd of the call, in UTC.yes
voice.clock.sourceenumntp_wallWhich clock stamped this record.yes

Trace IDs. The W3C Trace Context Recommendation defines a trace ID as 32 lowercase hex characters and a span ID as 16. An all-zero value is invalid. The OpenTelemetry logs data model, which has Stable status, carries both as TraceId and SpanId.

Provider IDs. The Twilio Call resource has a sid of 34 characters starting with CA, and a parent_call_sid for the call that created a leg. Store the provider's value in its own field, because one call can have several legs.

Timestamps. RFC 3339 defines the date-time form 2026-11-21T09:14:03.120Z. A Z suffix means UTC. A numeric offset such as -08:00 is local time minus UTC. The RFC reserves -00:00 for "UTC known, local offset unknown." Twilio returns RFC 2822 dates, so convert on ingest.

Clock source. The logs data model separates Timestamp, the origin clock's time, from ObservedTimestamp, when the collector saw the event. Record which clock stamped each value. The timestamp alignment post explains why two correct clocks disagree.

Call record: direction, disposition and end reason

These fields say what kind of call it was and how it ended. They are cheap to record and often queried. Keep each a short closed list.

Field (suggested)TypeExampleWhy it existsRaw?
voice.call.directionenuminboundInbound and outbound fail in different ways.yes
voice.call.transportenumpstnWhich path carried the media: pstn, sip or webrtc.yes
voice.call.setup_outcomeenumconnectedSeparates calls that never started from calls that went wrong.yes
voice.call.answered_byenumhumanHuman, machine or unknown, where detection ran.yes
voice.call.duration_msint98750Cost and long-call queries.yes
voice.call.end_reasonenumcaller_hangupWho or what ended the call.yes
voice.call.outcomeenumbookedThe business result, from your own list.yes

Direction is not a standard attribute. The Twilio resource lists inbound, outbound-api and outbound-dial, and adds trunking values for SIP trunks. Collapse provider values into your own two.

The network.transport attribute is Stable, but it names the OSI transport, with values such as tcp and udp. It does not say PSTN, SIP or WebRTC. Keep voice.call.transport as your own field.

Give the end reason a closed list, such as caller_hangup, agent_hangup, transfer, timeout and error. Free text breaks every dashboard. Keep the call disposition, the business outcome, separate. A call can end by caller hangup and still succeed.

Versions and provider per layer

A failure after a deploy needs a version to prove it. A failure that clusters on one vendor needs the vendor name. Record both on the call record.

Field (suggested)TypeExampleWhy it existsRaw?
voice.agent.namestringschedulerWhich agent took the call.yes
voice.agent.versionstring2026-11-12.3Did the failure start with a release?yes
voice.prompt.hashstringp_91abCatches an edit inside one version label.yes
voice.languagestringen-USLanguage setting in force.yes
voice.stt.providerstringstt-vendor-aFailures that cluster on one recognizer.yes
voice.stt.modelstringmodel-xModel or tier, next to the provider.yes
voice.llm.providerstringllm-vendor-bFailures that cluster on one model host.yes
voice.llm.model_requestedstringmodel-yWhat the config asked for.yes
voice.llm.model_servedstringmodel-y-2026-10What answered. Providers can differ.yes
voice.tts.providerstringtts-vendor-cFailures that cluster on one synthesizer.yes
voice.tts.voice_idstringv_amberA voice change that matches complaints.yes

The vendor values above are placeholders.

The GenAI agent spans page defines gen_ai.agent.name and gen_ai.agent.version. Both are conditionally required, and the page is Development status. The client inference page defines gen_ai.provider.name, gen_ai.request.model and gen_ai.response.model. It defines nothing for speech recognition or synthesis, so the stt and tts rows stay your own.

Keep requested and served model apart. A router or fallback can change the model behind a stable name.

Turn event: timing fields

A turn is one exchange. Callers feel its timing fields as "it paused" or "it talked over me." Record offsets in milliseconds from call start, on one clock. Derive the gaps once.

Field (suggested)TypeExampleWhy it existsRaw?
voice.turn.indexint4Orders turns and joins to artifacts.yes
voice.turn.caller_speech_end_msint12400Anchor for the response gap.yes
voice.turn.endpoint_decided_msint12700When the agent decided the caller had finished.yes
voice.turn.llm_first_token_msint13150First token of the spoken reply.yes
voice.turn.tts_first_audio_msint13480First agent audio produced.yes
voice.turn.response_gap_msint1080First audio minus caller speech end.yes
voice.turn.interruptedboolfalseDid the caller cut the agent off?yes
voice.turn.stop_delay_msint or nullnullTime from caller onset to playback stopping.yes

The response gap crosses three stages, so no single span holds it. Compute it once, in code that sees every timestamp, and define it in the schema file. The time to first audio post breaks the gap down. For overlap and barge-in, see interruption rate.

None of these voice agent turn event fields has a standard name. The GenAI pages I read define no turn, endpointing or playback attributes. The GenAI conventions post lists what exists.

Illustrative turn timeline in milliseconds from call start: caller speech ends at 12400, endpoint decided at 12700, first token at 13150, first audio at 13480, response gap 1080.

Turn event: tool, handoff, count and error fields

This group explains why a turn failed, not only that it was slow. Counts replace content, so only one field is hashed.

Field (suggested)TypeExampleWhy it existsRaw?
voice.tool.namestringlookup_orderWhich tool ran.yes
voice.tool.call_idstringtc_01Joins the request to its result.yes
voice.tool.latency_msint340A slow tool looks like dead air.yes
voice.tool.outcomeenumsuccessSuccess, error, timeout or cancelled.yes
voice.tool.retry_countint0Repeated calls hide behind one outcome.yes
voice.tool.args_hashstringa_55d0Spots a repeated call without storing the arguments.hash
voice.tool.result_charsint212An empty result looks like success without it.yes
voice.handoff.typeenumhumanAgent, human or queue target.yes
voice.handoff.reasonenumcaller_requestWhy control moved.yes
voice.handoff.outcomeenumconnectedDid the receiving side pick up?yes
voice.handoff.context_passedbooltrueDid the caller have to repeat themselves?yes
voice.llm.input_tokensint3120Context growth across turns.yes
voice.llm.output_tokensint64Reply length for speech.yes
voice.stt.transcript_charsint38Tiny transcript, long audio: a visible mismatch.yes
voice.error.typestringtimeoutShort class of failure.yes
voice.error.stageenumtoolWhich layer failed: stt, llm, tool, tts or telephony.yes
voice.error.provider_codestring429The provider's own code.yes

The execute tool page, in Development status, defines gen_ai.tool.name as required and gen_ai.tool.call.id as conditionally required. It marks gen_ai.tool.call.arguments and gen_ai.tool.call.result as opt-in, and warns they may hold sensitive data. The same page defines gen_ai.transfer.mode and gen_ai.transfer.target.name for tool calls that transfer work to another agent. It defines nothing for transfers to a human, so the handoff rows stay yours.

The inference page defines gen_ai.usage.input_tokens and gen_ai.usage.output_tokens as integers. It also defines gen_ai.response.finish_reasons, a string array.

error.type is Stable. The registry says it should be predictable and low cardinality, and that it should not be set on success. It suggests a domain-specific attribute for your own error identifiers, with error.type still set. That is why voice.error.provider_code sits beside voice.error.type.

Keep metric labels to bounded enums such as version, provider and outcome, never a call ID. Read per-call values from the records. The tool call tracing post and the handoff tracing post cover the spans behind these rows.

These fields prove what happened around the call without carrying the audio. Store a recording reference, not the recording.

Field (suggested)TypeExampleWhy it existsRaw?
voice.recording.refstringrec_8d21Opaque ID resolved by a service with access control.keyed
voice.recording.start_offset_msint120Maps a trace time to a position in the audio.yes
voice.recording.channelsstringcaller:L,agent:RWhich party is on which channel.yes
voice.recording.storedbooltrueSeparates "no recording" from "lost recording."yes
voice.consent.statusenumobtainedobtained, declined, not_asked or unknown.yes
voice.consent.policy_refstringpolicy-7Which rule set applied, by your own ID.yes
voice.disclosure.ai_playedbooltrueWas the AI disclosure delivered?yes
voice.disclosure.at_msint or null1500When it played, from call start.yes

The recording link post covers offsets and channels. The recording consent post and the AI disclosure post cover what to capture and why.

Consent rules depend on where the parties are. In the US, the FCC issued a declaratory ruling on February 2, 2024 confirming that AI-generated voices count as an "artificial or prerecorded voice" under the TCPA, so prior express consent rules apply. This is not legal advice. Ask counsel which flags your calls need, and record the answer as data.

Which fields are safe to store raw

The verdicts above follow four classes.

Four classes of call fields and their storage verdict: IDs, enums, counts raw; provider IDs and references with access control; caller identifiers hashed or masked; content never raw.

Raw. Enums, counts, durations, flags, versions and IDs you generated. They carry no content. Most of the schema lives here.

Raw with access control. Provider call IDs, trace IDs and recording references. They are harmless alone, but they open other systems. Restrict who can resolve them.

Hash or mask. Caller numbers and any account or user ID. A plain hash of a phone number can be guessed by hashing every possible number, so use a keyed hash. Twilio marks caller_name as PII with a 120-day retention limit.

Never raw. Transcript text, tool arguments and results, audio, names, dates of birth and card numbers. The OpenTelemetry GenAI pages mark message content and tool arguments as opt-in for this reason. Keep lengths and hashes in the record. Put content in a separate store. The PII redaction post covers where to mask.

One illustrative record

This example is invented, and valid JSON. It shows one call record and one turn event, using only the suggested names above. The turn matches the timeline diagram.

{
  "call_record": {
    "voice.call.id": "c_7f3a91",
    "voice.trace.id": "4bf92f3577b34da6a3ce929d0e0e4736",
    "voice.provider.call_id": "CA0123456789abcdef0123456789abcdef",
    "voice.leg.parent_id": null,
    "voice.tenant.id": "clinic-042",
    "voice.caller.ref": "h_2c9e",
    "voice.caller.number_masked": "***0100",
    "voice.call.started_at": "2026-11-21T09:14:03.120Z",
    "voice.call.ended_at": "2026-11-21T09:15:41.870Z",
    "voice.clock.source": "ntp_wall",
    "voice.call.direction": "inbound",
    "voice.call.transport": "pstn",
    "voice.call.setup_outcome": "connected",
    "voice.call.duration_ms": 98750,
    "voice.call.end_reason": "caller_hangup",
    "voice.call.outcome": "booked",
    "voice.agent.name": "scheduler",
    "voice.agent.version": "2026-11-12.3",
    "voice.llm.model_requested": "model-y",
    "voice.llm.model_served": "model-y-2026-10",
    "voice.recording.ref": "rec_8d21",
    "voice.consent.status": "obtained",
    "voice.disclosure.ai_played": true
  },
  "turn_event": {
    "voice.call.id": "c_7f3a91",
    "voice.turn.index": 4,
    "voice.turn.caller_speech_end_ms": 12400,
    "voice.turn.endpoint_decided_ms": 12700,
    "voice.turn.llm_first_token_ms": 13150,
    "voice.turn.tts_first_audio_ms": 13480,
    "voice.turn.response_gap_ms": 1080,
    "voice.turn.interrupted": false,
    "voice.tool.name": "lookup_order",
    "voice.tool.latency_ms": 340,
    "voice.tool.outcome": "success",
    "voice.llm.input_tokens": 3120,
    "voice.llm.output_tokens": 64
  }
}

The endpointing wait is 300 ms, from 12400 to 12700. The response gap is 1080 ms, from 12400 to 13480. Both derive from stored offsets, so neither can drift.

Fields with a standard OpenTelemetry name

This is the full mapping of OpenTelemetry semantic conventions I found. Everything else here is your own convention. As of November 21, 2026, each page reads Development status unless marked.

Suggested fieldOpenTelemetry nameStatus as read
voice.call.idgen_ai.conversation.idDevelopment
voice.agent.name, voice.agent.versiongen_ai.agent.name, gen_ai.agent.versionDevelopment
provider per layer (LLM only)gen_ai.provider.nameDevelopment
voice.llm.model_requested, voice.llm.model_servedgen_ai.request.model, gen_ai.response.modelDevelopment
voice.llm.input_tokens, voice.llm.output_tokensgen_ai.usage.input_tokens, gen_ai.usage.output_tokensDevelopment
voice.tool.name, voice.tool.call_idgen_ai.tool.name, gen_ai.tool.call.idDevelopment
voice.error.typeerror.typeStable
voice.trace.idTraceId in the logs data modelStable

Two cautions. The gen_ai.* definitions live in the semantic-conventions-genai repository, so read it for current ones. And Development status means names can change, so keep your own field as the stored name and map at export. The span model post shows where each attribute sits on a span.

How to define your voice call event schema in six steps

1. Pick the prefix and the two record levels - Choose one prefix. Decide which fields live on the call record and which on the turn event. Keep the list in your repository.

2. Give every field a type, an example and a verdict - Use the five columns from this post. A field with no raw-storage verdict is not ready to ship.

3. Close every enum - Write the allowed values for direction, end reason, outcome, tool outcome and error stage. Reject anything else at write time.

4. Choose one clock and store offsets - Store call start as RFC 3339 UTC. Store turn times as milliseconds from call start on one clock. Record the clock source.

5. Derive crossing fields once - Compute the response gap and the stop delay in one place. Store the inputs beside them.

6. Replay a staged call and read it back - Place a call with an interruption, a failed tool and a transfer. Check every field is present, bounded and free of content. The state observability post covers extending the schema with flow state.

Where Evalgent fits

A schema only helps if something reads it. Evalgent Observe, which is launching, ingests OpenTelemetry-format data from any stack, plus an upload path for call details. It traces each failure to the step or handoff behind it, and groups failures into root causes. Where your data cannot support a verdict, it says undetermined and shows the coverage gap. It never sits in the media path.

Evalgent Monitor, which is live, flags problems in production calls, with fix recommendations. For testing, Reviews replay a test call with audio and transcript together and show the exact tool payloads. Evalgent also measures call timestamps such as the endpointing decision and first audio. You can see them in a short demo. For the wider picture, see what is voice agent observability and root cause analysis.

Frequently asked questions

What is a voice call event schema?

It is the agreed list of fields recorded for each call and each turn, with a type, allowed values and a storage rule per field. A call record holds whole-call facts. A turn event holds timing, tool, token and error facts for one exchange.

Is there a standard voice call event schema?

Not that I found. As of November 21, 2026, the OpenTelemetry GenAI pages I read define model, agent and tool attributes in Development status. They define no turn, endpointing, telephony or recording attributes. Treat every voice.* name here as a suggestion, and map to standard names only where they exist.

Which fields are safe to store raw?

Enums, counts, durations, flags, versions and IDs you generated. Provider IDs and recording references need access control. Caller numbers should be hashed or masked. Transcripts, tool arguments, audio and names should never be stored raw in the record.

Should I use flat fields or nested objects?

Either works if names stay stable. Flat dotted names map cleanly to OpenTelemetry attributes and log records. Nested objects read better in JSON. Pick one and keep the same names everywhere.

How should I store timestamps in a voice call record?

Store call start and end as RFC 3339 strings in UTC, such as 2026-11-21T09:14:03.120Z. Store turn times as millisecond offsets from call start on one clock. Record the clock source, because two correct clocks can still disagree.

Do I need both a call record and a turn event?

Yes, for most agents. Call-level facts such as version and direction repeat on every turn if you flatten them, which wastes storage and invites drift. Turn-level facts such as timing do not fit one row per call. Join the two on the call ID.

Record what happened as a consent flag and a timestamp: status, the policy ID that applied, and whether and when the AI disclosure played. Do not embed legal text. This is not legal advice, so ask counsel which flags your calls need.

Can I upload this schema's data to an observability tool?

Often, if the tool accepts OpenTelemetry or a file of call details. Keep your own names as the stored form, and map to standard attribute names at export. Check the tool's documentation, since this post does not describe any vendor's format.

The bottom line

A voice call event schema works when every field has a type, an example, a reason and a raw-storage verdict, and when it is split into one call record and one turn event. Store enums, counts and durations raw, hash or mask identifiers, keep content out of the record, and label every name as your own unless OpenTelemetry defines it.

Related Articles