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.
| Verdict | Meaning |
|---|---|
| yes | Safe to store raw. It is a number, an enum, a flag or a random ID you generated. |
| keyed | Store raw only with access control, because it links to another system. |
| hash | Store a keyed hash, so you can count repeats without keeping the value. |
| mask | Store a partial value, such as the last four digits. |
| no | Do 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.

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) | Type | Example | Why it exists | Raw? |
|---|---|---|---|---|
voice.call.id | string | c_7f3a91 | One key every system can join on. Generate it yourself. | yes |
voice.trace.id | string, 32 hex | 4bf92f35...4736 | Opens the trace from the record. | keyed |
voice.provider.call_id | string | CA0123...cdef | Joins to the carrier or telephony record. | keyed |
voice.leg.parent_id | string or null | null | Links a transfer or dialed leg to its first leg. | keyed |
voice.tenant.id | string | clinic-042 | Slices every metric by customer. | yes |
voice.caller.ref | string | h_2c9e... | Keyed hash of the caller number. Finds repeat callers. | hash |
voice.caller.number_masked | string | ***0100 | Lets a reviewer recognise a call without the number. | mask |
voice.call.started_at | string, RFC 3339 | 2026-11-21T09:14:03.120Z | Start of the call, in UTC. | yes |
voice.call.ended_at | string, RFC 3339 | 2026-11-21T09:15:41.870Z | End of the call, in UTC. | yes |
voice.clock.source | enum | ntp_wall | Which 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) | Type | Example | Why it exists | Raw? |
|---|---|---|---|---|
voice.call.direction | enum | inbound | Inbound and outbound fail in different ways. | yes |
voice.call.transport | enum | pstn | Which path carried the media: pstn, sip or webrtc. | yes |
voice.call.setup_outcome | enum | connected | Separates calls that never started from calls that went wrong. | yes |
voice.call.answered_by | enum | human | Human, machine or unknown, where detection ran. | yes |
voice.call.duration_ms | int | 98750 | Cost and long-call queries. | yes |
voice.call.end_reason | enum | caller_hangup | Who or what ended the call. | yes |
voice.call.outcome | enum | booked | The 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) | Type | Example | Why it exists | Raw? |
|---|---|---|---|---|
voice.agent.name | string | scheduler | Which agent took the call. | yes |
voice.agent.version | string | 2026-11-12.3 | Did the failure start with a release? | yes |
voice.prompt.hash | string | p_91ab | Catches an edit inside one version label. | yes |
voice.language | string | en-US | Language setting in force. | yes |
voice.stt.provider | string | stt-vendor-a | Failures that cluster on one recognizer. | yes |
voice.stt.model | string | model-x | Model or tier, next to the provider. | yes |
voice.llm.provider | string | llm-vendor-b | Failures that cluster on one model host. | yes |
voice.llm.model_requested | string | model-y | What the config asked for. | yes |
voice.llm.model_served | string | model-y-2026-10 | What answered. Providers can differ. | yes |
voice.tts.provider | string | tts-vendor-c | Failures that cluster on one synthesizer. | yes |
voice.tts.voice_id | string | v_amber | A 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) | Type | Example | Why it exists | Raw? |
|---|---|---|---|---|
voice.turn.index | int | 4 | Orders turns and joins to artifacts. | yes |
voice.turn.caller_speech_end_ms | int | 12400 | Anchor for the response gap. | yes |
voice.turn.endpoint_decided_ms | int | 12700 | When the agent decided the caller had finished. | yes |
voice.turn.llm_first_token_ms | int | 13150 | First token of the spoken reply. | yes |
voice.turn.tts_first_audio_ms | int | 13480 | First agent audio produced. | yes |
voice.turn.response_gap_ms | int | 1080 | First audio minus caller speech end. | yes |
voice.turn.interrupted | bool | false | Did the caller cut the agent off? | yes |
voice.turn.stop_delay_ms | int or null | null | Time 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.

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) | Type | Example | Why it exists | Raw? |
|---|---|---|---|---|
voice.tool.name | string | lookup_order | Which tool ran. | yes |
voice.tool.call_id | string | tc_01 | Joins the request to its result. | yes |
voice.tool.latency_ms | int | 340 | A slow tool looks like dead air. | yes |
voice.tool.outcome | enum | success | Success, error, timeout or cancelled. | yes |
voice.tool.retry_count | int | 0 | Repeated calls hide behind one outcome. | yes |
voice.tool.args_hash | string | a_55d0 | Spots a repeated call without storing the arguments. | hash |
voice.tool.result_chars | int | 212 | An empty result looks like success without it. | yes |
voice.handoff.type | enum | human | Agent, human or queue target. | yes |
voice.handoff.reason | enum | caller_request | Why control moved. | yes |
voice.handoff.outcome | enum | connected | Did the receiving side pick up? | yes |
voice.handoff.context_passed | bool | true | Did the caller have to repeat themselves? | yes |
voice.llm.input_tokens | int | 3120 | Context growth across turns. | yes |
voice.llm.output_tokens | int | 64 | Reply length for speech. | yes |
voice.stt.transcript_chars | int | 38 | Tiny transcript, long audio: a visible mismatch. | yes |
voice.error.type | string | timeout | Short class of failure. | yes |
voice.error.stage | enum | tool | Which layer failed: stt, llm, tool, tts or telephony. | yes |
voice.error.provider_code | string | 429 | The 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.
Recording, consent and disclosure fields
These fields prove what happened around the call without carrying the audio. Store a recording reference, not the recording.
| Field (suggested) | Type | Example | Why it exists | Raw? |
|---|---|---|---|---|
voice.recording.ref | string | rec_8d21 | Opaque ID resolved by a service with access control. | keyed |
voice.recording.start_offset_ms | int | 120 | Maps a trace time to a position in the audio. | yes |
voice.recording.channels | string | caller:L,agent:R | Which party is on which channel. | yes |
voice.recording.stored | bool | true | Separates "no recording" from "lost recording." | yes |
voice.consent.status | enum | obtained | obtained, declined, not_asked or unknown. | yes |
voice.consent.policy_ref | string | policy-7 | Which rule set applied, by your own ID. | yes |
voice.disclosure.ai_played | bool | true | Was the AI disclosure delivered? | yes |
voice.disclosure.at_ms | int or null | 1500 | When 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.

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 field | OpenTelemetry name | Status as read |
|---|---|---|
voice.call.id | gen_ai.conversation.id | Development |
voice.agent.name, voice.agent.version | gen_ai.agent.name, gen_ai.agent.version | Development |
| provider per layer (LLM only) | gen_ai.provider.name | Development |
voice.llm.model_requested, voice.llm.model_served | gen_ai.request.model, gen_ai.response.model | Development |
voice.llm.input_tokens, voice.llm.output_tokens | gen_ai.usage.input_tokens, gen_ai.usage.output_tokens | Development |
voice.tool.name, voice.tool.call_id | gen_ai.tool.name, gen_ai.tool.call.id | Development |
voice.error.type | error.type | Stable |
voice.trace.id | TraceId in the logs data model | Stable |
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.
How do I handle consent and disclosure fields?
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

How to automate voice agent testing: synthetic callers vs manual QA
Learn how ai test automation replaces manual QA for voice agents. Compare synthetic callers vs human testers, with a 5-step framework to scale without hiring.
Read more
AI Agent Testing vs Voice Agent Testing: What General Tools Miss for Voice
AI agent testing measures text outputs. Voice agent testing measures behaviour through an acoustic pipeline. Five failure categories general tools miss.
Read more